menu_banner (2K)

Appendix D: Task Parameters

Although the script associated with a task may be designed to operate in a particular fashion, it is sometimes convenient if that behaviour can be modified. To this end the details for each task contain a set of optional fields which can be used to modify that task's behaviour. These fields are:

Initial Passthru This field contains the identity of a different passthru task. The first time the main task is called it will immediately suspend itself and pass control to the passthru task instead. When the passthru task has been completed it will return control to the main task which will carry out its normal processing using any parameters that may have been returned by the passthru task. These will appear in the $selection argument in the _cm_initialise() method.

This mechanism is typically used for tasks of type LIST where it is required that a SEARCH screen be processed first. Any type of task can be used as the passthru task, but note that if it is a POPUP then the normal processing described in this FAQ will not be performed.

NOTE: If a task's session data is removed, such as by the keep data on exit option, then all memory of any previous activity for the task will be lost and any future activation of the task will be treated as if it were the first activation.

Selection (fixed) A task which is activated from the menu bar does not have a parent task, therefore cannot have any context passed down to it in the $where variable from the parent task. For tasks which perform a database SELECT this will cause all available rows to be retrieved from the database. This behaviour can be altered by defining selection criteria in the format fieldname='value' within this field. Multiple fields can be specified using fieldname1='value' AND fieldname2='value'. This data will be loaded into the $where variable so that it can be used in the WHERE clause of the SQL SELECT statement.

Please note the following:

  • The use of a SEARCH screen will not alter the contents of the $where variable.
  • The contents of the $where variable will NOT be cleared when the RESET button is pressed.
  • In page controllers which deal with more than one table object (such as LIST2, LIST3, MULTI2, MULTI3 and MULTI4) this value will be appended to the $where variable for the first object, and the $this->sql_where variable for subsequent objects as it may have been filtered out of the $where variable which is extracted from the previous object.
Selection (temporary) When a task of type LIST is activated it is possible for a child SEARCH screen to be activated in order to filter the data which is retrieved from the database by including additional search criteria. This temporary selection criteria will be loaded into the $search variable so that it an be used when the task is first initiated, as if it was supplied from a SEARCH screen.

Note the following:

  • The use of a SEARCH screen will cause the contents of the $search variable to be replaced.
  • The contents of the $search variable will be cleared if the RESET button is pressed.
Settings This provides the means to send parameters to the component in order to affect its behaviour. These parameters will be made available in $GLOBALS['settings']. The format is name=value where:
  • name is the variable name without a leading $ sign
  • value is the value for that variable without enclosing quotes.

Multiple entries may be defined by separating them with '&' as in name1=value&name2=value.

Any entries defined here will be available to any script which is run during the execution of this task, and will also be written out in the <params> area of the XML document so that it is also available to the XSL transformation process.

Here are some examples used by the framework:
This affects a POPUP task by changing the select controls from checkboxes to radio buttons, thus allowing only a single row to be selected. This is demonstrated in Choose Task (menu).
This can also be used in tasks of type UPDATE 1 and DELETE 1 to restrict updates and deletes to the person who created the record. Simply insert an entry where <fieldname> is typically created_user (the field which identifies who created the record).
Patterns like LIST 2 which deal with more than one entity cannot normally be run directly from a menu as there is nothing available in the $where string, which causes the task to fail. This setting will bypass that check, but be aware that without any selection criteria this will retrieve all available records from the outer database table.
When a batch task is activated it normally logs its progress in a file which is written to the LOGS directory. If that task is activated from a navigation button in an online screen it will, by default, automatically jump to a filepicker screen so that the log file can be viewed. This behaviour can be overridden with this setting.

Other settings may be used, but they will be ignored by the framework and therefore must be dealt with by custom code.

Order By This is only relevant for those tasks which retrieve multiple occurrences from the database. If used at all the contents of this field will be used in the ORDER BY clause of the SQL SELECT statement, so it should contain a valid field name, or a list of names separated by commas.
Keep Data on Exit

This switch has the following options:

  • Yes - details for the task will persist, so if it is activated again it will resume from where it left off.
  • No - details for the task will not persist, so if it is activated again it will start afresh.

This should only be used for tasks of type LIST, POPUP or TREE which are suitable for restarting from the previous state. It will be ignored for enquire, update and delete forms where a new selection is always passed down from the previous form. If used in an ADD form it will cause the data for the previous addition to be loaded as default values, which could cause confusion.

A task can be in one of the following states:

  • Active - It is the current task. It is shown as the last entry in the bottom line of the menu bar.
  • Suspended - It has passed control to another task, usually from a button on the navigation bar, and will resume processing once that other task has finished. All tasks which appear in the bottom line of the menu bar in front of the current task are suspended tasks.
  • Terminated - It no longer appears in the bottom line of the menu bar.

When a task is active or suspended data is stored in the SESSION array so that if it is reactivated later it can resume processing from where it left off.

When a task is terminated, either by pressing the SUBMIT or CANCEL/CLOSE buttons, the default behaviour is to erase this data so that the next activation can start afresh. This behaviour can be altered by changing this switch from 'NO' to 'YES'.

NOTE: If control is passed to another task by any means other than by the use of the SUBMIT, CANCEL or CLOSE buttons then the data for the current task will remain in the session file. This data will be reused on the next activation unless it is overridden by new selection criteria.

Run at End This identifies the task which is to be run when the current task ends. For example, to implement the business rule "after viewing a sales order the user must always add a comment to that sales order" you set the run_at_end field of the "view sales order" task to "add a comment".

This facility has the following limitations:

  • The main task must have a screen which displays a single record, not multiple records.
  • The main task cannot be given a selection of records to display which would cause the scrolling area to be displayed. This is because it can only pass the primary key from a single occurrence to the run_at_end task.
  • If the run_at_end task is run manually before the main task ends it will not be run again automatically.
Run at Cancel This identifies the task which is to be run when the current task is cancelled without performing a database update. For example, to implement the business rule "if the user is asked to add a comment to an order, but cancels, then a default comment must be added" you set the run_at_cancel field of the "add a comment" task to "add a default comment".

Note that if the run_at_cancel task has any user dialog it opens up the possibility that it may be cancelled before it completes its task.

If the main task performs a commit (database update) before it terminates then it wasn't cancelled, so the run_at_cancel task will not be run.

Quick Navigation In LIST screens which display multiple rows of data there are buttons in the navigation bar which allow the user to jump to a child task while passing the identities of those rows which have been selected. This means that jumping to a child task always takes a minimum of two keystrokes - one to tick the select box of a row and another to select the child task. In those cases where it is common for a user to select a particular task for a single row the two keystrokes can be a little annoying. For this situation the quick_navigation column allows the child task to be selected with a single keystroke.

If a value for quick_navigation task is entered then whenever this task is run an extra column will be added to the screen at the start of each row and will contain a quicknav icon quicknav (1K) which, when pressed, will automatically jump to the specified child task and pass to it the primary key of the current row.

This button will have "QNav" as its column heading. If you hover your mouse over it the task description will be displayed a s a tooltip.

Note that this option is only valid for LIST screens.