Rapid Application Development toolkit for building Administrative Web Applications

Transaction Patterns for Web Applications

(formerly called "Dialog Types/Patterns/Templates for Web Development")

By Tony Marston

2nd August 2003
Amended 1st June 2021

As of 10th April 2006 the software discussed in this article can be downloaded from www.radicore.org

Introduction

Forms Families

Screen Area

Menu Bar

Title & QuickSearch Bar

Navigation Bar

Column Headings

Data Area

Message Area

Pagination Area

Scrolling Area

Action Bar

Miscellaneous

Version Number

Internationalisation (I18N)

Associated/Related Rows

Add/Create/Insert

Add 1

Add 2

Add 3

Add 4

Add 5

Add 6

Add 7

Background processing

Batch

Delete

Delete 1

Delete 2

Delete 3

Delete 4

Erase 1

Enquire/Read/Display

Enquire 1

List/Browse

List 1

List 2

List 3

List 4

Multi-Purpose

Link 1

Multi 1

Multi 2

Multi 3

Multi 4

Multi 5

Multi 6

Output

Output 1 - CSV

Output 2 - PDF (list view)

Output 3 - PDF (detail view)

Output 4 - CSV (with column selection)

Output 5 - PDF (address labels)

Output 6 - CSV (tree view)

Picklist

File Picker

File Upload

File Download

Popup

Search

Search 1

Timetable

Timetable1

Tree

Tree View 1

Tree View 2

Tree View 3

Update/Modify

Update 1

Update 2

Update 3

Update 4

Update 5

Choosing which template to use

List 1, List 2 or List 3?

Add 1, Add 2, Add 3 or Add 4?

Delete 1, Delete 2, Delete 3 or Erase 1?

Update 1, Update 2, Update 3 or Update 4?

Link 1, List 2 or Multi 2?

Multi 1, Multi 3 or Multi 4?

Amendment History

Introduction

For a definition of the underlying motivation behind this article please refer to What are Transaction Patterns? This is also based on a concept called The Power of Component Templates which I first encountered in my previous language.

In a previous article entitled A Development Infrastructure for PHP I wrote that in my methodology I categorise components by their structure, behaviour and content. From this I have been able to create a set of standard patterns or templates which are comprised of the following:

• The structure - an XSL stylesheet which defines what the transaction's output will look like when it is rendered into HTML.
• The behaviour - a Transaction Pattern (Controller) script which defines what the transaction does, what methods it will call on its dependent objects.
• The content - supplied from one or more of the components which exist in the business layer.

These also represent components in the Model-View-Controller design pattern:

• Structure is represented by the View
• Behaviour is represented by the Controller
• Content is represented by the Model

Each different pattern has its own controller script, but several controllers can share the same XSL stylesheet. Each Model can be accessed by any number of patterns.

Each user transaction in the application will have its own Component script which will identify which pattern (controller and view) is to be executed on which database table (model).

The purpose of this document is to describe the various templates/patterns which currently exist in my software library.

In order to create a user transaction from a pattern it is first necessary to import the structure of your application database into the Data Dictionary, then export each table definition to provide a class file which will be used as the Model in the Model-View-Controller design pattern. In the following sections each database table and its associated class file may be referred to as an "entity". While most of the following patterns deal with a single entity there are some which deal with two or more.

From within the Data Dictionary it is then possible to select a table/entity and then generate a transaction, or a family of transactions, from a selection in a dropdown list. The transactions that are generated will be sufficient to perform the basic functionality of moving the data between the database and the user interface, with default data validation. By default the screen structure will contain all fields/columns in the order in which they were defined in the database, but the screen structure file can be easily customised to provide a different layout. The table class file can also be modified to enhance or customise the standard processing, such as the implementation of business rules, by copying any of the empty customisable methods from the abstract table class to the database table class and adding in the required code. The generation process will also add the necessary entries to the TASK, MENU and NAVIGATION_BUTTON tables in the MENU database

This article is also covered by a video titled What are Transaction Patterns and how are they used to achieve Rapid Application Development?

Forms Families

Rather than have large complex components which can perform several functions I much prefer to build small simple components which perform a single function each. While this does increase the number of components within an application it also increases the amount of reusable code which results in faster development times. Thus to maintain the contents of a typical database table where I need to provide the functions to list, search, insert, update, enquire and delete I create a family of components which is arranged in the structure shown in Figure 1. Note that these constitute six separate use cases each of which has its own Controller and not a single use case which so many programmers still insist on using. I gave up on that idea in the 1980s, as documented in Component Design - Large and Complex vs. Small and Simple.

Figure 1 - A typical Family of Forms

Each of the boxes in the above diagram is a clickable link. Please note the following:

1. This family is not implemented as a single task (use case or user transaction) with a single Controller talking to a single Model, it is implemented as a collection of separate tasks, each with its own Controller, which talk to the same Model. In some cases a Controller can talk to more than one Model.
2. Each task will have its own entry on the MNU_TASK table. This entry will point to a component script which exists in the file system. This will be shown in the URL when that task is activated. This script does nothing more than identify which Model(s), View and Controller will be used to carry out this task.
3. Each Controller performs a predetermined set of operations on its Model by implementing one of the catalog of Transaction Patterns.
4. Because a Controller does not contain any hard-wired Model names or column names, which would produce tight coupling, it can be used with any Model.
5. No Controller can have more than one View. The LIST task uses a screen structure file for a List View while the others use a Detail View.
6. In the above arrangement the LIST form is known as the parent while the others are its children. The child tasks can only be accessed from a navigation button in the parent. The parent, depending on which pattern it implements, can either be accessed from a menu button, or it may be accessed from a navigation button in a different but related task.
7. Because each of the above operations is a separate task it makes it easier to grant or deny a user's access to individual tasks by using the capabilities of the Role Based Access Control (RBAC) system which is built into the framework.

Except for the INSERT the child component will need the primary key of an occurrence in the parent component before it can load any data on which it is supposed to act. In this case the required occurrence in the parent screen must be marked as selected using the relevant checkbox before the link/button for the child component is pressed. Note that it is possible to select multiple rows before jumping to the child screen, in which case the child screen will include a scrolling area so that you can scroll through the selected rows one at a time.

It should be noted that in my web development environment all HTML output is produced by XSL transformations using XML files created by the Dialog Type scripts. Each component will therefore require its own Component script to specify the content as well as an XSL file to display that content. Another area of reuse I have managed to achieve is for several components to share the same XSL file, as shown in Figure 2.

Figure 2 - Sharing XSL files

Note: each of the boxes in the above diagram is a clickable link.

The parent screen (LIST) shows data for multiple database occurrences in summary form, with each occurrence taking up one line going across the screen with one set of column headings at the top. The child screens (SEARCH, INSERT, UPDATE, DELETE and ENQUIRE) shows data for a single database occurrence in detail form going down the screen, with a label in front of each field. As the child screens have an identical structure they can all share the same XSL file.

In my original infrastructure each database table required its own version of the list.xsl and detail.xsl files as the table, field names and field labels had to be hard-coded inside them, but I have since enhanced my XSL library so that a small number of generic stylesheets can be used for any number of database tables. This is documented in Reusable XSL Stylesheets and Templates and uses updated versions of my std.list1.xsl and std.detail1.xsl stylesheets which allow the table name(s), field names and field labels to be passed in as part of the XML data.

Screen Area

The following sections contain references to the screen area. This is the area within the browser window running on the client device which the software may fill with data. It must be remembered that each client may have a different screen resolution, so that what fits easily into a screen at one resolution may need scroll bars in another. It must also be remembered that users may alter their browser's font size which may also affect how much data can be displayed without the need for scroll bars.

It is not possible to dictate either the screen resolution or the font size used by individual clients, nor is it practicable to limit the amount of data generated by individual forms to fit the smallest screen window that may be encountered. What is important is to output enough data to make each screen usable based on the average screen resolution and default font size that are currently in use. On some clients this may leave areas of empty space while on others it will overflow the available area and require the use of scroll bars. This is a fact of life which cannot be avoided. Unless, of course, the framework provides a responsive interface which will alter the screen layout depending on the size of the screen being used.

All the screen layouts in the following sections are shown broken down into separate areas or zones where the data for some zones is provided automatically by the framework while others are provided by application components. The following zones are provided by the framework:

• Menu Bar
• Title & QuickSearch Bar
• Navigation Bar
• Column Headings (for data areas containing multiple rows)
• Message Area
• Pagination Area (for data areas containing multiple rows)
• Scrolling Area for data areas containing single rows
• Action Bar

The following zone is provided by the application:

• Data Area - Note that shows multiple rows in a horizontal arrangement for LIST screens, while other screens show a single row in a vertical arrangement. In some layouts, such as LIST2, LIST3 and LIST4, there are separate zones, each with its own name, for different application components.

Menu Bar

Menu buttons are defined on the MENU table within the MENU database. They are shown as a series of hyperlinks at the top of the screen which allow the user to navigate around different parts of the system. These links are shown in two rows, as in the following example:

Menu Bar with text links

The text on the top row can be changed to images as in the following:

Menu Bar with image links

The top row shows the current logon identity on the left, with a series of hyperlinks on the right:

• add to favourites - this will add the current task and its menu bar to the favourites area of the Menu/Home Page. When one of these favourites is selected the task will be activated with its menu bar reconstituted to the saved values.
• logout - this will cancel the current session, log the user out and return to the LOGIN screen.
• logout (all) - this will cancel all sessions which may currently be open on the client device (see Appendix H for details), log the user out and return to the LOGIN screen.
• new session - this will generate a new session name with a new session id for maintaining session data on the server. This is useful after creating a cloned browser instance which would otherwise share the same session data as the original instance. See Appendix H for details.
• print - this will cause the current page to be redisplayed without any menu buttons, navigation buttons, action buttons, pagination or scrolling areas, thus enabling it to be printed through your browser's print facility without being cluttered with unwanted details. This hyperlink will then change to 'noprint', which, when pressed, will return the page to its previous state.
• help - this will invoke the online help facility for the current screen.

