Scripts

7. Scripts

7.1. Overview

Scripts elements allows to develop simple client-side logic. Using scripts, developers can create basic view logic like enabling or disabling fields, change ribbon buttons, fire view events etc...

7.1.1. 'script' tag structure

To insert script to component use xml 'script' tag:

<script>
      <![CDATA[

           // SCRIPT BODY

      ]]>
</script>

You can add script to every component in system.

7.1.2. language

Scripts are written in JavaScript language, with some additional features and methods (see below)

7.2. Additional language elements

7.2.1. this

Oposite to original JavaScript - 'this' keyword always access component in which script was defined.

7.2.2. access other view components

You can access oter components from inside script using construction:

#{referenceName}

Where

• referenceName - reference name of component to access

Result of this construction is component object or 'null' when no component found.

7.2.3. access translations

You can get translation using construction:

#{translate(translationKey)}

Where

• translationKey - key to translate

Result of this construction is string with translation.

7.3. Component methods

7.3.1. commons

• addOnChangeListener(listener)

Adds listener to component. For more information see component events.

Arguments:
- listener - [object] listener to add

Returns:
none

• fireEvent(actionPerformer, eventName, args)

Fires event on component.

Arguments:
- actionPerformer - [component] reference to performer component
- eventName - [string] name of event
- args - [array] array of event arguments

Returns:
none

• fireEvent(actionPerformer, {
      name : eventName,
      args : eventArgs,
      callback : eventCallback
  })

Fires event on component.

Arguments:
- actionPerformer - [component] reference to performer component (optional)
- eventName - [string] name of event
- args - [array] array of event arguments (optional)
- eventCallback - [function] parameterless function which will be called after event handler completes its job. (optional) 

Returns:
none

• getValue()

Gets component value.

Arguments:
none

Returns:
component value

• isChanged()

Check if component has some unsaved changes.

Arguments:
none

Returns:
true if component has unsaved changes, false otherwise.

• isEnabled()

Check if component is enabled.

Arguments:
none

Returns:
true if component is enabled, false otherwise.

• isVisible()

Check if component is visible.

Arguments:
none

Returns:
true if component is visible, false otherwise.

• performUpdateState()

This function informs component that his current state is synchronized with server. That means that isChanged method will return false.

Arguments:
none

Returns:
none

• setComponentError(isError)

Displays or removes error information on component.

Arguments:
- isError - [boolean] true if component should display error message

Returns:
none

• setEditable(isEditable)

Makes component editable or not.

Arguments:
- isEditable - [boolean] true if component should be editable

Returns:
none

• setEnabled(isEnabled, isDeep)

Makes component enabled or not.

Arguments:
- isEnabled - [boolean] true if component should be enabled
- isDeep - [boolean] true if all children component should inherit

Returns:
none

• setMessages(messages)

Shows messages on component.

Arguments:
- messages - [array] array of messages to show

Returns:
none

• setValue(value)

Sets new component value.

Arguments:
- value - [object] new component value

Returns:
none

• setVisible(isVisible)

Makes component visible or not.

Arguments:
- isVisible - [boolean] true if component should be visible

Returns:
none

7.3.2. window:

• getRibbonItem(ribbonItemPath)

Returns ribbon object defined by path

Arguments:
- ribbonItemPath - [string] coma separated path to ribbon item. Can be groupName.itemName or groupName.itemName.subitemName

Returns:
- [object] ribbon object or null when no object found

• performBack()

Go to previous page.

Arguments:
none

Returns:
none

• setHeader(header)

Sets window header (if header visible).

Arguments:
- header - [string] header content

Returns:
none

• setActiveTab(tabName)

Shows tab with given name, regardless of its current visibility state.

Arguments:
- tabName - [string] name of the tab

Returns:
none

• getTab(tabName)

Returns tab with given name.

Arguments:
- tabName - [string] name of the tab.

Returns:
window tab object (see next section) or 'undefined' if it doesn't exist.

7.3.3. window tab:

• getRibbonItem(ribbonItemPath)

Returns ribbon object defined by path

Arguments:
- ribbonItemPath - [string] coma separated path to ribbon item. Can be groupName.itemName or groupName.itemName.subitemName

Returns:
- [object] ribbon object or null when no object found

• setVisible(isVisible)

Depending on the argument's value shows or hides this tab from the window header.

Setting tab's visibility to true != activate tab. Visibility refers to presence tab name in the window header, while tab activation means focusing given tab.

If you set currently focused (active) tab to be not visible then the first visible tab (counting from the left) will be focused (activated).

Arguments:
- isVisible - [boolean] true if tab name should be displayed in the tabs list, at the window's header.

Returns:
none

7.3.4. form

• setComponentLoading(isLoadingVisible)

Shows or hides loading indicator

Arguments:
- isLoadingVisible - [boolean] true if loading indicator should be visible

Returns:
none

7.3.5. grid:

• setComponentLoading(isLoadingVisible)

Shows or hides loading indicator

Arguments:
- isLoadingVisible - [boolean] true if loading indicator should be visible

Returns:
none

• setFilterObject(filterObject)

Sets state of filters for all column.

Arguments:
- filterObject - [object] object where keys are column names and values are filter values to insert

Returns:
none

• setFilterState(column, filterText)

Sets state of filter for one column.

Arguments:
- column - [string] name of column
- filterText - [string] filter value to insert

Returns:
none

7.3.6. tree

• setComponentLoading(isLoadingVisible)

Shows or hides loading indicator

Arguments:
- isLoadingVisible - [boolean] true if loading indicator should be visible

Returns:
none

7.3.7. ribbon button:

• disable()

Disables button

Arguments:
none

Returns:
none

• disable(msg)

Disables button and sets info message

Arguments:
- msg - [string] info message

Returns:
none

• enable()

Enables button.

Arguments:
none

Returns:
none

• enable(msg)

Enables button and sets info message

Arguments:
- msg - [string] info message

Returns:
none

• isEnabled()

Check if button is enabled

Arguments:
none

Returns:
- [boolean] true if button is enabled, false otherwise

• setIcon(icon)

Sets button icon

Arguments:
- icon - [string] new button icon

Returns:
none

• setLabel(label)

Sets button label

Arguments:
- label - [string] new button label

Returns:
none

7.3.8. calendar:

• getDate()

Returns calendar value as date.

Arguments:
none

Returns:
[date] date value of field, 0 when field is empty or null when date parsing error

• setDate(date)

Sets datepicker value from date.

Arguments:
- date - [date] new value of field

Returns:
none

7.3.9. borderLayout:

• setBackground(color)

Sets border layout background color.

Arguments:
- color - [string] new color of background (in CSS notation)

Returns:
none

7.4. Component events

To every component you can add listener using addOnChangeListener method. Listener object should have methods that will be executed when event is fired. Depends of component object different methods will be executed (see below)

7.4.1. commons

• onSetValue(value)

Executed when setValue method is executed on component.

Arguments:
- value - [object] value object

7.4.2. grid

• onChange(selectedEntitiesArray)

Executed when grid selection changes.

Arguments:
- selectedEntitiesArray - [array] array of selected entities

7.4.3. ribbon button

• onClick()

Executed when ribbon button is clicked.

Arguments:
none

7.4.4. tree

• onMoveModeChange(isMoveMode)

Executed when tree change its move mode.

Arguments:
- isMoveMode - [boolean] true if tree is in move mode, false otherwise