Choosing which Component Template to use

Deciding which template to use for each component depends on the specific requirements of the application. Some solutions may be provided with a single component, others may require a mixture of two or more components. The following sections provide examples of how particular templates can be utilised within an application.

A single Multi-Purpose function

This multi-purpose form component shown in Figure 1 performs Create, Read, Update and Delete operations on an entity. Anyone who has been granted access to this form can therefore perform all these operations. It is not possible to restrict individual operations to individual users or classes of user.

Figure 1 - A Multi-Purpose Function

This option is usual under the following circumstances:

Where the entity contains only a small number of fields (i.e. can fit on a single row across the screen).
Once created the data is unlikely to require regular updating.
Create, Update and Delete access is restricted to a small number of privileged users.
All other users will require only Read access.

When it is required to allow an ordinary user to view the contents of the entity so that a specific occurrence can be chosen this can be provided in one of the following ways:

Create a popup form (which is read-only) which can be called from any form.
Create a hidden form which loads the contents of the entity into a global variable so that they can be copied into form widgets (e.g.: dropdown lists, radio groups) at runtime. This hidden form is normally activated from the application's INIT proc.

A group of Single-Purpose functions

Each of the form components shown in Figure 2 performs a single function. Giving a user access to a function is therefore as simple as granting access to the component which performs that function.

Figure 2 - A group of Single-Purpose Functions

This combination has the following set of characteristics:

The List form may or may not perform an automatic <retrieve> upon initial entry, based upon a setting in the Extra Parameters field (e.g. $auto_retrieve$=Y/N).
By default no parameters are passed to the List form, therefore an automatic <retrieve> would potentially encompass all available occurrences.
A small Profile Area at the top of the List form can be used to enter selection criteria before performing a <retrieve>.
It is possible to use the Extra Parameters option for the List form to define default values for fields in the Profile Area.
The use of the Select form to define search criteria instead of the Profile Area is entirely optional.
Access to the Select, Add, Modify, Enquire and Delete forms can only be achieved through the List form.
Access to each child form can be turned on or off within the Menu system and is dealt with at runtime in the List form. Refer to Menu and Security System, Appendix J - Transaction Access Profiles for more details Options which are inaccessible will have their navigation buttons dimmed.
An occurrence must be selected in the List form before control can passed to the Enquire, Modify or Delete form.
Each of the child forms Add, Update, Enquire and Delete will only operate on a single occurrence.
If the database is modified by a child form a message will be sent to the parent List form so that it may update its display accordingly.

Options available with LIST forms

'List' to 'Select'

In the combination shown in Figure 3 the parent form is a List form (with limited selection criteria in the Profile Area), and the use of the Select form, which allows any field to be profiled, is entirely optional.

Figure 3 - 'List' to 'Select'

The identity of the Select form is defined in the Extra Parameters area for the List form on the Menu database.

'Select' to 'List'

In the combination shown in Figure 4 the parent form is a Select form, and this must be negotiated before the List form can be processed. The List form does not contain a Profile Area, and performs an automatic <retrieve> based on the profile that is passed to it by its parent form.

Figure 4 - 'Select' to 'List'

The identity of the child form is defined in the Extra Parameters area for the Select form on the Menu database.

Various 'Selects' to 'List'

In the combination shown in Figure 5 the profile used by 'List MANY', which contains entities 'A' and 'B' as foreign entities, can come from a number of different sources.

Figure 5 - Various 'Selects' to 'List'

'List A' will list occurrences of object A, and will pass a primary key of object A as the profile.
'List B' will list occurrences of object B, and will pass a primary key of object B as the profile.
'Select' will allow any profile to be defined.
'List MANY' will use whatever profile is passed to it.

Options available in One-to-Many relationships

In this situation the 'One' entity can also be referred to as the 'up' entity, and the 'Many' entity can also be referred to as the 'down' entity. The primary key of the 'One' entity also exists as a foreign key on the 'Many' entity.

