====== Table Scripting in the Vortex ======

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.

==== Location of the script ====

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.

==== Naming the class ====

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.

===== Triggered events =====

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

==== beforeLoad ====
**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.

==== afterLoad ====
**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.

==== beforeSave ====
**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.

==== afterSave ====
**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.

==== beforeUpdate ====
**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.

==== afterUpdate ====
**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.


===== Overview =====

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.

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

===== Table Summary =====

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.

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


===== GUI Activated Scripts =====

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.

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

The attributes to the //script// element is:

==== name ====

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:
<code php>
  public static function TestScript( &$table, &$recordids ) {}
</code>

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.

==== description ====

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

==== icon ====

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

==== type ====

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.

==== return =====

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.

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

==== access ====

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.\\

==== require ====

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

==== onclick ====

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.

==== Returing data as XML ====

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.

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

=== error ===
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)

=== info_popup ===
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:
<code java>
  AJAX.open( "POST", "index.php?vortex_callertype=ajax&ajax_operation=AJAXscript" );
</code>
this will post the information to the method for the last activated GUI table script.

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

=== success ===
The //success// element triggers a notification with the success status.

=== tablerecord ===
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.