The ability to change the text into images is documented in FAQ99.

The middle row is the current set of menu options. If you click an option which is a sub-menu then the whole list of options will change. If you click an option which is not a menu then the whole area below the menu bar will change to reflect the requirements of that option. The background colour of that option in the menu bar will then change to be the same as the second row to signify that it is 'active'. The other options will have a different background color to signify that they are 'inactive'.

The bottom row of the menu bar will trace the route from the starting page to the current page. This list is sometimes known as 'breadcrumbs' as it allows the user to find his way home if he gets lost. As each new task is selected it will be added to the list. When a task is terminated it will be removed from this list. An item in this list will be available as a hyperlink if it is different from the current page.

Title & QuickSearch Bar

This exists between the Menu Bar and the Navigation Bar. In most cases the screen title is shown on its own, as in the following:

Title Bar

In some cases the task may be configured (see FAQ145 for details) to include a QuickSearch bar, as in the following:

Title Bar with QuickSearch Bar

This is a quicker alternative to the separate SEARCH screen. The QuickSearch bar is comprised of the following elements:

• A dropdown list which contains a selection of column/field names.
• A text box into which your search criteria can be entered.
• A SEARCH button.

If you select a field name from the dropdown list, enter a value into the text box, then press the SEARCH button, this will cause the task to retrieve data which matches this search criteria and refresh the screen display with the first page of available data.

Navigation Bar

Navigation buttons are defined on the NAV_BUTTON table within the MENU database. They are shown as a series of buttons in an area immediately below the Title & QuickSearch Bar. They are similar to menu buttons in that they pass control to other tasks within the system, but as each parent task has its own set of navigation buttons for child tasks, it is possible to pass context from the parent to the child task.

Navigation Bar

The top row contains buttons which can be pressed without selecting any items from within the body of the current screen. These will typically be:

Upon returning from a SEARCH screen the page number will be reset to 1, and any column sorting settings will be cleared. New data will be retrieved from the database using the search criteria, and will be presented in the default sort sequence starting at page 1.

The bottom row contains buttons which cannot be pressed without selecting one or more items from within the body of the current screen. These will typically be:

This selection process enables the primary key(s) of the selected occurrence(s) to be passed down to the child form so that they know which occurrences to process.

Upon returning from a child function the parent function will re-retrieve its data according to the current settings (page number, sort sequence, etc). This is so that any changes made by the child function can be included in the screen display.

The middle row contains a series of options which act upon the body of the current screen. These options are:

It is possible to prevent these parts from being displayed with the following settings in your code:

    $this->xsl_params['noselect']  = 'y';  // remove 'select all/unselect all ' hyperlinks
    $this->xsl_params['noshow']    = 'y';  // remove 'show 10/show 25/...' hyperlinks

Column Headings

On screens which show multiple rows with headings above each column, such as in List 1 and List 2, the column headings may be shown as hyperlinks, as in the following example:

Column Headings

If the number of available rows is not 2 or more then the column headings will be shown as plain text, not hyperlinks, as there will be no point in sorting only 1 row.

If one of these hyperlinks is pressed it will cause the current page to be regenerated after the data is sorted on the selected column. Note that this causes all data which satisfies the current selection criteria to be sorted, not just the data on the current page. An image will appear next to the column heading to indicate that the data has been sorted on this column. If this or any other such hyperlink is pressed again it will cause the sort sequence to alternate between ascending and descending, with the image next to the heading being switched accordingly.

Any column sorting can be cleared by using the RESET button in the action bar.

There are two ways to prevent a column heading from becoming a hyperlink for sorting:

1. To disable sorting on all column headings use the following code:

   $this->xsl_params['nosort']    = 'y';  // remove sort hyperlinks in column headings
   

2. To disable sorting on individual columns use the 'nosort' => 'y' option in the screen structure file, as in:

   $structure['inner']['fields'][] = array('node_desc' => 'Description', 'nosort' => 'y');
   

Data Area

The way that data is displayed in this area depends on whether it is capable of displaying single or multiple occurrences (rows).

Single

The data for a single occurrence will be displayed vertically, with labels on the left and data on the right. The field value will be shown in the right-hand column while a suitable label will be shown in the left-hand column, as in the following: For functions which allow inserts or updates an asterisk in front of a label is used to indicate that the field cannot be left empty. If there is an error with the user's input a suitable error message will be shown immediately under the offending data. Other screen layouts are also available. For example, you can have more than one piece of data in a single line, as in the following: It is even possible to have data spanning more than one line, as in the following: For details on how these different layouts can be specified please refer to XSL Structure files in The Model-View-Controller (MVC) Design Pattern for PHP.

Multiple

The data will be displayed horizontally, one occurrence per line. Each field will be shown in a separate column, and above each column will be a set of column headings, as in the following: Alternate rows will be shown with a different background colour to help them stand out from each other. The first column will usually be a checkbox or radio button which has different uses depending on the type of function: For functions of type LIST, MULTI 2, TREE VIEW 1 and TREE VIEW 2 these will be a method of selecting one or more occurrences before pressing one of the buttons in the navigation bar. This will cause the primary key of the selected occurrence(s) to be passed to the function which is associated with that navigation button. For functions of type POPUP these will be a method of selecting one or more occurrences before pressing the CHOOSE button in the action bar. This will cause the primary key of the selected occurrence(s) to be passed back to the previous function. For functions of type LINK 1 these will initially indicate if an occurrence of the link entity exists or not. By changing the setting of any select box and pressing the SUBMIT button on the action bar then the corresponding occurrence of the link entity will be created or deleted as appropriate. It is possible to modify certain aspects of this display at runtime. Please refer to: How can I make a single row in a multi-row area non-editable? How can I remove the select box from a single row? How can I hide/remove columns in a multi-row display? How can I modify column labels at runtime? How can I replace a column and its label at runtime?

Message Area

Messages related to a particular field will usually appear immediately below the field's data in the data area. There may be circumstances where there is a message which cannot be attached to any field on the current screen, or where there is a general message or instruction. In this case such messages (as there may be more than one) will appear immediately below the data area.

In screens of type Delete 1, for example, this area will either display a confirmation message or it will give a reason why the record cannot be deleted.

Pagination Area

For some screens there may be more records available than can be displayed at any one time (see LIST 1 and LIST 2 for examples). In this case the number of available rows will be broken down into manageable 'pages' and a pagination area will be made available which will allow the user to move forwards and backwards through the available pages. The number of rows per 'page' is governed by a variable within the class for each database table, but this may be altered at run-time by choosing one of the options in the middle row of the navigation bar.

There are two display options which are available, governed by the Pagination Width setting on the Menu Control Record. If this value is zero then the default display will be used.

Pagination area (default display)

If the value is greater than zero then a 'Google style' display will be used.

Pagination area (Google style display)

The pagination area is broken down into the following sections:-

Scrolling Area

There may be screens in which it is possible to step through a series of selected or available items (see Delete 1, Enquire 1, List 2, Multi 2 and Update 1 for examples) either as well as or instead of the usual pagination options. In this case there will need to be a separate area to control the movement between the selected/available items. This 'scrolling' will usually be for one occurrence (item) at a time rather than multiple occurrences, and will only be shown when multiple occurrences are actually available.

Note that there may be more than one scrolling area to a page (as in Multi 2), so each area will be placed immediately below the data to which it relates.

There are two display options which are available, governed by the Scrolling Width setting on the Menu Control Record. If this value is zero then the default display will be used.

Scrolling area (default display)

If the value is greater than zero then a 'Google style' display will be used.

Scrolling area (Google style display)

The scrolling area is broken down into the following sections:-

Action Bar

These buttons are defined within the controller script for each dialog type as they allow the user to choose an action which that controller is able to perform, such as updating the database, terminating the screen, or resetting the selection criteria. These buttons are situated in an area at the bottom of the screen.

Action Bar

The SUBMIT button(s) will be on the left while any other buttons will be on the right. The number of buttons will vary according to the circumstances.

The text which appears underneath the action bar is described in Version Number.

Miscellaneous

Version Number

There may be several application subsystems running under the Radicore menu system, and it is sometimes useful to know the version number of each of those subsystems. This is now an optional feature which is activated by placing a file called version.txt in the subsystem directory. If such a file is found when running a script from within that subsystem then its contents will be retrieved and displayed at the bottom of the screen underneath the action bar. The contents of this file should be a text string of up to 40 characters.

Internationalisation (I18N)

It is sometimes a requirement that an application is able to operate in more than one language. This can be a problem if all text, such as titles, labels and messages, is hard-coded within the application. It is far less of a problem if this text is maintained in separate text files as this gives the ability to modify the text in those files without modifying the application. Whenever the application requires a piece of text it uses an API which, when given the identity of the text and a language code, will retrieve that text in the required language and return it to the application.

In the Radicore framework all text is maintained in a separate 'text' directory, with a separate subdirectory for each language code. Each file therefore contains text in a single language. Adding a new language to the application is as simple as 1-2-3:

1. Create a new subdirectory for the required language code.
2. Take an existing text file and translate the contents.
3. Put the translated file into the new subdirectory.

Obtaining the user's language code is simple in a web application. The user can define his/her preferred language in the browser settings, and this information is made available to the application on the server through the HTTP_ACCEPT_LANGUAGE variable.

This is explained in more detail in Internationalisation and the Radicore Development Infrastructure (Part 1) and Part 2.

Associated/Related Rows