In this type of relationship several options are available when creating an occurrence of 'Many'. These options mainly revolve around the choice of the outer entity in the component structure, as any parameters which are passed from the parent form normally apply only to the outer entity.

A Single Foreign Entity

This is where there is a simple ONE-to-MANY structure as shown in Figure 6.

Figure 6 - A single Foreign Entity

In this structure ONE is the 'up' or 'foreign' entity while MANY is the 'down' entity. When included within a component these two entities may be arranged as shown in either Figure 7 or Figure 8.

Figure 7
Structure for ADD 1 Component

The ADD 1 template has the following characteristics:

The outer entity in this structure is the 'MANY' entity.
Values for foreign keys are not expected to be passed down from the parent form.
If any foreign key values are passed down the standard code will not preload them, nor will it automatically retrieve the specified occurrence of the foreign entities.
The user can select or change values for foreign keys while in this form (e.g.: via a dropdown list or a popup form).

Figure 8
Structure for ADD 2 Component

The ADD 2 template has the following characteristics:

The outer entity in this structure is the 'ONE' entity.
The primary key of the outer entity is expected to be passed down from the parent form.
The specified occurrence of the outer entity will be automatically retrieved.
The user will not be allowed to change the occurrence of the outer entity.

Multiple Foreign Entities

This is where two 'up' entities are connected to the same 'down' entity, as shown in Figure 9.

Figure 9 - Multiple Foreign Entities

In this example the database structure could lead to the generation of three different components to create new occurrences of the MANY entity, as shown in Figures 10, 11 and 12.

Figure 10 Structure for ADD 1 Component	The ADD 1 template has the following characteristics: The outer entity in this structure is the 'MANY' entity. Values for foreign keys are not expected to be passed down from the parent form. If any foreign key values are passed down the standard code will not preload them, nor will it automatically retrieve the specified occurrence of the foreign entities. The user can select or change values for the foreign keys to the inner (up) entities while in this form (e.g.: via a dropdown list or a popup form).
Figure 11 Structure for ADD 2 Component (a)	The ADD 2 template has the following characteristics: The outer entity in this structure is one of the 'ONE' entities. The primary key of the outer entity is expected to be passed down from the parent form. The specified occurrence of the outer entity will be automatically retrieved. The user will not be allowed to change the occurrence of the outer entity. The user can select or change values for the foreign keys to the inner (up) entities while in this form (e.g.: via a dropdown list or a popup form).
Figure 12 Structure for ADD 2 Component (b)	This is the same as the previous ADD 2 component, but the positions of entities ONE(a) and ONE(b) have been reversed. In this case the parameter which is passed in should include the primary key for the ONE(b) entity instead of the ONE(a) entity.

Note here that two different components are constructed from the ADD 2 template as there are two possible choices for the outer entity. Along with the ADD 1 component this will result in a mixture of parent/child forms as shown in Figure 13.

Figure 13 - 3 Components to add an occurrence of MANY

A Child form being shared by Different Parents

If a component were constructed from the ADD 1 template and modified to expect any one of the foreign key values to be included in the passed parameters it would reduce the number of components, as shown in Figure 14.

Figure 14 - Access to a shared version of ADD 1

It is even possible to extend this ability to share components across several layers in the hierarchy, as shown in Figure 15.

Figure 15 - Access to several shared components

The LIST(Many) form would accept the following as pased parameters:

If parent = LIST(a) then the parameter would be a value for foreign entity (a).
If parent = LIST(b) then the parameter would be a value for foreign entity (b).
If parent = SELECT(Many) then the parameter would be any value for entity (many).

The action taken by ADD 1 would depend on the parameters passed down by its parent:

If parent = LIST(a) then inner entity (a) would be preselected and unchangeable.
If parent = LIST(b) then inner entity (b) would be preselected and unchangeable.
If parent = LIST(Many) then nothing would be preselected and everything would be changeable.

http://www.tonymarston.net