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

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

Example

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

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

Example

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").

Another javascript function provided by platform that you could include in your client-side javascript actions is the one used to manually manage a file upload:

uploadFile(title,enabled,fileName,dirId,beforeUploadCallback,afterUploadCallback,errorOnUploadCallback,settings);

The syntax for this function includes the following arguments:

• title; can be null, in that case, a default title is shown

• enabled true: upload button is enabled, false: upload button is disabled

• fileName file name to set in the input field; if it is not empty, then a “Download” and “Preview” buttons are shown too

• dirId directory id on the server side where saving the file to upload

• beforeUploadCallback callback function invoked just before the uploading; format:

function({ filename: “…” }) { 
  return true|false 
};   
// false can block the uploading
// you can change the file name by working on the argument 

• afterUploadCallback callback function invoked after the uploading; format:

function({ fileName: "….", success: true|false, message: "…" }) 
// The popup window is automatically closed just before this callback is invoked

• errorOnUploadCallback callback function invoked in case of errors on uploading; format:

function({ error: “…” }) 
// The popup window is automatically closed just before this callback is invoked

• settings - optional javascript object containing additional settings, expressed as attribute-value:

  • acceptMimes: a string containing a list of mime types, separated by comma; example: "image/jpg,image/png" - used to filter the content to upload

  • encriptAttachments: true|false - specify if content to upload must be encripted on the server side; in such a case, content must be undecripted when reloading it leater

  • panelId: ... // panel id related to this upload process

Through this arguments you can for instance show a modal dialog prompting the user to select a local file and upload it in the specified folder identified by dirId. After that, you could use the same modal dialog to show a previously uploaded file, through the “Download” or “Preview” buttons, in case you have filled the “fileName” arguments.

Example

uploadFile(
    "My upload", // title,
    true, // upload enabled
    "", // fileName,
    19, // dirId
    function(args) {
        var filename = args.filename;
        return true; // do not block file uploading!
    }, // beforeUploadCallback
    function(args) {
        var filename = args.filename;
    }, // afterUploadCallback
    function(args) {
        var error = args.error;
    }, // errorOnUploadCallback
    {
      acceptMimes: "image/jpg,image/png,image/gif"
    } // settings
);

Example

var yourFileName = "...";
uploadFile(
    "My upload", // title,
    false, // upload NOT enabled
    yourFileName, // fileName,
    19 // dirId
);