When a pattern which reads from the database contains several table objects, such as LIST2 and LIST3, it will start its data retrieval at the outermost (parent) table before it proceeds to the innermost (child) table. If multiple rows from the outer entity are retrieved they will be shown one at a time, and a scrolling area will be shown to allow the user to traverse through the other rows. The retrieval on the inner table will be restricted to those records which are associated with the current row of the outer table. In other words, the primary key of the outer table will be used to obtain the foreign key on the inner table. This is done by calling the getForeignKeyValues() function which will attempt to find the correct primary-to-foreign key relationship between these two tables using the contents of the $parent_relations array in the child object. Before it returns it will call the _cm_getforeignkeyvalues() method in the child object in case any adjustments to the foreign key need to be made. The foreign key for the inner/child table will be extracted into a string such as:

fieldname='value'
  or for composite keys:
fieldname1='value' AND fieldname2='value'

This string will then be passed to the child table as the $where argument on the call to getData().

When passing control from one task to another by means of a navigation button the getForeignKeyValues() function cannot be used as neither task knows the identity of the other's table. The primary key of the selected row(s) in the parent task will be extracted into a $where string and passed to the child task. Note that the Radicore framework assumes that the field names in the primary key of the outer/parent table are exactly the same as the field names in the foreign key of the inner/child table. If they are not then you will have to modify the $where string manually in the _cm_pre_getData() method using code such as the following:

$where = str_replace('node_id=', 'node_id_snr=', $where);

Add/Create/Insert

These functions will enable the user to add new entries to the database.

Add 1

This is typically called from a LIST 1 task in order to add 1 new row at a time to the database. Upon initial entry this screen will usually be blank, but some fields may be shown with default or initial values.

This screen contains the following areas:-

Add 1 screenshot

Add 2

This screen has a similar layout to the ADD 1 screen, but is called from a LIST 2 task. Upon initial entry this screen will retrieve the parent details as identified in the previous function and show them as read-only at the top of the data area. The remaining details will usually be blank, but some fields may be shown with default or initial values.

This screen contains the following areas:-

Add 2 screenshot

Add 3

This function does not have a visible screen. It is used to add occurrences to the link entity which exists in the middle of a MANY-to-MANY relationship. This is called by a parent function which passes it the identity of an occurrence from one of the MANY tables. This function will then call a popup screen which will allow the user to select one or more occurrences from the second MANY table. This function will then use the identity from the first MANY table with the selection list from the second MANY table to add new occurrences to the intermediate link table (using multiple calls to the insertRecord() method).

This process is represented in Figure 3.

Figure 3 - The processing of an ADD 3 function

Note that in order to switch the popup screen from allowing you to choose a single occurrence (where the SELECT column contains multiple radio buttons), to choosing multiple occurrences (where the SELECT column contains multiple checkboxes) you must change the contents of the _cm_popupCall() method so that $settings['select_one'] is FALSE. This will also cause the CHOOSE NULL button to be removed from the popup screen.

Add 4

This function does not have a visible screen. It is used to add one or more occurrences to a database table using information passed down from the parent screen. This information is used in the getInitialDataMultiple() method to construct an array of entries which is then added to the database using the insertMultiple() method. Upon completion it will return control to the parent screen.

Working examples can be found in the Data Dictionary subsystem with the Import Databases, Import Table and Import Columns functions.

Note that the insertMultiple() method can also perform updates and deletes as well as inserts.

Add 5

This function allows several child occurrences to be added to a selected parent occurrence with a single input screen. Upon initial entry this task will retrieve the parent details as identified in the previous function and show them at the top of the data area. The contents of this area may be modifiable, or may be set to 'noedit'. A number of blank rows will be shown below the column headings in the child area which the user can fill in before pressing the submit button.

By default the number of blank rows which is first displayed in the child area is determined by whatever code is in the getInitialDataMultiple() method. During the execution of the script it is possible to include custom buttons to add or remove rows from this area as documented in FAQ156.

Note that the insertMultiple() method call also perform updates and deletes as well as inserts.

This screen contains the following areas:-

Add 5 screenshot

Add 6

Where there are two tables in a parent-child relationship this function will allow a new record to be added to the parent table and a single record to be added to the child table in a single operation. This avoids the need to have separate tasks to add records to each table.

This screen contains the following areas:-

Add 6 screenshot

Add 7

This is similar to Add 6 but will allow multiple entries to be added to the child table.

By default the number of blank rows which is first displayed in the child area is determined by whatever code is in the getInitialDataMultiple() method. During the execution of the script it is possible to include custom buttons to add or remove rows from this area as documented in FAQ156.

This screen contains the following areas:-

Add 7 screenshot

Background Processing

All other patterns in this catalogue are for tasks which are run from within the web browser, but they must be completed within a time limit otherwise the processing will be aborted. If a script needs to run for a longer time one option is to run it from the command line in which case there is no time limit. See FAQ56 for details on how to set up a batch job. As well as via the command line, this type of job can also be initiated via a cron job which will run it at scheduled times.

Batch

This type of task will allow a batch job to be initiated from within the web browser by a navigation button. The generated script must follow the guidelines which are outlined in FAQ56. When the navigation button is pressed to activate this task the following events will take place:

1. The current session data will be copied to a new session with a new session_id.
2. A new entry will be created in this new session to hold the details of the task which is about to be initiated. The selection and sorting criteria used by the current task will be inserted into this new entry's details so that they will be available to the batch task.
3. A command line string will be constructed as follows:
   • Windows: "start php_exe $script_name PHPSESSID $session_id $extra_args"
   • Linux: "/usr/bin/php '$script_name' PHPSESSID $session_id $extra_args >/dev/null &"
   This will then be processed by the popen() function using mode 'r'.
4. After the parallel task has been initiated the current task will continue by automatically jumping to the Show Batch Log File screen. The user can either wait here until the output from the batch task appears, or continue working with other tasks.

Note that this task cannot have any dialog with the user, although it is possible to pass it any selection and sorting criteria from the current task.

Note also that while it is possible for a batch task to activate another task this other task must also be a batch task which calls the batchInit() function and not the initSession() function. There are some page controller scripts which can be run in both online and batch modes as these contain the following lines of code:

if (preg_match('/cli/i', php_sapi_name())) {
    // being run from the command line, so initialisation has already been done
    $batch_errors = null;
} else {
    require_once 'include.general.inc';
    initSession();      // load session variables
} // if

The page controller script can then be called from a component script as shown in the following example:

$stdout = '../logs/inventory_item(csv).html';
$csvout = '../logs/inventory_item.csv';

ini_set('include_path', '.');
require 'std.batch.inc';

batchInit(__FILE__);

// custom code starts here
$table_id = 'inventory_item_s03';   // table name
require 'std.output1.inc';          // activate page controller
// custom code ends here

batchEnd();

Delete

These functions will enable the user to delete entries (or remove links to entries) from the database.

Delete 1

Upon initial entry this function will retrieve a record from the database using the primary key(s) passed down by the previous form. It will then use the $child_relations array in the database object to check if any subordinate entries exist on any related database tables which will prevent the deletion from continuing. If there are any such constraints then an error message will be generated.

This screen contains the following areas:-

Delete 1 screenshot

If it is necessary to prevent everyone except the record's creator from deleting the record this can be achieved by putting the string created_user=$logon_user_id into the SETTINGS field for the task.

Delete 2

This function does not have any dialog with the user. It receives an array of primary keys which were selected in the previous form, deletes them one at a time using the deleteMultiple() method, then passes control back to the previous form with a message saying how any occurrences were actually deleted. This type of function is usually used to delete occurrences from a LINK entity created by an ADD 3 form.

Delete 3

This function is similar to DELETE 2 in that it has no screen dialog, but instead of receiving an array of primary keys it receives selection criteria which may identify any number of occurrences from the specified database table. These occurrences are then updated in a single operation (using the deleteSelection() method), usually by nullifying the column(s) that caused them to be selected in the first place. This is the reverse of a UPDATE 2 function.

Delete 4

This is similar to a LIST 2, but will allow the current occurrence of the parent table, plus all related occurrences on the child table, to be deleted.

Upon initial entry this function will retrieve the first of the selected occurrences from the ONE (parent) table, then retrieve associated rows from the MANY (child) table and display them starting at page 1. It will then use the $child_relations array in the parent database object to check if there are any other restraints which will prevent the deletion from continuing. If there are any such constraints then an error message will be generated.

This screen contains the following areas:-

Delete 4 screenshot

Erase 1

This function is similar to DELETE 1, but instead of stopping if any occurrences on a child table are found for which the delete constraint is set to RESTRICTED it will instead act as if the constraint were set to CASCADE. This will cause ALL child occurrences, and the children of those children all the way down to the bottom of the relationship hierarchy, to be deleted from the database.

Note: this will only erase data from tables which exist in databases which belong to the current subsystem. For example, when erasing a MNU_SUBSYSTEM entry from the MENU database it will not affect related tables in either the DICT database or the WORKFLOW database.

The value of the audit logging flag $this->audit_logging in the initial table object will be passed down the hierarchy to each child object. If set to TRUE then all deleted records will appear in the audit log. If set to FALSE then no deleted records will appear in the audit log. Regardless of what value has been defined for this flag in normal operations an alternative value can be defined in the _cm_pre_eraseRecord() method which will take effect for the current operation only.

Due to the large number of records that can be deleted with a function of this type it should only be created where absolutely necessary, and access permissions should only be granted to responsible personnel. It would also be a good idea to have some sort of export function so that the data can be reinstated if required.

Enquire/Read/Display

This type of function will allow the user to view details from the database. No type of update is allowed.

Enquire 1

Upon initial entry this function will retrieve a record from the database using the primary key(s) passed down by the previous form.

This screen contains the following areas:-

Enquire 1 screenshot

List/Browse

This type of form is used to display multiple occurrences (rows) of a database table. It shows summary details only, one entry per line. It does not allow any updates, but a series of navigation buttons will provide access to other forms/functions/screens that should be able to add, update or delete occurrences of the table.

