Documentation

Actions: Events and Actions

According to the MVC paradigm, the data model and the views must be decoupled: this philosophy has been respected on the whole product. Between model and view, a controller should be included, in order to manage operations to apply on the views and to listen to events coming from the views.

Actions in 4WS.Platform represent the controller: they are invoked by events fired by views (a grid, a form, a tree, a column, a control, a filter control, a tree node, a button) and they perform a presentation logic on the GUI or a business logic on the server side.

Actions have a format:

  • JavaScript – in this case the code will be executed on the GUI
  • SQL – in this case the code will be run on the server side; it can include more than one SQL statement, separated by “;”
  • Web service – the web service is expressed as an URL which can include variables (:VARNAME); this web service will be always called on the server layer, so there will not be any limit related the host to invoke.

 

By means of actions, it is possible to enhance and customize the standard behavior of grids, forms, trees and the other components, by injecting custom code invoked by specific events.

 

Events and actions work closely: an event provides inputs that an action can use and evaluate; output from actions can represent a feedback for events and can influence the way the component behaves after the event completion. So, for example, it is possible to prevent the data saving when pressing the save button in a grid, using an action linked to a “before saving on insert” event.

 

It is also possible to create a chain of actions to execute in sequence, starting from a single event: through the action detail form, it is possible to define an optional action to perform at the end of the current one.

In case of server-side javascript actions, it is also possible to define an action to concatenate before the current action: in this way, a unique action composed of these two is execute on the server side. This feature allows to reuse code defined on the server by multiple actions, in a similar way to classes linked to a inheritance relationship: a base action can contain reusable code, expressed as declaration of functions, whereas other classes can invoke that code, if they inherit the base action, by declaring it as the class to execute before.

Example of server-side javascript base action:

var baseMethod = function(argument1, argument2, ..) {...}

 

Example of server-side javascript action which uses the previous one:

baseMethod(parameter1, parameter2, …);

 

This feature is available only for server-side javascript actions. If inheritance is nedded on client-side javascript actions, this is already possible by defining an action linked to the whole application (“action after render” property defined in the application detail form), containing the reusable code (reusable functions); this code is global, so it can be accessed from any part of the client-side application, so to any client-side javascript action.

Example of client-side javascript initial action:

window.baseMethod = function(argument1, argument2, ..) {...}

 

Example of client-side javascript action which uses the previous one:

baseMethod(parameter1, parameter2, …);

 

 

Events are defined at panel level and at component level (column, control, tree node, button).

In the following table, a list of inputs and outputs for actions are reported, according to the event type, related to grid panels.

 

Event Action type Inputs Outputs
before grid opening SQL/Javascript/Web service gridXXX (current grid)

 

vo (current record)

after data loading SQL/Javascript/Web service gridXXX (current grid)

 

vo (current record)

click of a grid row on tree node SQL/Javascript/Web service comp (current grid)

 

record (current record)

 

rowIndex (current row index)

double click on a grid row SQL/Javascript/Web service comp (current grid)

 

record (current record)

 

rowIndex (current row index)

before cell editing in grid SQL/Javascript/Web service comp (current grid)

 

record (current record)

 

rowIndex (current row index)

 

node (current column index)

return false

will block the operation

after cell editing in grid SQL/Javascript/Web service comp (current grid)

 

record (current record)

 

rowIndex (current row index)

 

node (current column index)

before saving data in insert mode SQL/Javascript/Web service gridXXX (current grid)

 

vo (current record)

return false

will block the operation

before saving data in edit mode SQL/Javascript/Web service gridXXX (current grid)

 

vo (current record)

return false

will block the operation

before deleting record SQL/Javascript/Web service gridXXX (current grid)

 

vo (current record)

return false

will block the operation

before rendering the grid SQL/Javascript/Web service rec (current record)
when pressing insert button SQL/Javascript/Web service gridXXX (current grid)

 

vo (current record)

return false

will block the operation

when pressing edit button SQL/Javascript/Web service gridXXX (current grid)

 

vo (current record)

return false

will block the operation

when pressing delete button SQL/Javascript/Web service gridXXX (current grid)

 

vo (current record)

return false

will block the operation

after saving data in insert mode SQL/Javascript/Web service

In case of SQL statements, these are executed on the server side and are part of the same saving transaction.

gridXXX (current grid)

 

vo (current record)

after saving data in edit mode SQL/Javascript/Web service

In case of SQL statements, these are executed on the server side and are part of the same saving transaction.

gridXXX (current grid)

 

vo (current record)

after deleting record SQL/Javascript/Web service

In case of SQL statements, these are executed on the server side and are part of the same saving transaction.

