Dynamic Forms feature

Provides the capability to control the visibility of forms, tabs, and fields, and change focus to a specific form and tab when working with a record.

The feature can also be enabled or disabled for specific databases, or entire database sets, via the setting of the master property ALLOW_DYNAMIC_FORMS. See the installutil setmasterproperty topic for the details about how to set up the master property.

Note:

The feature is managed by a Web server site configuration setting, the Allow Dynamic Forms Groups, which specifies which groups can use the feature. The feature is available if you are a member of one of those groups. To get permission, you can ask an administrator for the privilege or see the Applications Options Page topic to set it up.

This feature allows the administrator to provide the hook codes that can complete specific actions. For example, changing a Project field’s value can display a tab with additional fields specific to that project, or selecting a different value in a Type field that can display a specific form for that type. It can also present a series of panels to users to guide them through a specific task, such as resolving a defect record after completing the verification steps.

HCL Compass APIs for controlling field, tab, and form visibility

General
  • The APIs are available in Perl only, on the CQEntity object.
  • In most cases, these APIs will throw an exception if the core knows that the client does not support the dynamic forms feature which is supported only by HCL Compass Web. The result from GetViewFormName or GetViewTabName will be empty if the client does not support the feature.
  • For all APIs taking a fieldName, an exception is thrown if the named field does not exist.
  • For all APIs taking a formName or tabName, an exception is thrown if the name is not empty and the named form or tab does not exist.
  • For any API that starts with Set* and Get* APIs and taking a formName parameter, an empty value means the current form.
  • For Set* APIs taking a formName parameter, a special value of @all means that the change applies to all forms.
    Note:

    The purpose of using @all for the formName parameter is to allow the hook code to configure multiple forms in one place so that the forms are ready to be used. An expected use case is to hide a field based on the value of another field, and that would need to be done on all forms that are available to the user, not just the one that is currently selected.

    Using @all in Perl string generally requires an escape: \@all.

    The form names cannot include most punctuation characters. Dash and underscore are allowed. The tab names can contain any punctuation character.

  • A form can contain multiple tabs with the same name. Any API taking a tabName parameter can identify the tab by its index with the following syntax: <name>[<tab><index>], where <tab> is a single tab character and <index> is the numeric index of the tab, starting with zero. The <name> part may be empty to use only the index; in that case the string value must start with the tab character. If both <name> and <index> are provided, an exception is thrown if the name does not match the tab at the given index. For example, “Notes\t3�? would identify the fourth tab named “Notes�?.

View versus Set for form and tab

  • The View form and tab in the user interface (UI) are used to show the record.
  • The Set form and tab are what has been set by calling the SetFormAndTab API.
  • The user can change forms and tabs, which causes the View values to change, but not the Set values.
  • Hook code can use SetViewFormAndTab to change what the UI is using to show the record.
  • Only the Set values are stored in the record if it is enabled to store the values and SaveVisibilitySettings is called. Those values are used to initialize the View values the next time the record is opened.
  • The primary purpose of the Set form and tab is to specify what will be used the next time the record is opened in a UI that supports dynamic forms. Hooks are not involved when a record is opened and therefore cannot set the View form and tab at that time. The Set values provide the ability to accomplish the same thing. Essentially, the stored Set values become the initial View values when the record is opened.
    Note:

    The Set form and tab will apply for any user that views the record. Those settings should be based on the record content such as State, but not on user or group attributes.

    Use only SetFormAndTab to set the form and tab for the next time the record is opened, but not change what the user is currently using.

    Use both APIs to make the change have an immediate effect in the UI and are persistent, so they are used the next time the record is opened.

    Use only SetViewFormAndTab to change what the current user will see, with the intent that the change is only for the current user and only in the current session.

Enablement

To save the visibility settings of the record, the record type must be enabled.

If a record's type is not enabled to save the settings, any visibility settings will be in effect only while the record is open.

The record's visibility is done with the packageutil setforminfo command. Make sure the schema is not open in the designer when this command is run.
C:\> packageutil setforminfo
 packageutil setforminfo adds the form info field to one or more record types.
 Usage: packageutil setforminfo
          [-help] [-dbset dbset_name]
          compass_login
          compass_password
          schema_name
          (-enable | -disable)
          record_type ...
          [-checkin | -nocheckin]
For example, to enable ALMRequest and ALMTask in the ALM schema, you can use:
packageutil setforminfo -dbset ALM admin "" ALM -enable ALMRequest ALMTask -nocheckin
To see what record types are enabled, use the showforminfo command:
C:\> packageutil showforminfo
 packageutil showforminfo shows which record types have the form info field.
 Usage: packageutil showforminfo
          [-help] [-dbset dbset_name]
         compass_login
         compass_password
          schema_name
For example:
packageutil showforminfo -dbset ALM admin "" ALM

APIs

CQEntity::SetFieldVisibility and CQEntity::GetFieldVisibility