In these forms the total number of rows may too large to display in a single page, therefore each page may be limited to a certain number of rows. In this case pagination options will be made available which will allow the user to select a particular page to display.

List 1

Upon initial entry this function will display details from the selected table starting at page 1. The number of rows in each page is held within each data object, but can be changed using options in the navigation bar.

It is also possible for selection criteria to be passed down from the previous function, in which case this will be used when retrieving data from the database.

This screen contains the following areas:-

List 1 screenshot

List 2

This function is used in a ONE-to-MANY relationship to display several occurrences of MANY for a selected occurrence of ONE.

Upon initial entry this function will retrieve the first of the selected occurrences from the ONE (parent) table, then retrieve associated rows from the MANY (child) table and display them starting at page 1. The number of rows in each page is held within each data object, as is any default sort criteria.

This screen contains the following areas:-

List 2 screenshot

List 3

This function is used in a PARENT-to-CHILD-to-GRANDCHILD (or OUTER-to-MIDDLE-to-INNER) relationship where both PARENT-to-CHILD and CHILD-to-GRANDCHILD are defined as ONE-to-MANY relationships. For each occurrence of PARENT it will show related occurrences from the CHILD, and for each occurrence of CHILD it will show related occurrences from the GRANDCHILD.

Upon initial entry this function will retrieve the first of the selected occurrences from the PARENT/OUTER table using the selection criteria passed down by the previous form, then for the current PARENT it will retrieve the first of the associated occurrences from the CHILD/MIDDLE table. It will then retrieve associated occurrences from the GRANDCHILD/INNER table and display them starting from page 1.

Note that by default the grandchild/inner entity will not be processed unless the child/middle entity reads a row from the database as the grandchild/inner entity requires the primary key of that row to use as its $where criteria. In some cases the child/middle entity may be optional, in which case it may not retrieve any data from the database, and the grandchild/inner entity will not be processed. To avoid this situation the child/middle entity can set the $allow_zero_rows to TRUE. It should also include code in order to build a dummy entry in $fieldarray to contain fields for the primary key with the optional elements set to NULL, similar to the following:

function _cm_getExtraData ($where, $fieldarray)
{
    $pattern_id = getPatternId();
    if (preg_match('/LIST3/i', $pattern_id) AND $this->zone == 'middle') {
        if (empty($fieldarray)) {
            // insert values to be passed down to child (inner) table
            $parent_data = $this->getParentData();
            $fieldarray['product_id']  = $parent_data['product_id'];  // primary key of OUTER and MIDDLE entity
            $fieldarray['revision_id'] = null;                        // primary key of MIDDLE entity
        } // if
    } // if

    return $fieldarray;
		
} // _cm_getExtraData

This screen contains the following areas:-

List 3 screenshot

List 4

This function is used in an OUTER-to-MIDDLE1-to-MIDDLE2-to-INNER) relationship where both OUTER-to-MIDDLE1, MIDDLE1-to-MIDDLE2 and MIDDLE2-to-INNER are defined as ONE-to-MANY relationships. For each occurrence of OUTER it will show related occurrences from MIDDLE1, for each occurrence of MIDDLE1 it will show related occurrences from MIDDLE2, and for each occurrence of MIDDLE2 it will show related occurrences from INNER.

Upon initial entry this function will retrieve the first of the selected occurrences from the OUTER table using the selection criteria passed down by the previous form, then for the current OUTER it will retrieve the first of the associated occurrences from the MIDDLE table, then it will then retrieve associated occurrences from the MIDDLE2 table. It will then retrieve associated occurrences from the INNER table and display them starting from page 1.

This screen contains the following areas:-

List 4 screenshot

Multi-Purpose

These are called multi-purpose because they may allow more than one function within a single component.

Link 1

This is used to maintain what is sometimes referred to as a MANY-to-MANY relationship but what is actually a ONE-to-MANY-to-ONE relationship, as described in How to handle a Many-to-Many relationship with PHP and MySQL. In this case the MANY table (also known as the INTERSECTION, XREF or LINK table) is used to indicate that a relationship exists between an occurrence of the first (outer) ONE table and an occurrence of the second (inner) ONE table.

A MANY-to-MANY relationship

This is achieved by having the primary key of the MANY (LINK) table constructed by combining the primary keys of the other two (OUTER and INNER) tables - thus the existence or non-existence of a record on the MANY (LINK) table indicates the existence or non-existence of a link between the other (OUTER and INNER) tables.

This function deals with two ONE-to-MANY relationships in the form of OUTER-to-LINK and INNER-to-LINK, which means that one of the ONE tables is designated as OUTER while the other is designated as INNER. It should not matter which is OUTER and which is INNER as they should be interchangeable. It should therefore be possible to create two versions of this transaction where each ONE table takes its turn at being OUTER as well as INNER.

Upon initial entry this function will retrieve an occurrence of the OUTER table using selection criteria passed down from the previous screen. If the selection criteria results in multiple occurrences then scrolling options will be made available.

It will then fill the LINK area by retrieving occurrences from both the LINK and INNER tables by means of an sql JOIN. There may be more occurrences of LINK than can fit onto a single page, so pagination options may be made available.

The INNER/LINK area will show all available occurrences from the INNER table, and if a corresponding entry exists on the LINK table then the SELECT box will be set to ON. If no corresponding entry exists on the LINK table then the SELECT box will be set to OFF. The user may toggle the value within any number of these SELECT boxes, then by pressing the SUBMIT button in the action bar the contents of the LINK table will be adjusted accordingly.

The initial display will show all available occurrences of OUTER which may contain a mixture of selected and non-selected occurrences of INNER. The SEARCH button in the navigation bar may be used to alter the display to show only those occurrence of INNER which have been selected, or alternatively only those occurrences which have not been selected.

Note that the navigation bar does not contain buttons for ADD or DELETE as records on the LINK table are added or deleted by toggling the SELECT box on each line.

In a simple situation the LINK table contains only a primary key, but it is possible for it to contain a number of non-key fields which may have their values displayed in the screen so that the user may change them. Both situations can be catered for by specifying the relevant sql SELECT values in the component script.

This screen contains the following areas:-

Link 1 screenshot

Multi 1

This has a screen similar to Update 1 but will allow one or more occurrences to be either inserted or updated depending on whether they currently exist or not. Due to the fact that rows may not currently exist the default scrolling mechanism cannot be used, therefore an array of occurrences has to be built using the setScrollArray() method which uses any selection criteria passed down to it by the parent screen. The getScrollItem() method is then used to navigate through this array. This allows custom code to be inserted such as the ability to jump over entries in the array depending on certain values being present.

When the SUBMIT button is pressed on each screen either the insertRecord() or updateRecord() method will be called, as appropriate.

In some cases the following additional buttons may appear in the action bar:

• RESET - abandon latest input and reset the screen to its prior contents.
• DELETE - will delete the current record.

Multi 1 screenshot

Multi 2

This will allow multiple MANY occurrences in a ONE-to-MANY (parent-child) relationship to be modified in a single operation.

The identity of the ONE (parent) will be passed down from the previous screen. Occurrences of the MANY (child) will be retrieved and displayed starting at page 1. Standard pagination options will allow the user to step through all available pages. If more than one occurrence of the ONE table was selected then scrolling options will be made available.

Values may be changed in any number of rows, then sent to the database by pressing the SUBMIT button in the action bar.

By default the inner zone can only be used to modify existing rows, although navigation buttons can be used to run other tasks to add or remove rows one at a time. However, it is possible to use custom buttons to add or remove rows dynamically using the procedure documented in FAQ156. Note that these additions or deletions will not be actioned until a SUBMIT button is pressed.

Note that the updateMultiple() method call also perform inserts and deletes as well as updates.

This screen contains the following areas:-

Multi 2 screenshot

Multi 3

This is similar to MULTI 2 but instead of a PARENT-CHILD relationship it displays a GRANDPARENT-PARENT-CHILD relationship. This is expressed as OUTER-to-MIDDLE-to-INNER. Occurrences of OUTER and MIDDLE will be shown one at a time and will be read-only. The multiple occurrences of INNER may be modified.

The identity of OUTER will be passed down from the previous screen. The first available occurrence of MIDDLE will be automatically retrieved, as will associated occurrences of INNER starting at page 1. Standard pagination options will allow the user to step through occurrences of INNER, and while a separate scrolling area will allow the user to step through occurrences of OUTER and MIDDLE.

Values may be changed in any number of rows, then sent to the database by pressing the SUBMIT button in the action bar.

By default the inner zone can only be used to modify existing rows, although navigation buttons can be used to run other tasks to add or remove rows one at a time. However, it is possible to use custom buttons to add or remove rows dynamically using the procedure documented in FAQ156. Note that these additions or deletions will not be actioned until a SUBMIT button is pressed.

Note that the updateMultiple() method call also perform inserts and deletes as well as updates.

This screen contains the following areas:-

Multi 3 screenshot

Multi 4

This is the same as MULTI 2, but will allow updates to both the parent and child tables.

If a field which is editable in the parent area also exists in the $fieldspec array of the child object, then that field will be included in the data which is sent to the child object.

The identity of the ONE (parent) will be passed down from the previous screen. Occurrences of the MANY (child) will be retrieved and displayed starting at page 1. Standard pagination options will allow the user to step through all available pages. If more than one occurrence of the ONE table was selected then scrolling options will be made available.

Values may be changed in any number of rows, then sent to the database by pressing the SUBMIT button in the action bar.

By default the inner zone can only be used to modify existing rows, although navigation buttons can be used to run other tasks to add or remove rows one at a time. However, it is possible to use custom buttons to add or remove rows dynamically using the procedure documented in FAQ156. Note that these additions or deletions will not be actioned until a SUBMIT button is pressed.

