In this documentation the term "context" is used to mean the identity of an entity within the application database, and usually consists of the primary key from the associated database table.
An application developed using this framework may have many tasks dealing with many entities, and a common structure is to start with a LIST screen which shows summary information from several occurrences from a particular database table. From here the user can select one or more occurrences and navigate to other tasks, such as an ENQUIRY screen, to show more details concerning the selected occurrences. The processing of selecting occurrences in a parent task then navigating to a child task to show more levels of detail is known as the drill down technique. The selecting of occurrences in the parent task determines the context which is passed to the child task so that when the child task is activated it knows which occurrence(s) to deal with without having to ask the user. The user does not have to type in the identities of the selected occurrences, simply mark them as "selected" and press a button on the navigation bar.
For example, a user may start at a "List Customer" screen which shows several rows of summary information, one row per customer. The user can select one or more rows in this screen and press the "Show Details" button to activate a different screen which shows more details concerning those customers, one customer at a time. The user can then press the "Show Invoices" button to show a list of invoices which were sent to the current customer. Within this screen there may be another button to "Show Invoice Lines", and so on. There is no limit to the hierarchy of levels which may be navigated in this way, and context is automatically passed from the parent screen to the child screen.
This is a two-part operation which involves the following:
The child tasks which are available to any parent task will be indicated on its navigation bar. A parent can have any number of children, and a child can have an number of parents. It is also possible for a child task to have children of its own, and each of those children to have grandchildren, and so on.
If a parent task shows multiple rows the user marks individual rows for selection by clicking on the checkbox in the "select" column at the start of each row. A row is selected if its select box is "On" and not selected if its select box is "Off".
If the parent task does not contain multiple selectable rows - in other words it only shows information concerning a single database row - then the identity of the current row will automatically become the selection which is passed to the child task.
The mechanism for extracting the identities of the selected rows is as follows:
$selectionstring similar to the following:
(fieldname='fieldvalue') (fieldname1='fieldvalue' AND fieldname2='fieldvalue') (fieldname1='fieldvalue') OR (fieldname1='fieldvalue')This
$selectionstring has the following format:
name='value'pair will be separated by ' AND '.
$wherestring for the current task will be extracted, using _cm_getWhere() to allow any temporary modifications.
$wherestrings into the child task's area in the $_SESSION array.
Whenever a child task/object is activated it will look for any selections which were passed down to it from its parent task/object before it retrieves any data from the database. The procedure is as follows:
$wherestring and the
$selectionstring will be extracted from the task's area in the $_SESSION array, not from arguments in the URL. This means that they will not be visible to the user.
$selectionstrings, but their priority is as follows:
$selectionis not empty then move
$wherestring will then be used in all subsequent database retrievals.
In the case of ADD2 tasks both the
$selection strings will be made available to the _cm_initialise() method.
$wherestring will be filtered to remove any references to fields which do not exist in the current database table (see Different Names). This will prevent the subsequent database retrieval from failing. This list of fields is obtained in the following manner:
Some tasks, such as those which are based on the LIST2, LIST3, MULTI2 and MULTI3 patterns, contain more than one database object either in an outer-inner or outer-middle-inner configuration. The processing flow starts with the outermost object and moves in sequence down to the innermost as follows:
$wherestring with the following format:
(fieldname='fieldvalue') (fieldname1='fieldvalue' AND fieldname2='fieldvalue')
$wherestring is passed to the next object so that it can retrieve its own records from the database (see Different Names).
$wherestring which is then passed to the third object.
$selectionstring will be extracted from the innermost object using the procedure described above so that it can be passed to the next task.
If a task is activated from a button in the menu bar there is no user-definable context which can be passed to it. It is possible, however, to provide preset selection criteria in various ways as documented in FAQ 71.
Note that if the
$where string, as passed down from a parent object, contains a reference to a field which exists in the current table but with a different name in the parent object, then that name must be converted manually into the one used by the current table otherwise the subsequent call to getData() may not retrieve the correct records. This is typically the case where the primary key of the parent table has a different name from the foreign key in the child table. This conversion of field names can usually be performed in the _cm_pre_getData() method using code similar to the following:
$where = str_replace('node_id=', 'node_id_snr=', $where);
Note that although the $parent_relations array contains information regarding which fields are used in the relationship between two tables, or even where a table is related to itself, this is only used in the ON clause of a JOIN when that table object is asked to construct an sql SELECT statement prior to retrieving its own data. This information cannot be used to automatically translate field names in a WHERE string which is passed down from an external source as there is no information which identifies which of the many possible relationships is involved.
This is described in more detail in FAQ129.