void CQEntity::SetFieldVisibility(const CQString& formName, const CQString& fieldName, const BOOL visible);
BOOL CQEntity::GetFieldVisibility(const CQString& formName, const CQString& fieldName);
  • Set or get the visibility of a field on the specified form.
  • The field visibility setting is independent of form or tab visibility.
  • An exception is thrown if the field is not present on the form.
  • When formName is empty, the operation applies to the current form. The current form is the view form if available, otherwise, the set form. If neither form is available, an exception is thrown.
  • For SetFieldVisibility, formName may be "@all" to apply to all forms. The change will only apply to the forms that actually have the named field. An exception is thrown only if the named field is invalid or does not exist on at least one form.
  • A true result indicates the tab is visible; false means it is hidden.
  • This visibility setting applies to the field anywhere on the form, on any tab, using any control. If the field is associated with multiple controls, hiding the field will hide all those controls.
Note: It is not possible to hide controls that are not directly associated with a field, such as buttons, group boxes, or static text (use tab hiding instead).

CQStringArray CQEntity::GetHiddenFieldNames(const CQString& formName);

  • Returns the names of all fields that are currently hidden on the specified form. If formName is empty, the result will be for the current form. The special form name "@all" is not accepted. The order of the result is not defined.

CQStringArray CQEntity::GetVisibleFieldNames(const CQString& formName)

Returns the names of all fields that are currently visible on the designated form. If formName is empty, the result will be for the current form. The special form name "@all" is not accepted. The order of the result is not defined.

Note: Without this API it is not possible for hook code to determine if a field is actually visible somewhere on a form.

CQStringArray CQEntity::GetFormFieldNames(const CQString& formName);

  • Returns the names of all fields on the designated form.
  • If formName is empty, the current form is used.
  • The special form name "@all" is not accepted.
  • The order of the result is not defined.

CQString CQEntity::GetViewFormName(); CQString CQEntity::GetViewTabName(); and CQEntity::GetViewFormIsLocked();

CQString CQEntity::GetViewFormName();
CQString CQEntity::GetViewTabName();
BOOL     CQEntity::GetViewFormIsLocked();
  • Returns the name of the current form or tab being used to display the record.
  • The result of the GetView*Name APIs will be empty if the record is not being viewed by a UI client that supports the form selection or dynamic forms features.
  • The result of GetViewFormIsLocked is true if the form is locked (the user cannot change to another form).

CQEntity::SetViewFormAndTab

void CQEntity::SetViewFormAndTab(const CQString& formName, const CQString& tabName, const BOOL lockForm);
  • Set the view form and tab, and optionally lock the form.
  • An exception is thrown if the record is not being viewed by a client that supports the dynamic forms feature.
  • The given settings affect what form and tab is currently used to view the record, but will not be saved with the record. Calling this API has the same effect as if the user changed focus to the named form and tab.
  • If formName is empty, the current form is used.
  • If tabName is empty, the first tab will be used; otherwise, an exception is thrown if the named tab does not exist on the form.
  • When lockForm is true, the user is not allowed to select a different form. The Forms menu will be disabled and its hover text will indicate the form cannot be changed. Only the current form can be locked. If the form is changed in another call, the lock on the current form is automatically removed.
  • If the named form is hidden, the UI will use the default form. If that form is hidden, the UI will choose from the visible forms. If no form is visible, a message will be shown in place of the form, saying no forms are available for the record type.
  • If the named tab is hidden, the UI will change focus to the first tab. If there are no visible tabs, a message will be shown saying there are no visible tabs on the form.

CQEntity::SetFormAndTab

void CQEntity::SetFormAndTab(const CQString& formName, const CQString& tabName, const BOOL lockForm);
IMPORTANT: The primary purpose of this API is to change how the record will appear the next time it is opened in a UI that supports dynamic forms. It does not affect how the record is currently being viewed. To change what is being viewed, use SetViewFormAndTab.
  • Set the form and tab, and optionally lock the form.
  • The given settings will be saved with the record if SaveVisibilitySettings is called.
  • The next time the record is opened, the saved settings will become the view form, tab, and lock. In other words, the effect is as if SetViewFormAndTab was set with the saved values when the record is opened (before any hooks are fired).
  • Either formName or tabName, or both, can be empty. If both are empty, the UI will use the default form and tab the next time the record is opened.
  • If formName is empty and tabName is non-empty, the current view form is used to validate the tab, but the set form name will remain empty. If there is no view form, an exception is thrown. This combination is used to specify the record open on a particular tab that is expected to exist on all forms. If a form does not have that tab, the record will be opened with focus on the first tab.
  • If formName is empty, lockForm cannot be true.
  • If the form selection feature is not enabled, locking a form is allowed but will have no effect. The lock setting will be saved, and may have an effect in the future if that feature is enabled.
  • When lockForm is true, the user is not allowed to select a different form. This setting takes effect the next time the record is opened. To lock the form currently being viewed, use SetViewFormAndTab.

CQString CQEntity::GetFormName(); CQString CQEntity::GetTabName(); and CQEntity::GetFormIsLocked();