gridXXX (current grid)

 

vo (current record)

update summary row Javascript total (current total for the current column)

 

params.css (css class name that can be applied for the current column)

params.id (column index for the current column)

params.style (style for the current column)

 

params.attr (‘ext:qtip=”Total no. of companies”‘ tooltip example)

record.data (data to show in the last row)

 

formattedValue (current total, reformatted with the same format of the values in the column

 

colAttr (attribute nameof the current column)

 

col (current column object)

return total;

 

or

 

return formattedValue;

column headers

 

Javascript return array with column headers

 

example: return [ [{header: ‘4 Cols’, colspan: 4}, {header: ‘7 Cols’, colspan: 7}], [{header: ‘Goup1’, colspan: 2},{header: ‘Group2’, colspan: 2},{header: ‘Group3’, colspan: 7, align: ‘center’}] ];

 

Important note: be sure to include hidden columns in the colspan counting, as well as an additional empty column always automatically added on the right of the grid.

 

The grid name (gridXXX) can be retrieved by opening the list of panels and identying the current pane: the last column in the list (javascript name) reports the grid name to use.

 

The local variable vo represents the javascript object linked to current grid row; if you need to read the value of a specific cell, use the related attribute name; example: vo[“attribute1.attribute2”]

 

The local variable rec/record represents a wrapper of the javascript object linked to current grid row; starting from this wrapper, you can access so some utility methods/properties:

record.data – the javascript object linked to the current row; if you need to read the value of a specific cell, use the related attribute name; example: record.data[“attribute1.attribute2”]

record.set(“attributeName1.attributeName2”, valueToSet] – method used to change the value of a specific cell, identified by the specified attribute name

 

In javascript actions, you can also perform common operations:

  • gridXXX.store.getCount() – number of rows in grid
  • gridXXX.store.baseParams.parameter = value; – pass to HTTP request the specified parameter; in order to read that parameter on the binded business component on the server side, you have to specify it in the where clause of the business component; bear in mind that if the variable in the where clause is :VAR_NAME, then the parameter passed through baseParams must be expressed in “camel” format, i.e. varName
  • gridXXX.store.reload(); – force grid reloading
  • gridXXX.store.removeAll(); – clear up the grid content
  • gridXXX.mode – current grid mode; you can use it to check out the current grid mode and then perform custom logic. It can have 3 different values:
    • READONLY
    • INSERT
    • EDIT
  • gridToolbarXXX.enable() or gridToolbar.disable() – enable/disable all buttons in the toolbar
  • gridToolbarXXX.insertButton.enable() or disable() – enable/disable the insert button of the grid’s toolbar
  • gridToolbarXXX.updateButton.enable() or disable() – enable/disable the update button of the grid’s toolbar
  • gridToolbarXXX.detailButton.enable() or disable() – enable/disable the detail button of the grid’s toolbar
  • gridToolbarXXX.reloadButton.enable() or disable() – enable/disable the reload button of the grid’s toolbar
  • gridToolbarXXX.deleteButton.enable() or disable() – enable/disable the delete button of the grid’s toolbar
  • gridToolbarXXX.exportButton.enable() or disable() – enable/disable the export button of the grid’s toolbar

 

In the following table, a list of inputs and outputs for actions are reported, according to the event type, related to form panels.

 

Event Action type Inputs Outputs
before saving data in insert mode SQL/Javascript/Web service formPanelXXX (current form)

 

vo (current record)

return false

will block the operation

before saving data in edit mode SQL/Javascript/Web service formPanelXXX (current form)

 

vo (current record)

return false

will block the operation

before deleting record SQL/Javascript/Web service formPanelXXX (current form)

 

vo (current record)

return false

will block the operation

when pressing insert button SQL/Javascript/Web service formPanelXXX (current form)

 

vo (current record)

return false

will block the operation

when pressing edit button SQL/Javascript/Web service formPanelXXX (current form)

 

vo (current record)

return false

will block the operation

when pressing delete button SQL/Javascript/Web service formPanelXXX (current form)

 

vo (current record)

 

return false

will block the operation

after saving data in insert mode SQL/Javascript/Web service

In case of SQL statements, these are executed on the server side and are part of the same saving transaction.

formPanelXXX (current form)

 

vo (current record)

 

after saving data in edit mode SQL/Javascript/Web service

In case of SQL statements, these are executed on the server side and are part of the same saving transaction.

formPanelXXX (current form)

 

vo (current record)

after deleting record SQL/Javascript/Web service

In case of SQL statements, these are executed on the server side and are part of the same saving transaction.

formPanelXXX

 

(current form)

 

vo (current record)

click on any additional button SQL/Javascript/Web service formPanelXXX

 

The form name (formPanelXXX) can be retrieved by opening the list of panels and identifying the current pane: the last column in the list (javascript name) reports the form name to use.

 

The local variable vo represents the javascript object linked to current form row; if you need to read the value of a specific control, use the related attribute name; example: vo.attribute1.attribute2

 

In javascript actions, you can also perform common operations:

  • formPanelXXX.baseParams.parameter = value; – pass to HTTP request the specified parameter; in order to read that parameter on the binded business component on the server side, you have to specify it in the where clause of the business component; bear in mind that if the variable in the where clause is :VAR_NAME, then the parameter passed through baseParams must be expressed in “camel” format, i.e. varName
  • formPanelXXX.reload(); – force form reloading
  • formPanelXXX.mode – current form mode. You can use it to check out the current form mode and then perform custom logic. It can have 3 different values:
    • READONLY
    • INSERT
    • EDIT
  • formToolbarXXX.enable() or disable() – enable/disable all buttons in the toolbar
  • formToolbarXXX.insertButton.enable() or disable() – enable/disable the insert button of the form toolbar
  • formToolbarXXX.updateButton.enable() or disable() – enable/disable the update button of the form toolbar
  • formToolbarXXX.detailButton.enable() or disable() – enable/disable the detail button of the form toolbar
  • formToolbarXXX.reloadButton.enable() or disable() – enable/disable the reload button of the form toolbar
  • formToolbarXXX.deleteButton.enable() or disable() – enable/disable the delete button of the form toolbar
  • formToolbarXXX.exportButton.enable() or disable() – enable/disable the export button of the form toolbar
  • formToolbarXXX.show() or hide() – hide/show toolbar

 

In the following table, a list of inputs and outputs for actions are reported, according to the event type, related to tree panels.

 

Event Action type Inputs Outputs
before tree rendering SQL/Javascript/Web service treePanelXXX (current tree)
click of a grid row on tree node SQL/Javascript/Web service treePanelXXX (current tree)

 

vo (record linked to current node)

 

node (current node)

when expanding a node SQL/Javascript/Web service treePanelXXX (current tree)

 

vo (record linked to current node)

 

node (current node)

when selecting a checkbox related to a node SQL/Javascript/Web service treePanelXXX (current tree)

 

vo (record linked to current node)

 

node (current node)

 

The tree name (treePanelXXX) can be retrieved by opening the list of panels and identying the current pane: the last column in the list (javascript name) reports the tree name to use.

 

In the following table, a list of inputs and outputs for actions are reported, according to the event type, related to components.

 

Event Action type Inputs Outputs
cell value changed SQL/Javascript/Web service comp

record

rowIndex

node

control

formPanel

filterPanel

before validation SQL/Javascript/Web service control

formPanel

filterPanel

focus grab and lost SQL/Javascript/Web service comp

record

rowIndex

node

control

formPanel

filterPanel

value changed SQL/Javascript/Web service comp

record

rowIndex

node

control

formPanel

filterPanel

value correctly validated SQL/Javascript/Web service comp

record

rowIndex

node

control

formPanel

filterPanel

value not correctly validated SQL/Javascript/Web service comp

record

rowIndex

node

control

formPanel

filterPanel

row/node selected SQL/Javascript/Web service comp

record

rowIndex

node

control

formPanel

filterPanel

button clicked SQL/Javascript/Web service comp

record

control

formPanel

filterPanel

enter key pressed SQL/Javascript/Web service comp

record

control

formPanel

filterPanel

 

In the following table, a list of inputs and outputs for actions are reported, according to the event type, related to grid columns.

 

Event Action type Inputs Outputs
before lookup code validation

before lookup grid opening

SQL/Javascript/Web service lkupds

lkupds.baseParams

grid

rec

after lookup code changed SQL/Javascript/Web service grid

rec

value

before upload button SQL/Javascript/Web service grid

rowIndex

colIndex

rec

after editing cell SQL/Javascript/Web service grid

rowIndex

columnIndex

fieldName

cell selected SQL/Javascript/Web service record

index

control

 

before combo selection SQL/Javascript/Web service combo

 

A special kind of javascript action is the one where the written code, executed on the GUI layer, is used to call the server side, via an Ajax call. There are 2 ways to invoke the server side:

invoking a resource class on the server side, e.g. using the utility method

var response = new SyncRequest().send(uri[,method[,data]]);

invoking a predefined resource class, used to invoke a business component having the task to execute a SQL statement (contextPath+”/executesql”) or a web service from the server layer (contextPath+”/executesql/executewebservice”).