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	If this field is used it should contain the identity of another task. The first time this 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 this task which will carry out its normal processing using any parameters that may have been returned by the passthru task. This mechanism is typically used for tasks of type LIST where it is required that a SEARCH screen be processed first. 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: `select_one=TRUE` 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). `<fieldname>=$logon_user_id` 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). `allow_empty_where=TRUE` 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. 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 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.

http://www.tonymarston.net
http://www.radicore.org

counter