CQString CQEntity::GetFormName();
CQString CQEntity::GetTabName();
BOOL CQEntity::GetFormIsLocked();
  • Returns the name of the current set form or tab, and the lock status of the set form.
  • The string results will be empty if the SetFormAndTab API has not been called on the record with non-empty names for the item.
  • The results of these Get* APIs differ from their GetView* counterparts in the following way. The results of GetView*Name indicate what the UI client is presenting to the user. The results of these APIs indicate what has been set on the record, and possibly saved with the record. After a SetFormAndTab has been called, the user is allowed to change the form (unless locked) and tab. When the result of GetView*Name does not match the result of the corresponding Get*Name, the API client will know the user has changed the form or tab.

CQEntity::SetTabVisibility and CQEntity::GetTabVisibility

Set or get the visibility of a tab on a specified form. If the formName is empty, the current form is used. For SetTabVisibility, formName may be "@all" to apply to all forms. A true result indicates the tab is visible; false means it is hidden.

void CQEntity::SetTabVisibility(const CQString& formName, const CQString& tabName, const BOOL visible);
BOOL CQEntity::GetTabVisibility(const CQString& formName, const CQString& tabName);
  • Set or get the visibility of a tab on a specified form.
  • The tab visibility setting is independent of form visibility.
  • If the formName is empty, the current form is used.
  • For SetTabVisibility, formName may be "@all" to apply to all forms. The change will only apply to the forms that actually have the named tab. An exception is thrown only if the named tab is invalid or does not exist on at least one form.
  • A true result from Get* indicates the tab is visible; false means it is hidden.
  • Hiding a tab does not change the result returned from GetFormTabNames or the tab order.
  • If the specified tab currently has focus and is set to be not visible, focus will change to the first tab on the form.
  • If there are no visible tabs, the form will be completely blank.

CQStringArray CQEntity::GetHiddenTabNames(const CQString& formName);

  • Returns the names of all tabs that are hidden on the named form.
  • If the formName is empty, the current form is used.
  • The order of the result is not defined.
  • The result includes only those tabs that are accessible to the user but have been hidden with a prior call to SetTabVisibility. In particular, the result will not include tabs not accessible to the user based on group access.

CQStringArray CQEntity::GetVisibleTabNames(const CQString& formName);

  • Get the names of all tabs that are visible on the named form.
  • If the formName is empty, the current form is used.
  • The order of the result is not defined.

CQStringArray CQEntity::GetFormTabNames(const CQString& formName);

  • Return the names of all tabs for a specific form.
  • If the formName is empty, the current form is used.
  • The special form name "@all" is not accepted.
  • The result will be in tab order.
  • The tab names will not include an ampersand ('&').
  • The result includes only the tabs potentially visible to the user. Specifically, it excludes tabs that are hidden due to group access control. Of the potentially visible tabs, the result includes a tab even if it is currently not visible (due to a prior call to SetTabVisibility).

CQEntity::SetFormVisibility and CQEntity::GetFormVisibility

void CQEntity::SetFormVisibility(const CQString& formName, const BOOL visible);
BOOL CQEntity::GetFormVisibility(const CQString& formName);
  • Set or get the visibility of a form for the current record.
  • A valid formName must be provided.
  • A true result indicates the form is visible; false means it is hidden.
  • A hidden form is not listed in the Forms menu.
  • If the current form is hidden, the UI will choose the default form. If that form is hidden, the UI will choose from the visible forms.
  • If all forms are hidden, a message will be shown in place of the form, saying no forms are available for the record type.

CQStringArray CQEntity::GetHiddenFormNames();

  • Returns the names of all hidden forms.
  • The order of the result is not defined.

CQStringArray CQEntity::GetVisibleFormNames();

  • Returns the names of forms that are visible.
  • The order of the result is not defined.

CQStringArray CQEntity::GetFormNames();

  • Get the names of the available forms for the record.
  • The order of the result is not defined.

CQFormPtr CQEntity::GetFormByName(const CQString& formName);

  • Get a specific form by name.

void CQEntity::SaveVisibilitySettings();

  • Save the current visibility settings with the record.
  • An exception is thrown if there is no action in progress on the record.
  • Any visibility changes made after this is called are not saved, but will continue to be in effect while the record remains open in the UI.

CQEntity::ResetVisibilitySettings

void CQEntity::ResetVisibilitySettings(const CQString& formName, const BOOL resetForms, const BOOL resetTabs, const BOOL resetFields);
  • This API is experimental.
  • Reset the current visibility settings, making all hidden items be visible.
  • This applies to one or more of the forms, tabs, and fields, as specified by the boolean parameters.
  • When formName is non-empty, the reset* parameters apply only to items on the named form. In this case, if resetForms is true only the named form will be made visible.
  • When formName is "@all", the reset is applied to all forms.
  • There is no effect on the set form and tab names.
  • The effect does not apply to the saved settings. If appropriate, the reset values can be saved by calling SaveVisibilitySettings.