Main Index  PREV  NEXT

Auxiliary Forms

Overview

An auxiliary form does not obtain its data from the database. The data is passed to it as a parameter from the parent form. This is usually because there is too much data for the parent form to handle within its own screen.

If the form allows changes then the changed data is returned to the parent form. It is up to the parent form to accept these updates and to store them on the database.

A mixture of normal and auxiliary forms can be constructed as shown in Figure 1.

Figure 1 - A parent form with Auxiliary forms

This arrangement has the following characteristics:

• The transaction begins and ends within the parent form.
• All database access (reading and updating) is performed within the parent form.
• All data is held within the parent form, with subsets being passed to each child auxiliary form when required. This data is passed as a parameter on an operation (by default the EXEC operation).
• If the auxiliary form allows data to be changed it is passed back to the parent as an argument on an operation (usually the UPDATE operation).
• Each auxiliary form can only be activated by some postive action in the parent (e.g. pressing a button) so that it can be revisited as many times as the user requires.
• Each auxiliary form is modal, so that once activated the user cannot change focus to another form until the auxiliary form has been terminated.
• There is no means of navigating directly from one child auxiliary to another - the user must always exit from the current auxiliary form and return to the parent before selecting a different auxiliary.

Auxiliary 1 - read access only

Description

For an overview of all Auxiliary forms please go here.

This type of form will display the data passed to it from the parent form. This will usually be in the form of a single string (associative list) in the <exec> trigger. No updates are allowed in this form, so there is no data to pass back to the parent.

The ENTITY_LOAD proc is used to transfer data from the input string to the form. This can handle more than one entity and more than one occurrence of each entity.

Buttons

Contents

Bound Objects

Local Constants (Refer to Local Constants)

Component Variables (Refer to Component Variables)

Auxiliary 2 - read/write access

Description

For an overview of all Auxiliary forms please go here.

This type of form will display the data passed to it from the parent form. This will usually be in the form of a single string (associative list) in the <exec> trigger. Updates are allowed in this form, so when the OK button is pressed it is passed back to the parent.

The ENTITY_LOAD proc is used to transfer data from the input string to the form. This can handle more than one entity and more than one occurrence of each entity.

The ENTITY_UNLOAD proc is used to transfer data from the form to the output string which is passed back to the parent. This can handle more than one entity and more than one occurrence of each entity.

If there is the possibility that a foreign key value may be pre-selected in the calling form and therefore may not be changed by the user at runtime then refer to Note #1 below.

Buttons

Contents

Bound Objects

Local Constants (Refer to Local Constants)

Component Variables (Refer to Component Variables)

Note # 1 - Pre-selected Foreign Keys

If there is the possibility that a foreign key value may be pre-selected in the calling form and therefore may not be changed by the user at run time in this form then follow these steps:

1. Create a component variable for each foreign key. This will be populated with any value passed down by the calling form with the getlistitems/id/local $params$ statement in the <exec> trigger.
2. In the <occurrence gets focus> trigger of the main entity insert the following code (after call to LOAD_INIT_VALUES if it exists):

   Call LP_SELECT
   

3. Create the local proc LP_SELECT with code similar to the following:

   entry LP_SELECT		; look for pre-selected value from parent form
   
   ; was PERSON_ID passed from parent form?
   getitem/id $person_id$, $params$, "person_id"
   if ($person_id$ != "") & (!$dbocc(person))
      person_id.person = $person_id$   ; set the foreign key value
      retrieve/e "person"              ; retrieve the foreign entity
      field_syntax POPUP_BUTTON.PERSON, "NDI,NED,NPR"  ; hide popup button
      field_syntax PERSON_NAME.PERSON, "NED,NPR"       ; make field 'noedit'
      $properties(PERSON_NAME) = "font=fnoeditbox"     ; change font
   endif
   
   ; was COURSE_ID passed from parent form?
   getitem/id $course_id$, $params$, "course_id"
   if ($course_id$ != "") & (!$dbocc(training_course))
      course_id. training_course = $course_id$
      retrieve/e "training_course"
      field_syntax POPUP_BUTTON.TRAINING_COURSE, "NDI,NED,NPR"
      field_syntax COURSE_NAME.TRAINING_COURSE, "NED,NPR"
      $properties(COURSE_NAME) = "font=fnoeditbox"
   endif
   
   return(0)
   
   end LP_SELECT
   

4. Prevent the popup form from being activated for a foreign key field by disabling the <detail> trigger of that field with code similar to the following:

   if ($person_id$ != "") return(0)   ; not allowed to change
   
   call POPUP_DTL(".....")
   .....
   

http://www.tonymarston.net