Note that the updateMultiple() method call also perform inserts and deletes as well as updates.

Note that by default the contents of the OUTER entity will be retrieved from the database using the getData() method. However, if the use_scrollarray property is set to TRUE within the _cm_initialise() method this will call the setScrollArray() method to provide that data instead.

Multi 4 screenshot

Multi 5

This is similar MULTI 2, but the outer/top/parent entity is used only to enter selection criteria while the inner/bottom/child entity is used to display and possibly amend those occurrences which satisfy that criteria.

The bottom zone can be made non-amendable (read-only) as shown in FAQ110.

Note that the updateMultiple() method call also perform inserts and deletes as well as updates.

The OUTER entity may be programmed to load initial selection criteria which are passed to the INNER entity for automatic retrieval, after which the criteria can be changed and sent to the INNER entity by pressing the RETRIEVE button. Alternatively data for the INNER entity may not be retrieved until after the RETRIEVE button is pressed.

By default the inner zone can only be used to modify existing rows, although navigation buttons can be used to run other tasks to add or remove rows one at a time. However, it is possible to use custom buttons to add or remove rows dynamically using the procedure documented in FAQ156. Note that these additions or deletions will not be actioned until a SUBMIT button is pressed.

The screen contains the following areas:

Multi 5 screenshot

Multi 6

This is similar MULTI 5, but instead of having just two zones it has three in a parent/outer, middle/child and inner/grandchild relationship.

The bottom zone can be made non-amendable (read-only) as shown in FAQ110.

Note that the updateMultiple() method call also perform inserts and deletes as well as updates.

The OUTER entity may be programmed to load initial selection criteria which are passed to the MIDDLE entity for automatic retrieval, then the primary key of the current MIDDLE entity is passed to the INNER entity. After this the criteria can be changed and sent to the MIDDLE and INNER entities by pressing the RETRIEVE button. Alternatively data for the MIDDLE and INNER entities may not be retrieved until after the RETRIEVE button is pressed.

By default the inner zone can only be used to modify existing rows, although navigation buttons can be used to run other tasks to add or remove rows one at a time. However, it is possible to use custom buttons to add or remove rows dynamically using the procedure documented in FAQ156. Note that these additions or deletions will not be actioned until a SUBMIT button is pressed.

The screen contains the following areas:

Multi 6 screenshot

By default the middle entity (child) in this parent-child-grandchild relationship will only display one row at a time, with a scrolling area to move backwards and forwards through the selected rows. However, there is the option to display multiple rows at a time using instructions similar to the following:

    function _cm_initialise ($where, &$selection, $search)
    // perform any initialisation for the current task.
    // NOTE: $selection is passed by reference as it may be amended.
    // NOTE: $search    is only available for OUTPUT tasks.
    {
        $this->skip_getdata                  = true;    // perform all reads in _cm_customButton()
        $this->xsl_params['middle_multiple'] = 'y';     // allow this zone to show multiple rows
        $this->xsl_params['middle_nosort']   = 'y';     // disable all sort hyperlinks
        $this->setRowsPerPage(10);                      // show up to 10 rows at a time

        return $where;

    } // _cm_initialise

Note that with this option you will have to manage the selection criteria for the middle/child and lower/grandchild entities with care.

Output

These functions will allow data to be output in formats other than HTML, such as CSV or PDF.

Output 1 - CSV

This function does not have any visible screen. It will extract data using the selection and sort criteria passed down from the previous screen, convert that data to CSV format (Comma Separated Values) and send it to the client browser where it can either be viewed immediately (usually in a spreadsheet program) or saved to disk.

The first row of the output file will contain the column labels, while all subsequent rows will contain data, one line per record.

Note that by default if no rows are retrieved from the database this program will not produce an output file but will return to the calling program with an error message. If the allow_zero_rows property is set then it will instead create an empty CSV file which contains a row of labels but no data.

Output 2 - PDF (list view)

This function will produce a PDF document which is suitable for printing. The completed PDF document can either be sent to the client or stored on the server. List View will output the data one record per line according to the specifications in the report structure file. More details on how this pattern can be used to produce customised reports may be found in RADICORE for PHP - creating PDF output.

This function is designed to be processed from a navigation button in a parent form. Whatever selection and sort criteria which is currently being used in the parent form will be passed down to this task so that whatever is being shown on the screen will appear in the report, but without the pagination option which restricts the output to a limited number of records. This selection and sort criteria may be overridden within the task, if desired.

Each printed page will contain the following areas:-

Output 2 report sample

Output 3 - PDF (detail view)

This function will produce a PDF document which is suitable for printing. The completed PDF document can either be sent to the client or stored on the server. List View will output the data one record per page according to the specifications in the report structure file. More details on how this pattern can be used to produce customised reports may be found in RADICORE for PHP - creating PDF output.

This function is designed to be processed from a navigation button in a parent form. Whatever selection and sort criteria which is currently being used in the parent form will be passed down to this task so that whatever is being shown on the screen will appear in the report, but without the pagination option which restricts the output to a limited number of records. This selection and sort criteria may be overridden within the task, if desired.

Each printed page will contain the following areas:-

Output 3 report sample

Output 4 - CSV (with column selection)

This function is similar to Output 1 but has a screen which allows the user to select which columns will be written to the output file. It will identify the columns which are available by selecting the first record and examining the result.

The first row of the output file will contain the column labels, while all subsequent rows will contain data, one line per record.

This screen contains the following areas:-

NOTE #1: If there is too much data to be extracted in a single operation the use of LIMIT and OFFSET will allow that data to be extracted in manageable chunks, as in:

NOTE #2: By default the initial value of sort_seq will be the order in which the fields were defined in the SELECT part of the SQL query. These defaults can be altered by inserting the relevant code into the _cm_getColumnNames() method. These values can also be altered before pressing the SUBMIT button to produce the output file.

Output 4 screenshot

Output 5 - PDF (address labels)

This function will produce a PDF document which is suitable for printing. The completed PDF document can either be sent to the client or stored on the server. Each page of the document will contain nothing but lines of address labels, so there will be no heading and no footer. More details on how this pattern can be used to produce customised reports may be found in RADICORE for PHP - creating PDF output.

This function is designed to be processed from a navigation button in a parent form. Whatever selection and sort criteria which is currently being used in the parent form will be passed down to this task so that whatever is being shown on the screen will appear in the report. This selection and sort criteria may be overridden within the task, if desired.

Each printed page will contain the following areas:-

Output 5 report sample

Output 6 - CSV (tree view)

This function does not have any visible screen. It will extract data for the top nodes in a hierarchy using the selection passed down from the previous screen, extract any child nodes down to any level, convert that data to CSV format (Comma Separated Values) and send it to the client browser where it can either be viewed immediately (usually in a spreadsheet program) or saved to disk.

The first row of the output file will contain the column labels, while all subsequent rows will contain data, one line per record.

Picklist

These screens are an alternative to dropdown lists and radio groups.

File Picker

This type of function is normally invoked from a parent function which has a popup button next to (or instead of) the data entry field. When this button is pressed it will activate the popupCall() method before calling the nominated task. After the popup form has been processed the original task will be reactivated, and the popupReturn() method will be used to deal with whatever has been selected.

It is used to display the files that exist in a pre-selected directory in a multi-column layout. Each filename will be shown as a hyperlink, so all the user has to do to make a selection is to click on a filename.

In cases where the files to be selected are images it may be possible to include a thumbnail image in the display.

The name of the directory from which the file will be picked and the valid file types are all specified in the _cm_initialiseFilePicker() method, as shown below:

    function _cm_initialiseFilePicker ($fieldarray)
    // perform any initialisation before displaying the File Picker screen.
    {
        // identify the subdirectory which contains the files
        $this->picker_subdir    = 'pictures';

        // identify the file types that may be picked
        $this->picker_filetypes = array();  // default is ANY file extension
        $this->picker_filetypes = array('bmp', 'jpg', 'png', 'gif');

        // specify the dimensions of the displayed image
        $this->image_height = 60;
        $this->image_width  = 60;
			
        // hyperlinks go direct to files, not redirected to download task
        $this->xsl_params['hyperlink_direct'] = 'y';
			
        // if a file is uploaded it will be returned immediately as if it was selected
        $this->return_uploaded_file = true;

        // identify the directory where cached results will be stored
        $this->cache_dir = 'files/cache';
				
        // list of subdirectories to be included
        // FALSE = none, TRUE = all, array() = list of allowed directories
        $this->picker_include_dir = FALSE;

        return $fieldarray;
        
    } // _cm_initialiseFilePicker

It is within the screen structure file that you define which fields are to be displayed. The following are available:

Note that as the details will be displayed in two column groups, not the usual one, the total width of each column group is 50%, as shown in the following example:

<?php
$structure['xsl_file'] = 'std.filepicker.list1.xsl';

$structure['tables']['main'] = 'file';

// identify the number of column and their widths
// (as columns are displayed in pairs each should be 50% of the total screen width)
//$structure['main']['columns'][] = array('width' => 1);
$structure['main']['columns'][] = array('width' => '40%');
$structure['main']['columns'][] = array('width' => '10%');
//$structure['main']['columns'][] = array('width' => '5%', 'align' => 'right');
//$structure['main']['columns'][] = array('width' => '17%');

// identify the field names and their screen labels
//$structure['main']['fields'][] = array('selectbox' => 'S');
$structure['main']['fields'][] = array('file_name' => 'File Name');
$structure['main']['fields'][] = array('image' => 'Image',
                                       'imagewidth' => 16,
                                       'imageheight' => 16);
//$structure['main']['fields'][] = array('file_size' => 'Size');
//$structure['main']['fields'][] = array('file_date' => 'Date');
?>

