EDGE: Engineering Design Guide and Environment
/public/Development/

Script Spec

Table of Contents

The scripts in superprojects allow extensions to the built-in CMS capability.

File Format

The format of the script file is that of a normal PHP executable file with the exception that 'local' (script-direcotory relative) includes are in a different format. These includes are listed, one per line, outside of the <?php ?> parsed block.

An example is: 

classname = MyScript
file1.inc
<?php
require_once('file2.inc');
Here, file1.inc is taken from the script directory of the containing project, while file2.inc is taken from the CGI root directory.

As with any execution-output-only script (one that does not contain embedded unparsed blocks), it is good practice to not include the closing ?> to avoid causing accidental, unwanted output.

Script Structure

A script is a set of files within the project repository's /web/scripts directory. The file assocated with an example script "MyScript" are:

All scripts should contain a locally-defined class that inherits from ScriptNode. This provides a basic structure to make script development simple. The option that tells the system what class to use for the script is classname

The script class member functions are of two types, those that begin with an underscore are internal functions and those that do no are external. External functions are associated with the action query parameter, which has a default value of "display". This means that the entry-point to a script is it's class' display() function.

An example of this structure is given here: 

class MyScript extends ScriptNode {
  /**
  * Control access to the script
  *
  * @param string $action Action to be performed on the table
  * @param boolean $throw True iff an exception should be thrown if access denied
  * @return boolean True iff access is allowed
  * @throws AccessViolation iff access should not be allowed and $throw is set
  */
  public function _access($action, $throw = true) {
    return true; // Everyone can run this
  }

  /**
   * This function displays some text
   */
  public function display() {
    $page_data['text'] = 'example';

    return $page_data;
  }
}

Each script source has associated with it a Smarty rendering template file. Documentation for this file is given in the Smarty manual.

For the example above, a template can simply be: 

{$text}

When sending data to the template, be careful about not using reserved data names. Reserved names are: 

globals
request
navbar
node
node_template
title
footer

A safe name to pass data to the template is body. This name is commonly used by scripts to pass script-specific data.

Explanation of Reserved Data

The name title is used to specify a string that will go beside the node name in the titlebar. The name footer is used to specify an array of items that are placed in the node's footer. footer itself is an array of lines in the footer, with each element containing the text of a link as its key and a URL as its value.

An example of a footer structure is: 

'footer' => array(
  0 => array(
    'name' => 'URL'
    'name2' => 'URL2'
  )
  1 => array(
    'name3' => NULL
    'name4' => URL4
  )
)

Which will be rendered to something similar to the following (but in the style of the footer, which is in-line listing):

Notice that to just write text, set the URL to NULL.

Exposing the Script

The following explanations focus on allowing the script to expose itself to external functions in a way that allows the functions to interrogate the script object and glean some useful information.

Naming Script's Actions

The first thing that needs done is to give long names to all of the script's actions. This is accomplished by creating an action name mapping array called action_names that has protected visibility.

An example of this is: 

/** Names of the entry actions */
protected $action_names = array(
  'display' => 'View normal mode',
  'edit' => 'View edit mode',
);
This assumes that the script has two actions, display and edit, and gives them long, explanatory names.

Simple Intra-Script Linking

The ScriptNode class provides a helper function, _addActionLink() that greatly simplifies linking between actions of a script using the script page's footer.

When an action calls something like the following: 

$this->_addActionLink($page_data['footer'][0], 'edit');
from within the display action, it will make a nice looking, consistantly named link in the first row of the footer. It uses the script's action_names map to create the link names.

A similar action link should be created in the edit action linking back to the display action.

Expose Entry Actions

After an action_names map is created, it is convenient to let external functions know valid actions to enter the script (eg. which actions can be linked to without some filter context).

This is accomplished by creating an entry_actions array with protected visibility, such as the following: 

/** Actions that are entry points to the script */
protected $entry_actions = array('display');
In this case, even though edit is an available action, it is not considered an entry action, and won't be displayed to the user as such.