About scripting hooks

The scripting hooks are functions that can be added to a widget/view definition. In this way they can be used to extend /customize the behavior of the widget/view. In principle, the hook is called when certain event occurs in the application and before the corresponding action is executed. It is possible to cancel the relevant action by returning false from a hook, for example when a condition is not met.

The list of available scripting hooks and their description

onDeleteRows

This scripting hook is available for views. The event is called when ‘delete row’ action is invoked. If the scripts associated with this event signal that they have handled the event the actions would stop there. If there is no script or the script decides not to consume the event the actions would proceed with their default behavior.

An example of the onDeleteRows scripting hook use is shown below.

onDeleteRows = { event ->
	// use java popup dialog
  	def readln = javax.swing.JOptionPane.&showInputDialog
 	def pass = readln 'Enter password:'
    // unless the user responds enters correct password (psswd), the event is directly consumed and the row is not deleted
  	if (pass=='psswd'){
       return false
       }
       else{
           println "INCORRECT PASSWORD!"
           return true}
}

onInsertRows

This scripting hook is available for views. The event is called when ‘insert row’ action is invoked. If the scripts associated with this event signal that they have handled the event the actions would stop there. If there is no script or the script decides not to handle the event the actions would proceed with their current behavior.

An example of the onInsertRows scripting hook use is shown below.

onInsertRows  = { event ->
	// use java popup dialog
  	def readln = javax.swing.JOptionPane.&showInputDialog
  	def pass = readln 'Enter password:'
    // unless the user responds enters correct password (psswd), the event is directly consumed and the row is not deleted
  	if (pass=='psswd'){
       return false
       }
       else{
           println "INCORRECT PASSWORD!"
           return true}
}

onDoubleClick

This scripting hook is available for widgets. It is the first event which is called when double-clicking a widget and it is common to all scriptable form widgets. This event is available to all user roles.

An example of the implementation of onDoubleClick hook can be found below.

onDoubleClick = { event ->
	field = event.widget.boundFields[0]
	message = "Double-Click event in a widget " +
        "bound to '${field.name}' field from '${field.entity.name}' entity " +
        "and showing value '${event.value}'"
	println message // printed to IJC output window
	javax.swing.JOptionPane.showMessageDialog(null, message);
	rs = event.widget.form.resultSet
	rootVS = rs.rootVertexState
	// do something with DFResultSet or VertexState here
}

beforeEdit

This scripting hook is available for widgets. When the user starts to edit the data in any way (Edit option in right click menu, F2 shortcut or double-clicking), the beforeEdit event is triggered. It can be used to run a script before editing a value in text field widget and e.g. control the editability of fields more precisely than just by using user roles.

An example of the use of beforeEdit hook can be found below.

// Adding a confirmation text message which asks whether a user wants to change the value
beforeEdit = { event ->
	// use java popup dialog
  	def readln = javax.swing.JOptionPane.&showInputDialog
	// newvalue stores the value edited by user. It should only accept yes/no values
	def newvalue = readln 'Do you really want to edit the value? (yes/no)'
	// unless user responds 'yes', the event is directly consumed
	if ((newvalue=='yes')||(newvalue=='no')){
		if (newvalue=='yes'){return false}
		}
	else{
		println "the value must be yes or no"
		return true}
}

afterEdit

This scripting hook is available for widgets. When the user finishes editing the data in a widget, the afterEdit event is called. It allows to run the script after editing, but yet before storing the value in the text field. This option can be used for example for normalization, auditing etc.

An example of the use of afterEdit hook can be found below.

// short script which notes the editing changes to the output
afterEdit = { event ->
    def today = new Date() // current datetime value
    def field = event.widget.selectedFields[0] // stores selected field
    def vs = event.widget.getVertexState(field)
    def id = vs.selectedRowsIds // get current row id
    println "$today : change of value for ${field.name} (id=$id) from ${field.entity.name}'"
}

The overview of scripting hooks and their availability for widgets

Containers
Panel	no support
Tabbed Pane	no support
Widgets
Single line text field	onDoubleClick, beforeEdit, afterEdit
Multi line text field	onDoubleClick, beforeEdit, afterEdit
Molecule pane	onDoubleClick, beforeEdit, afterEdit
Check box (for boolean fields)	onDoubleClick, beforeEdit, afterEdit
Date pane (for date fields)	onDoubleClick, beforeEdit, afterEdit
Label	no support
Button	no support
Browser pane	no support
List (for list fields)	onDoubleClick, beforeEdit, afterEdit
Tables
Table	onDoubleClick, beforeEdit, afterEdit
Sheet	onDoubleClick, beforeEdit, afterEdit
Molecules matrix	onDoubleClick, beforeEdit, afterEdit
Tree table (experimental)	no support
Charts
Box plot	no support
Histogram	no support
Radar chart	no support
Scatter plot	no support

Known issue

In the case of table widgets that utilize an external editor of values ( e.g. molecules matrix that uses Marvin Sketch), the afterEdit event is called when the editor opens and not when the new data is going to be inserted.

Scripting hooks