Please note that although the screen structure file contains the dimensions for the displayed images, it is also possible for these dimensions to be overridden by values specified in the _cm_initialiseFilePicker() method.

If you require a version to list video files instead of still images then you need to have a separate task with a separate screen structure file with the word 'image' changed to 'video', as in the following example:

$structure['main']['fields'][] = array('video' => 'Video',
                                       'imagewidth' => 180,
                                       'imageheight' => 320);

File Picker screenshot

Please note the following:

• The file names will be displayed without any directory names.
• The files will be displayed in pages of 100, in 2 columns. Pagination options will allow the user to select different pages.
• The title bar will automatically contain a QuickSearch option which will allow the files to be filtered by part of the file name.
• It is possible to have the FileUpload option in the navigation bar which will upload a new file. If this option is used the newly uploaded file will automatically be taken as the selected file and returned to the calling program unless the return_uploaded_file option is set to FALSE.
• If the hyperlink_direct option is set the hyperlinks for each file will go direct to the browser instead of being passed back to the task for processing via the _cm_filePickerSelect() method.
• If the $picker_subdir contains sub-directories these will be displayed according to the value in $this->picker_include_dir which has the following options:
  • FALSE - no subdirectories will be displayed.
  • TRUE - all subdirectories will be displayed.
  • array() - an array of directory names which are allowed to be displayed.

  Any directory name that is displayed will appear as a file name without a size and a date. If selected the contents of that subdirectory will be displayed, and a button called "DIRECTORY UP" will appear in the action bar. Press this button to return to the parent directory.

• If the source directory contains more than 2,000 files the directory listing will be stored in a cache file in order to speed up all subsequent page displays. If you do not supply a directory name in $this->cache_dir then the value from ini_get('session.save_path') will be used instead. This cache is 'per session', so a new file will be created for each session. You can manually rebuild the current cache by pressing the RESET button.

File Upload

This type of function can either be invoked from a menu or navigation button, but can also be invoked from a parent function which has a popup button next to (or instead of) the data entry field. When this button is pressed it will activate the popupCall() method before calling the nominated task. After the popup form has been processed the original task will be reactivated, and the popupReturn() method will be used to deal with whatever has been selected.

This will allow the user to upload a file from his device to the server. Note that a file can be rejected if it is the wrong type or above a maximum size.

The following variables need to be specified in the object's _cm_initialiseFileUpload() method:

• The name of the directory into which the file will be uploaded.
• A list of valid MIME Media Types (or a single type of 'image' to cover all possible image types, or '*' for any file type).
• The maximum file size, in bytes. Any file larger than this will be rejected.

    function _cm_initialiseFileUpload ($fieldarray)
    // perform any initialisation before displaying the File Upload screen.
    {
        $this->upload_subdir      = 'pictures';
			
either: $this->upload_filetypes   = array('image/x-png', 'image/gif');
or:     $this->upload_filetypes   = 'image';
or:     $this->upload_filetypes   = '*';

        $this->upload_maxfilesize = 100000;
        $this->upload_blacklist   = array("\.php.*", "\..*htm.*");				
        $this->allow_multiple     = TRUE;

        return $fieldarray;

    } // _cm_initialiseFileUpload

If $this->allow_multiple is set to TRUE then this will enable the 'SUBMIT+stay' button so that after a file has been uploaded it will stay in the screen so that another file can be uploaded.

It is also possible to get the upload process to automatically create copies of an image file with different dimensions by populating the object's resize_array using code similar to the following:

        $this->resize_array[1]['directory'] = 'thumbs';
        $this->resize_array[1]['width']     = 60;
        $this->resize_array[1]['height']    = 60;

        $this->resize_array[2]['directory'] = 'large';
        $this->resize_array[2]['width']     = 400;
        $this->resize_array[2]['height']    = 400;

This indexed array can contain any number of entries.

The name of the uploaded file can be changed by code in the _cm_fileUpload() method.

After the file has been uploaded it can be processed by code in the _cm_post_fileUpload() method.

This function may be called in place of a filepicker, or from the navigation bar of a filepicker, or from a popup button.

After returning to a task from a fileupload where one or more files were uploaded, a list of uploaded files will be made available in the $return_files argument of the _cm_restart(), _cm_popupReturn() and _cm_post_popup_return() methods. This will be an array containing data in the following format:

    $files[0]['url'] = "\var\www\html\documents\example1.pdf"
    $files[0]['filename_orig'] = 'example.pdf'
    $files[0]['filename'] = 'example'
    $files[0]['extension'] = 'pdf'
    $files[0]['size'] = 23400

File Upload screenshot

File Download

This function does not have any visible screen. This will allow the user to download a file from the web server to his client device. The user selects an entity which contains the name of the file to be downloaded, then activates this transaction by pressing a button on the navigation bar. Alternatively this can be used to process files which are selected in a filepicker screen.

If the task is to be used to download files which have been selected in a filepicker screen then the _cm_initialise() method should contain code similar to the following:

function _cm_initialise ($where, $selection)
// perform any initialisation for the current task.
{
    // do not try to read any data as this table does not exist
    $this->skip_getdata = true;

    // identify the subdirectory which contains the files
    $this->picker_subdir = '../logs';

    return $where;

} // _cm_initialise

Unless the $this->skip_getdata option has been set the name of the file to be downloaded is extracted from the selected database record and placed in the $this->download_filename variable in the _cm_intialiseFileDownload() method as shown below:

    function _cm_initialiseFileDownload ($fieldarray)
    // perform any initialisation for the file download operation.
    {
        // 'picture' field contains name of file to be downloaded
        $this->download_filename = $fieldarray['picture'];
        //$this->download_mode     = 'inline';  // disable option to save

        return;

    } // _cm_initialiseFileDownload

If you place the value 'inline' into $this->download_mode it will display the file in the browser without providing the option to save it to disk.

The updateRecord() method is called in case it is necessary to increment a download count, such as in the following example:

    function _cm_pre_updateRecord ($rowdata)
    // perform custom processing before database record is updated.
    // errors are added to $this->errors.
    {
        // update download details
        $rowdata['report_download'] = getTimeStamp();
        $rowdata['download_count']  = $rowdata['download_count'] +1;

        return $rowdata;

    } // _cm_pre_updateRecord

NOTE: this pattern uses the mime_content_type function which requires the mime_magic.magicfile = "/path/to/magic.mime" directive in your php.ini file.

Popup

This type of function is normally invoked from a parent function which has a popup button next to (or instead of) the data entry field. When this button is pressed it will activate the popupCall() method before calling the nominated task. After the popup form has been processed the original task will be reactivated, and the popupReturn() method will be used to deal with whatever has been selected.

It is used to provide a picklist from the contents of a database table which has too many rows to fit into a dropdown list. It is provided in the form of one of the standard LIST screens or a TREE VIEW screen but with the addition of the following buttons on the action bar:-

• CHOOSE - after selecting at least one row from the current display by checking the associated box in the SELECT column this button will cause the selected rows(s) to be passed back to the previous function for processing. If the SELECT column contains checkboxes then multiple selections can be made, but if it contains radio buttons then only a single selection can be made.
• CHOOSE NULL - This will cause the current selection in the parent screen to be nullified or cleared. This is different from the 'Cancel' button which will terminate the popup process without making a selection, thus leaving any current selection unchanged. This option is not available in popups which allow multiple selections.

Note that when the CHOOSE button is pressed in a POPUP screen it will cause the chooseButton() function to be called.

There are currently 4 types of popup available:

• POPUP 1 - which is LIST 1 with a 'CHOOSE' and 'CHOOSE NULL' button
• POPUP 2 - which is LIST 2 with a 'CHOOSE' and 'CHOOSE NULL' button
• POPUP 3 - which is TREE 1 with a 'CHOOSE' and 'CHOOSE NULL' button
• POPUP 4 - which is TREE 2 with a 'CHOOSE' and 'CHOOSE NULL' button

Popup1 screenshot

If the SELECT column contains checkboxes then it is possible to select more than one occurrence from the current screen. If only a single selection is possible then these checkboxes should be changed to radio buttons. This can be achieved by putting the string select_one=TRUE into the SETTINGS field for the popup task.

Popup2 screenshot

This type of popup has a parent/outer entity and a child/inner entity. Entries can only be selected from the child/inner entity, but these entries cannot be displayed until an occurrence of the parent/outer entity has been selected. The primary key of this occurrence can be suppled in one of the following ways:

• If the identity is known BEFORE the popup is activated then it should be supplied in the _cm_popupCall() method.
• If a value for the parent/outer entity is not supplied when the popup is activated it will by default immediately return with the message "Nothing selected from popup screen". This situation can be trapped in the _cm_initialise() method in order to suspend the current popup while a second popup is activated to provide a value.

These procedures are discussed in the FAQ.

Note that this situation also exists with POPUP 4 as it also deals with two entities.

Search

This type of function is used to enter selection criteria before retrieving data from the database. It is usually called from a LIST function via a button on the navigation bar and will cause that function to perform a new retrieve using the modified selection criteria which is passed back to it. It is possible to force the LIST function to automatically jump to the search screen by using the initial_passthru option in the Update Task screen.

Note that if the LIST function was activated with initial selection criteria passed down as context from the previous screen then the search screen can only add to this criteria. It cannot modify or remove the initial selection criteria which will be shown as non-editable text.

Some tasks may use the QuickSearch Bar to provide a faster method of performing searches.

This function may also be used to enter selection criteria for a BATCH or OUTPUT task, in which case the _cm_post_search() method must be used to identify the new task so that it can be activated. It is not possible to pass the selection criteria back to the previous task if that task is of type BATCH or OUTPUT as this type of task cannot be suspended.

Search 1

