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 July 2008

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

- Navigation Bar

- Column Headings

- Data Area

- Message Area

- Pagination Area

- Scrolling Area

- Action Bar

- Version Number

- Internationalisation (I18N)

Add/Create/Insert

- Add 1

- Add 2

- Add 3

- Add 4

- Add 5

Delete

- Delete 1

- Delete 2

- Delete 3

- Delete 4

- Erase 1

Enquire/Read/Display

- Enquire 1

List/Browse

- List 1

- List 2

- List 3

Multi-Purpose

- Link 1

- Multi 1

- Multi 2

- Multi 3

- Multi 4

Output

- Output 1 - CSV

- Output 2 - PDF (list view)

- Output 3 - PDF (detail view)

- Output 4 - CSV (with column selection)

Picklist

- File Picker

- File Upload

- File Download

- Popup

Search

- Search 1

Timetable

- Timetable1

Tree

- Tree View 1

- Tree View 2

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?

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 known as Transaction Pattern (Controller) scripts which deal only with structure and behaviour. These can be shared by any number of Component scripts which specify nothing but the content. The purpose of this document is to describe the various templates/patterns which currently exist in my software library.

As of 18th October 2006 the creation of application transactions has been automated. It is now possible to select a database table, select a transaction pattern then, at the touch of a button, have the framework generate the transaction for you - all without writing a single line of code. This is documented in Radicore Tutorial - Generate Transactions.

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.

Figure 1 - A typical Family of Forms

In this structure the LIST (parent) component is the only one that is available on a menu bar - all the other child components can only be selected from the navigation bar within a suitable parent component. In most cases 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.

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

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.

Menu Bar

This is 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:

• 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. An item will be a hyperlink if it is different from the current page.

Navigation Bar

This is a group of buttons which will allow control to be passed to functions which are in some way related to the current function. It can be thought of a a sort of 'mini menu', and is situated at the top of the screen under the menu bar.

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 modify column labels at runtime? How can I hide/remove columns in a multi-row display? 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?

Message Area

Messages related to a particular field will usually appear immediately below the field's data. 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.

Pagination area

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.

Scrolling area

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

Action Bar

This is a group of buttons which perform some action within the current screen, such as updating the database, terminating the screen, or resetting the selection criteria. This is situated at the bottom of the screen.

Action Bar

The SUBMIT button 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.

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 this 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.

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. 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

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.

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 which the user can fill in before pressing the submit button.

This screen contains the following areas:-

Add 5 screenshot

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 $relationship 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 $relationship 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 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 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 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 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 table. It will then retrieve associated occurrences from the GRANDCHILD table and display them starting from page 1.

This screen contains the following areas:-

List 3 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:

• CLEAR - clear the current selection and show a blank screen ready for fresh input.
• RETRIEVE - retrieve a new selection of records using whatever selection criteria is available in the current screen.
• 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. Rows may only be added or deleted by using the relevant buttons in the navigation bar.

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. Rows may only be added or deleted by using the relevant buttons in the navigation bar.

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.

Multi 4 screenshot

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.

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:-

Output 4 screenshot

The last line will accept values for LIMIT and OFFSET where:

• LIMIT is the maximum number of rows (records) to be extracted (default is 1000).
• OFFSET is the row number from which the extract will start (default is 0).

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:

Picklist

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

File Picker

This will display the file contents of a pre-selected directory in a multi-column display. 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 ()
    // 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('bmp', 'jpg', 'png', 'gif');

        // specify the dimensions of the displayed image
        $this->image_height = 60;
        $this->image_width  = 60;  

        return;
        
    } // _cm_initialiseFilePicker

It is within the screen structure file that you define whether to display just the filename or a filename with an image. 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';

$structure['main']['columns'][] = array('width' => '40%');
$structure['main']['columns'][] = array('width' => '10%');

$structure['main']['fields'][] = array('file' => 'File Name');
$structure['main']['fields'][] = array('image' => 'Image',
                                       'imagewidth' => 16,
                                       'imageheight' => 16);
?>

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.

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.
• It is also possible to have a SEARCH option on the navigation bar which returns selection criteria for a field called filename. This will be used to filter the file names before they are displayed.

File Upload

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).
• The maxmum 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';
        $this->upload_maxfilesize = 100000;

        return $fieldarray;

    } // _cm_initialiseFileUpload

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.

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

File Upload screenshot

File Download

This function does not have any visible screen. This will allow the user to download a file from the server to his 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.

The name of the file to be downloaded is extracted from the selected database record and placed in the $this->download_filebname 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 exampe:

    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.

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.

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 folowing 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_intialise() 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 and will cause that function to perform a new retrieve using the modified selection criteria which is passed back to it. 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.

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.

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