To customize the behaviour of the Vortex there is the possibility for per Table scripting. Here you can trigger events like beforeSave and afterLoad, but you can also configure and script custom scripts that can be activated by the user via the GUI. This chapter will describe the Table scripting in more detail.

All the custom scripts are placed in the /script folder in the DBI. All .php files in this path will be included and parsed at load time, and all scripts following the right name stanard will be used as per Table scripts, or as the CommandLine script class. The name of the file is not important, however we recommend giving the files logical names like MyTableScript.php for the file containing scripts for MyTable. Helper classes can be put in separate files or in the same files as the scripts, they will all be loaded and parsed.

The Vortex identifies scripts by the class name of the class containing the methods. For per Table scripts the name of the class should be Script[tablename] where tablename is all lowercase. For instance, if we were to create scripts for the table MyTable the class would be named Scriptmytable. To make scripts valid for all tables they can be added to the class Script_general which works in the same way as normal per-table scripts. Methods are first sought in the per-table script so general scripts can be overridden on a per-table basis by adding the same method/script to the table specific class.

The following events will be triggered while running the Vortex. All methods are declared - and run - statically.

Parameters: &$object, &$cancel
This method is called before a TableRecord is loaded from the database. The passed parameters are the $object which is to load and a boolean $cancel which per default is set to false. Here you can do pre-loading processing, and if the $cancel variable is set to true when returning from this method the TableRecord will not load.

Parameters: &$object, &$cancel
This method is called after a TableRecord is loaded from the database. The passed parameters are the $object which is to load and a boolean $cancel which per default is set to false. Here you can do post-loading processing, and if the $cancel variable is set to true when returning from this method the TableRecord will not load.

Parameters: &$object, &$cancel
This method is called before a TableRecord is saved to the database. The passed parameters are the $object which is to be saved and a boolean $cancel which per default is set to false. Here you can do pre-save processing, and if the $cancel variable is set to true when returning from this method the TableRecord will not be saved.

Parameters: &$object, &$cancel
This method is called after a TableRecord is saved to the database. The passed parameters are the $object which is to be saved and a boolean $cancel which per default is set to false. Here you can do post-save processing. Since the record has already been saved to the database, setting the $cancel flag will make no difference here. Please use caution when changing parameters in the $object in the afterSave method, since making the TableRecord dirty will cause the Vortex to save the $object again, possibly casuing an endless loop.

Parameters: &$field, &$cancel
This method is called before a field is updated in the TableRecord. The $field parameter contains the Field that will be changed, and if the $cancel flag is set true when returning the value of the Field will not be updated.

Parameters: &$field, &$cancel
This method is called after a field has been updated in the TableRecord. The $field parameter contains the Field that has been changed. Since the change has already been done, the $cancel flag has no function in this method.

To customize the appearance of the details view for the scripted Table, there is a possibility to add an Overview category. This will be shown as a normal category in the details view, will always be open per default and show at the top of the details view.
The Vortex checks the Table specific Class for a static method called _overview. If this exists, it calls the method with the parameter &$object which is the object for which the overview is to be shown. The _overview method returns pure HTML code, which is shown in the overview category of the details view.

class Scriptmytable {
  public static function _overview( &$myTableRecord ) {
    return "<b>Some overview here</b>";
  }
}

For every table there is the possibility to create a custom summary header showing information about the current table. The summary will be shown in the ShowList view and in the details view for all TableRecords in the table.
The Vortex checks the Table specific Class, or the _general class, for a static method called _summary. If the method exists it is called with the parameter &$table which is a reference to the current table. The _summary method works in the same way as the _overview and returns HTML code which is shown in the header.

class Scriptmytable {
  public static function _summary( &$table ) {
    return "<b>MySummary for table " . $table->get( 'name' ) . "</b>";
  }
}

GUI Activated scripts are represented by an icon in the top section of the ShowList or the Details view. Theese scripts are placed in the same Table specific class as all the other scripts regarding that table. To define the scripts, the variable $SCRIPTS is defined statically in the class as an XML string defining the scripts available for this Table.

class Scriptmytable {
  public static $SCRIPTS = '<script name="TestScript" description="MyTestScript" icon="script.jpg" type="details,table" return="xml" access="All" />';
}

The attributes to the script element is:

The name of the method to run. This method has to be statically defined in the Table specific class. The method is called given two arguments:

  public static function TestScript( &$table, &$recordids ) {}

The $table argument is a reference to the Table the script is run for. This is always the table for which the script is written. The $records argument contains the IDs of the records for which to run the script. If the script is run from the details view, this is an array containing one post, which is a reference to the TableRecord shown. If the script is run from a ShowList view, this is an array containing all the currently visible posts in the ShowList.

The description of the Script. This is shown when the mouse cursor hovers over the icon for the script.

This is the filename of the icon to show for the script.

Defines where the script icon is shown. Valid values are:
table - shown in the ShowList
details - shown in the details view
row - shown for each row in the ShowList
these can be combined using a comma as separator.

Tells the Vortex what kind of data to expect from the script. Valid values are:
pdf - A PDF document is returned and should be shown to the user
xml - XML is returned to the javascript AJAX call

In order to return a PDF the script method should set the headertype and return the raw data from the PDF.

  public static function makePDFScript( &$table, &$objectids ) {
    header( "Content-type: application/pdf" );
    echo file_get_contents( "/tmp/my_pdf_file.php" );
  }

Defines which UserGroups to have access to the script. Groups are stated by name and commaseparated. Valid values are:
[groupname] - The name of a group
All - All users will have access to the script. This is the default value.

Optionally, the require attribute can be used to only show the script when certain criteria are met. The require string is on the same format as the access string and valid requirements are:
edit - Require the SLTables edit flag to be set
norelation - Require the SLTable to not be a related SLTable, ie this is the master table shown

Optionally, the onclick attribute can be used to fire an internal method of the SLTable. This is only used for internal functions and should not be used in DBI scripts.
When onclick is set the name attribute should be omitted.

When returning data as XML there are a couple of elements that trigger special events in the GUI. Theese are triggered by giving the first element in the returned data the specified tagName.

The alert_popup element triggers a normal alert box containing the information in the contained TextNode.

The error element triggers an error that is notified to the user via the Notify SLClass method. (Shown for a period of time as a status in the Vortex)

The info_popup element triggers a popup DIV that is shown to the user. The div contains all the child elements of the info_popup element. The info_popup element has three attributes, width and height which determine the size of the popup box and skipClose. The skipClose attribute, if given, prevents the popup to close when clicked, which is the standard behaviour of the popup. Supplying the skipClose attribute means that somewhere in the content of the popup there should be a possibility to remove the div from the DOM.

When using info_popup as return type advanced functions can be added. In order to post information back to the same script method as defined in the SCRIPTS tag, simply add the two attributes vortex_callertype and ajax_operation to the request string in the following manner:

  AJAX.open( "POST", "index.php?vortex_callertype=ajax&ajax_operation=AJAXscript" );

this will post the information to the method for the last activated GUI table script.

The showdetails element shows the details view for the UUID that is the nodeValue for this element.

The success element triggers a notification with the success status.

The tablerecord element updates the TableRecord shown that is the child element of the tablerecord element. If not shown in the ShowList, it is added.