Upon initial entry this screen will usually be blank, but it may contain some values which were set in the parent form and which cannot be changed. If any previous values have been set using this screen then they will be shown as well (this will also cause the parent screen to have a PREVIOUS SEARCH button in the navigation bar). The user may enter whatever selection criteria is desired, then press the SUBMIT button to have it passed back to the calling transaction for processing.

By default the 'required' setting for each field will be turned off before the screen is displayed so that all fields are optional, but this can be re-instated in the _cm_changeConfig() method if necessary.

The following wild card characters are allowed anywhere in text fields:

The following qualifying characters are allowed at the beginning of numeric fields:

You may also use the terms 'is null' and 'is not null' in any field.

This screen contains the following areas:-

Search 1 screenshot

Timetable

This type of function is used for timetables or schedules.

Timetable1

This function is used to display all the schedule/timetable (child) entries for a selected parent.

Upon initial entry this function will retrieve the first of the selected occurrences from the ONE (parent) table, then retrieve all the associated rows from the schedule/timetable (child) table and display them on a single page with a separate column for each day. Each scheduled event will appear as a separate box in the relevant column for that day, with the top of the box aligned with the start time (as shown in the column on the far left) and the bottom of the box aligned with the end time.

This screen contains the following areas:-

$this->xsl_params['start_time']  = '09:00';
$this->xsl_params['end_time']    = '16:00';

$this->xsl_params['last_day_no'] = 5; // 5=Friday;

Timetable 1 screenshot

Tree

These types of screens are used to display the nodes in a tree structure where one node can be the parent of other nodes. This is a hierarchical structure which can support any number of levels.

Tree View 1

This screen accesses a simple hierarchical structure where a node can have zero or one parent but any number of children. A node without a parent is known as a root node, and upon initial entry to this screen only root nodes will be displayed. If a node has children then a button will be made available to either show or hide those children.

This screen contains the following areas:-

Tree View 1 screenshot (without extra fields)

The screen structure file used for the above looks like the following:

$structure['xsl_file'] = 'std.tree.list1.xsl';

$structure['tables']['main'] = 'tree_node';

$structure['main']['columns'][] = array('width' => 5);
$structure['main']['columns'][] = array('width' => '*');

$structure['main']['fields'][] = array('selectbox' => 'Select');
$structure['main']['fields'][] = array('node_desc' => 'Node Description', 'nosort' => 'y');

$structure['main']['node_data_names'] = array('id' => 'node_id',
                                              'desc' => 'node_desc',
                                              'depth' => 'node_depth',
                                              'child_count' => 'child_count',
                                              'expanded' => 'expanded',
                                              'icon' => 'icon');

Note that the single node_desc field in the screen is constructed by concatenating all those fields identified in the node_data_names array. This allows you to map the screen names with the column names which are used in the database and which have been copied to the XML file.

Note also that it is possible to add extra columns to the screen following the node description, as shown in the following example:

Tree View 1a screenshot (with extra fields)

The screen structure file used for the above looks like the following:

$structure['xsl_file'] = 'std.tree.list1.xsl';

$structure['tables']['main'] = 'tree_node';

$structure['main']['columns'][] = array('width' => 5);
$structure['main']['columns'][] = array('width' => '*');
$structure['main']['columns'][] = array('width' => 200);  <== EXTRA
$structure['main']['columns'][] = array('width' => 200);  <== EXTRA

$structure['main']['fields'][] = array('selectbox' => 'Select');
$structure['main']['fields'][] = array('node_desc' => 'Node Description', 'nosort' => 'y');
$structure['main']['fields'][] = array('location_type_id' => 'Location Type');  <== EXTRA
$structure['main']['fields'][] = array('asset_type_id' => 'Asset Type');        <== EXTRA

$structure['main']['node_data_names'] = array('id' => 'node_id',
                                              'desc' => 'node_desc',
                                              'depth' => 'node_depth',
                                              'child_count' => 'child_count',
                                              'expanded' => 'expanded',
                                              'icon' => 'icon');

// identify names of additional fields                              <== EXTRA
$structure['main']['node_extra_names'] = array('location_type_id',  <== EXTRA
                                               'asset_type_id');    <== EXTRA

Note that each additional column that you want to appear in the screen requires additional entries such as those marked with <== EXTRA.

Tree View 2

This is similar to TREE 1 but has an outer and an inner entity. The identity of the top/outer/parent entity will be passed down from the previous screen, and the bottom/inner/child entity will show that hierarchy of details, starting with all root nodes, which belong to the top/outer/parent entity.

It shares the same screen areas as the Tree View 1 screen.

Tree View 2 screenshot

Tree View 3

This is similar to a TREE 2, but the outer/top/parent entity is used only to enter selection criteria while the inner/bottom/child entity is used to display those occurrences which satisfy that criteria.

The OUTER entity may be programmed to load initial selection criteria which are passed to the INNER entity for automatic retrieval, after which the criteria can be changed and sent to the INNER entity by pressing the RETRIEVE button. Alternatively data for the INNER entity may not be retrieved until after the RETRIEVE button is pressed.

It shares the same screen areas as the Tree View 1 screen.

Tree View 3 screenshot

Update/Modify

This type of function is used to update existing occurrences on the database.

Update 1

Upon initial entry this function will retrieve one or more records from the database using the primary key(s) passed down by the previous form. It will display the current values for one record at a time and allow the user to change them.

This screen contains the following areas:-

Update 1 screenshot

If it is necessary to prevent everyone except the record's creator from amending the record this can be achieved by putting the string created_user=$logon_user_id into the SETTINGS field for the task.

Update 2

This function does not have any visible screen. It passes control to a POPUP screen where the user can select one or more occurrences, then uses the _cm_updateSelection() method to perform some sort of update. This may typically be to update each of the selected entries with the identity of the parent record. This is the reverse of a DELETE 3 function.

Update 3

This function has a screen similar to Update 1 but instead of having each field coming from the same database row, each field is actually from a different row in the same table. This is a design I have used successfully for many years to deal with what is sometimes referred to as 'control' data. Instead of having a single row with many values I have many rows each containing a single value. This allows me to add or delete values from the 'control' data without having to make any changes to the database structure. For more details please refer to A flexible method of storing control data.

The structure of my 'control' table is as follows:

CREATE TABLE `mnu_control` (
  `record_id` varchar(16) NOT NULL default '',
  `field_id` varchar(32) NOT NULL default '',
  `field_value` varchar(255) default NULL,
  PRIMARY KEY  (`record_id`,`field_id`)
) TYPE=MyISAM;

The class for my 'control' table then defines which values are to be retrieved from the database and how they are to be displayed on the screen. When the SUBMIT button is pressed these are updated using the _cm_updateSelection() method. Note that this method has been modified so that it will handle inserts as well as updates.

Update 3 screenshot

Update 4

This function does not have any visible screen. It will allow one or more database rows to be updated without being displayed. Any selection criteria is passed down from the previous screen. Rows are then retrieved from the database using the getData() method, modified by code within the table class, then written to the database using the updateMultiple() method.

Alternatively the application code may decide not to update the database (by not putting anything in the output array) but to write results out to a non-database file, as in mnu_subsystem(upd4)export.

Note that the updateMultiple() method can also perform inserts and deletes as well as updates.

Update 5

This function does not have any visible screen. It will allow one or more database rows to be inserted or updated without any dialog with the user. These rows must be constructed within the initialise() method so that they can be processed using the insertOrUpdate() method. This will examine each record in turn, and call either insertRecord() or updateRecord() depending on whether the primary key currently exists in the database or not.

Choosing which template to use

Although there are advantages from being able to pick from a large variety of templates, the biggest problem is deciding which template, or combination of templates, to use in a particular set of circumstances. Just because a template is designed around a particular database structure does not mean that wherever you see that database structure you must use that template. There may be more than one option, so you have to be aware of the different options before you make a decision.

List 1, List 2 or List 3?

Take an example where the database has three tables arranged in a parent-child-grandchild relationship, as shown in figure 3:

Figure 3 - Parent-Child-Grandchild relationship

Amongst the patterns there is a LIST 1 which deals with a single table, a LIST 2 which deals with two tables in a parent-child relationship, and a LIST 3 which deals with three tables in a parent-child-grandchild relationship. You may think that this automatically indicates that you should use LIST 1 for the parent, LIST 2 for the child and LIST 3 for the grandchild, as shown in figure 4:

Figure 4 - Possible use of List 1, List 2 and List 3

Although this combination would work, it may not be the best solution.

In the XAMPLE database as used by the Example application (available on the Prototype menu) there are three tables, 'person_type', 'person' and 'person_address' arranged in a parent-child-grandchild relationship. To maintain the 'person_type' table there is a LIST 1 accompanied by ADD 1, ENQUIRE 1 , UPDATE 1, DELETE 1 and SEARCH 1, but to maintain the 'person' table there is a LIST 1 where you might expect a LIST 2. Why is this? The reason is because of the restrictions that a LIST 2 imposes:

• A LIST 2 function cannot be accessed from an option in the menu bar as it requires some sort of context to be passed down from the previous screen. It can only be accessed from an option in the navigation bar, and is then constructed by whatever context is passed down to it.
• This means that it would not be possible to view the contents of the 'person' table without first selecting a value for 'person_type'.
• It would not be possible to exclude 'person_type' from the search criteria, so each screen would only show entries of the same type. A SEARCH screen can only be used to supply additional selection criteria and cannot modify any initial criteria passed down as context by the previous screen.
• This arrangement implies that once you have created a 'person' entry that you cannot change its value of 'person_type'.

The use of a LIST 1 as the primary method to access the 'person' table provides the following advantages:

• A LIST 1 function can be accessed from an option on the menu bar as it does not require any sort of context to be passed down to it. If it is accessed from an option on the navigation bar then it will be restricted by any context which is passed down to it.
• This means that it is possible to access the 'person' table without first selecting a value for 'person_type'.
• Once inside the LIST 1 screen it is possible to change the selection criteria to include or exclude a value for 'person_type' by activating the SEARCH 1 screen.
• When creating a 'person' record the choice of 'person_type' is made from a picklist after entering the 'person' screen, not before.
• When amending a 'person' this method implies that it is possible to change the value for 'person_type' from the picklist. This is made possible by the fact that 'person_type' is not part of the primary key.

Having said that a LIST 1 screen should be the primary method of accessing the 'person' table, there is no reason why you cannot have a LIST 2 screen as an option the navigation bar of the 'person_type' screen as a secondary method of access.

The use of a LIST 2 screen to access the 'person_address' table is justified for the following reasons:

• A 'person_address' always belongs to a particular 'person', so it is perfectly valid to select a 'person' before being able to access any address records for that person.
• When creating a new address it is not logical to activate the 'add address' screen and then choose the person. As you already know the person to whom the address belongs it is perfectly logical to start from a person screen and then say "add a new address to this person".
• Once an address has been created for a person it is not possible to switch that address to another person. This is enforced by the fact that 'address_no' is part of the primary key.

This produces an actual structure shown in figure 5:

Figure 5 - Actual structure of templates used

The use of a LIST 3 screen to access the 'person_address' table is not justified as it would mean starting with the LIST 1 screen in order to choose a 'person_type' before being able to navigate down to the LIST 2 screen to choose a 'person'. This extra step would insist that you know the value of 'person_type' before being able to view 'person', and as this restriction does not exist in real life it should not be enforced by the software.

Having said that a LIST 2 screen should be the primary method of accessing the 'person_address' table, there is no reason why you cannot have a LIST 1 screen as an option on a menu bar as a secondary method of access so that you can perform searches and inquiries without being restricted to a particular person.

Add 1, Add 2, Add 3 or Add 4?

All of these will add records to the database, but with subtle variations.

• ADD 1 is typically called from a navigation button in a LIST 1 screen to add a single record to the database. This does not require any context passed down to it before it can function as all data is input through its screen. Links to foreign tables can be made using picklists (dropdowns or popups). The same picklists are also available in the UPDATE 1 screen, so this implies that whatever values are chosen in the ADD screen can be changed in the UPDATE screen.
• ADD 2 is typically called from a navigation button in a LIST 2 screen to add a single record to the database. It cannot function without context being passed down to it (the primary key of a parent table). Although it would be possible to choose the parent identity from a picklist (after all, it is just another foreign key) as in an ADD 1 screen, this implies that the same picklist would be available in the UPDATE 1 screen making the identity of the parent table an updatable field. Where this value cannot be changed, for example because it is part of the primary key, then an ADD 2 should be used in preference to an ADD 1.
• ADD 3 is typically called from a navigation button in a MULTI 2 screen to add one or more records to the MANY table of a ONE-to-MANY-to-ONE relationship (i.e. where the MANY table has two parents). This function does not have a visible screen. All it does is call a POPUP screen which will allow the user to select one or more occurrences from the second MANY table, then combine this selection with the primary key of the first MANY table to add new occurrences to the link/intersection table (using multiple calls to the insertRecord method).
• ADD 4 is typically called from a navigation button in any type of screen. It has no visible screen of its own as all it does is use whatever context is passed down to it to construct an array of one or more entries which are then added to the database.

Update 1, Update 2, Update 3 or Update 4?

All of these will update records in the database, but with subtle variations.

• UPDATE 1 is typically called from a LIST 1 or LIST 2 screen in order to update one or more selected records. The current details of each selected record are shown one at a time, and the user may make any changes and commit them to the database by pressing the SUBMIT button, cancel all further changes by pressing the CANCEL button, or move on to another selected record by using the scrolling area.
• UPDATE 2 does not have a visible screen of its own. Instead it passes control to a POPUP screen so that the user can select one or more records. It then passes the selection plus the identity of the parent record to the _cm_updateSelection method which will perform the update. This will typically be to update each selected record with the identity of the parent. This is the reverse of a DELETE 3 function.
• UPDATE 3 is used to update values on a control table which, instead of being implemented as a single record with a large numbers of fields, actually exists as a collection of records which hold one value each. This design means that fields can be added or deleted from the control table without amending the structure of the database.
• UPDATE 4 does not have a visible screen of its own. It uses whatever context is passed down from the calling screen to construct an array of one or more database records to be updated, which are then processed by the updateMultiple method. Alternatively the application code may decide to leave the array empty (thus not updating the database) and instead write results out to a non-database file, as in mnu_subsystem(upd4)export.

Delete 1, Delete 2, Delete 3 or Erase 1?

All of these will remove records from the database, but with subtle variations.

• DELETE 1 is typically called from a LIST 1 or LIST 2 screen in order to delete one or more records from the database. The current details of each selected record are shown one at a time, and the user may confirm the deletion by pressing the SUBMIT button, reject the deletion by pressing the CANCEL button, or move on to another selected record by using the scrolling area. If there are any entries on related tables for the current record which are marked as RESTRICTED then the record cannot be deleted. If there are any entries on related tables for the current record which are marked as CASCADE then these will be deleted when the current record is deleted.
• DELETE 2 is typically called from a MULTI 2 screen in order to delete one or more records from the database. Note that this function does not have any user dialog. It simply deletes each selected record and returns control back to the calling screen.
• DELETE 3 is similar to DELETE 2 in that it can deal with multiple records without any user dialog, but the difference is that instead of receiving an array of primary keys it receives selection criteria which may include any number of records on a particular database table. The actual action performed on these records is not hard-coded, it is specified in the _cm_deleteSelection() method. It may actually delete the selected records, or it may update them by nullifying a foreign key.
• ERASE 1 should only be used in special circumstances as it ignores any RESTRICTED constraints on child relationships and removes an entire hierarchy of records from the database. This type of function would normally be accompanied by some sort of 'export' function which would provide a backup of that hierarchy of records so that it can be reinstated if necessary.

Link 1, List 2 or Multi 2?

Take the example where there are three database tables which are related in a ONE-to-MANY-to-ONE relationship, in other words a 'child' with two 'parents', as shown in figure 6:

Figure 6 - A ONE-to-MANY-to-ONE relationship

For the maintenance screens it is necessary to start with one of the parents and list its children, and perhaps showing some data retrieved from the other parent table. In this situation there are various combinations of templates which are available, and, depending on the particular circumstances, one may be more beneficial than the others.

• LINK 1 is typically used where the MANY entity is actually the intersection (or 'link') entity in what is sometimes known as a many-to-many relationship. In this situation the 'link' table does not contain any data other than foreign keys to each of the two parents. These two foreign keys are combined to form a primary key so that any combination of parent 1 and parent 2 can have no more than one record on the 'link' table. The top of the screen will contain a single occurrence of one of the parents while the body will show all occurrences of the other parent. Against each of these occurrences will be a checkbox which will be ON if a 'link' record exists, and OFF if a 'link' record does not exist. Creating and deleting 'link' records is as easy as toggling the checkbox. Note the following regarding options on the navigation bar:
  • There is no ADD/INSERT/NEW option as new records will be created by setting a checkbox ON.
  • There is no DELETE option as existing records will be deleted by setting a checkbox OFF.
  • There is no ENQUIRE option as there is no other data to view.
  • The SEARCH option may be used to restrict the display to only those occurrences where the checkbox is ON, where the checkbox is OFF, or any other selection criteria.
• LIST 2 is typically used where the MANY entity contains more than the foreign keys to the other two entities, and where the existence/non-existence of a record on the MANY table requires more than the toggling of a checkbox. It can be considered as a ONE-to-MANY relationship where the MANY just happens to have a foreign key to another table, as shown in figure 7:

  Figure 7 - A ONE-to-MANY-to-FOREIGN relationship

  

  In this situation the LIST 2 screen would cover the ORDER and ORDER_ITEM tables, while the PRODUCT table would be the subject of a POPUP from within the ORDER_ITEM(add) and ORDER_ITEM(update) screens.

  If it were ever needed to access the ORDER_ITEM table via a PRODUCT, then this combination would be the subject of a separate LIST 2 screen.

• MULTI 2 is typically used where the amount of data which can be updated on the MANY entity is so small that it can fit on a single line within a multi-occurrence screen instead of requiring a separate detail screen for each individual occurrence. Because there is no separate detail screen all additions and deletions are handled as follows:
  • Additions are handled via an ADD 3 screen which does not have a visible screen of its own. Its purpose is to pass control to a POPUP screen which allows the user to choose one or more entries from the 2nd parent table, and once these entries have been chosen to insert the relevant entries into the child table, then return control to the MULTI 2 where the newly-inserted records will be made available for modification.
  • Deletions are handled via an DELETE 2 screen which again does no have a visible screen of its own. It will simply take the list of primary keys passed down to it and delete those records from the database without requiring any further confirmation.

There are working examples of all of these within the RBAC application:

• The maintenance of the ROLE-TASK table is handled with a pair of LINK 1 screens, one which will link a Role to a selected Task, and another which will link a Task to a selected Role.
• The maintenance of the NAVIGATION_BUTTON table is best handled by a MULTI 2 screen, but a LINK 1 screen and a LIST 2 screen are also provided so that you can see the difference.

Multi 1, Multi 3 or Multi 4?

These will allow several database records to be updated at a time, but with minor variations.

• MULTI 1 is similar to UPDATE 1 in that it shows one record at a time, but it may also allow new database records to be created. The collection of records to be shown is constructed via the setScrollArray() method, and as the SUBMIT button is pressed each record will be processed by the insertRecord() or updateRecord() method as appropriate.
• MULTI 3 is similar to a LIST 3 but will allow the most junior database entries to be modified.
• MULTI 4 is similar to a MULTI 2 but will allow both the parent and child entities to be updated.

Amendment History