Chaining in the HTML Canvas

In this section:

You may chain controls to one another on the Parameters tab and apply conditions to links in the chain. Chaining will populate controls based on the selected value from the prior control in the chain. You can chain static and dynamic controls, link or unlink parts of a chain, and create conditions on links in a chain. Chains are represented by lines connecting control objects on the Design or Parameters tab. Note that chaining is applicable only for controls, not parameters.

Note:


Top of page

x
Automatically Chaining Parameters From the New Parameters Dialog Box

How to:

The auto chain option enables you to automatically chain selected controls from the New Parameters dialog box. Chaining populates controls based on the selected value from the prior control in the chain. The auto chain option is useful since it creates the chain, or links of a chain, automatically.

Note: Automatic chaining creates a basic chain with default functionality that does not include any conditions. You may create conditions for a chain through the Parameters tab.

When importing or referencing a report with parameters to an HTML page, the controls are not chained by default. You may choose to include or exclude individual controls in a chain with the Chain control column from the New Parameters dialog box.

Additionally, when the auto chain option is selected, a separator is added to the parameters list on the New Parameters dialog box. A separator is used to separate controls into multiple chains and can be moved up or down in the chain sequence.



x
Procedure: How to Auto Chain Controls From the New Parameters Dialog Box

The auto chain option creates the chain, or links of a chain, automatically. When the auto chain option is selected, a separator is added to the parameters list. A separator is used to separate controls into multiple chains and can be moved up or down in the chain sequence.

  1. In the HTML canvas, import or reference a report with parameters.

    The New Parameters dialog box opens.

  2. Select Auto chain controls in above specified order.

    Tip: You may use the up or down arrows to change the order of the selected control before selecting this option.

    The Chain control option is selected for all controls and a separator is added as the last object to the list of parameters, as shown in the following image.

  3. To create multiple chains, click the separator row and use the up or down arrows to change the location of the separator in the chain.

    Note: If the default separator is moved up, another separator is added to the end of the list.

  4. Click OK to close the New Parameters dialog box and add the control to the HTML page.

    On the Design tab, when creating multiple chains from the New Parameters dialog box, each set of chained parameters appears on a new line, regardless of the grouping option selected from the New Parameters dialog box. This behavior is set through the Start each chain on a new line option, located on the Form Settings dialog box in the HTML Page tab of the App Studio Options dialog box. This enables you to see the relationship of the chains within the form. Start each chain on a new line is selected by default.

    On the Parameters tab, chains are represented by lines connecting control objects.

  5. You can remove a chain by clicking Break binding from the shortcut menu when a chain link is selected.


x
Procedure: How to Chain Controls From the New Parameters Dialog Box

The Chain control column enables you to include or exclude individual controls in a chain, from the New Parameters dialog box.

  1. In the HTML canvas, import or reference a report with parameters.

    The New Parameters dialog box opens.

  2. Select the Chain control check box for the controls to be included in the chain.

    The controls are chained in the order that they appear on the New Parameters dialog box. You may use the up or down arrows to change the order of the selected control before chaining controls.

    Note: If a control is excluded from a chain, the chain automatically links only the selected controls.

  3. Click OK to close the New Parameters dialog box and add the control to the HTML page.

    On the Design tab, when creating multiple chains from the New Parameters dialog box, each set of chained parameters appears on a new line, regardless of the grouping option selected from the New Parameters dialog box. This behavior is set through the Start each chain on a new line option, located on the Form Settings dialog box in the HTML Page tab of the App Studio Options dialog box. This enables you to see the relationship of the chains within the form. Start each chain on a new line is selected by default.

    On the Parameters tab, chains are represented by lines connecting control objects.

  4. You can remove a chain by clicking Break binding from the shortcut menu when a chain link is selected.

Top of page

x
Chaining Controls on the Parameters Tab

How to:

Chaining enables you to associate two or more related values. When you chain controls together, chained values are filtered as selections are made to each parameter control. For example, if you chain the PLANT parameter to the STATE parameter, only PLANT values for the currently selected STATE value will be available instead of all the plants in the data source. Each time a selection is made, all chained controls that come after will be dynamically updated. Chaining also enables you to add, remove, and reverse the order of controls in the chain.

Values are processed with a caching mechanism that gathers all of the necessary values prior to loading the page. This method automatically combines all of the necessary requests into a single HTTP request and maps the result sets to the appropriate controls, greatly reducing the load time involved with sending multiple requests for data.



x
Procedure: How to Chain Controls on the Parameters Tab
  1. Create an HTML page using input controls to supply parameter values.
  2. Click the Parameters tab.
  3. Select the center of the control object and drag the control to the center of the next control object in the chain.

    Repeat this step for each link in the chain.

  4. Optionally, apply condition settings to the chain to determine how parameters are populated.

    If using static controls, you must apply conditions for each link in the chain. Conditions need to be created for each value of the control chained from, and those values must be mapped to the correct value(s) that will be displayed in the control that it is being changed to.



x
Procedure: How to Remove a Link in the Chain

  1. While on the Parameters tab, select the arrow head on the line so that the line is bold.
  2. Right-click and select Break binding.
  3. Repeat this step for each link in the chain that you want to break.


x
Procedure: How to Reverse the Order of Chained Controls

  1. While on the Parameters tab, select the arrow head on the line so that the line is bold, right-click and select Break binding.
  2. Select the center of the control object and drag the control to the center of the next control object in the chain.

    Notice the direction of the arrow between the control objects. You may reverse the direction of the link in the chain or reverse the order of the chain by changing the direction of each link.

    • If reversing the direction of a link in the chain and drag the control object in the desired order.
    • If reversing the order of a chain and drag the control objects in the desired order.

    Tip: In some scenarios, when reversing the order of chained values, you may want to move the controls from the default location on the Parameters tab so that you can better see the direction of the chain. Moving objects on the Parameters tab will not affect the Design view of your layout.

    • Press the Shift key and select the control object and bound parameter to move the objects as a set.
    • Chain the control objects together.
  3. Optionally, apply condition settings to the chain to determine how parameters are populated.

Top of page

x
Applying Conditions to a Chain

In this section:

How to:

Reference:

A chain contains conditions for each link in the chain. The conditions are linked to the values being selected in the control object. You may apply multiple conditions to one link. The settings for the condition describe how the link should behave. The following options are available:

If using static controls, you must apply conditions for each link in the chain. Conditions need to be created for each value of the control chained from, and those values must be mapped to the correct values that will be displayed in the control that it is being changed to.



x
Reference: Settings Panel (Conditions)

The Settings panel appears when creating a condition for a chain link on the Parameters tab. A chain contains conditions for each link in the chain.

The conditions are linked to the values being selected in the control object. The settings for the condition inherit the values of the prior bound control and provide additional condition settings. This section describes the additional condition settings.

The Settings panel contains the following fields and options when creating a condition:

Conditions

The conditions list enables you to create multiple conditions for the link. Default is the only initial condition.

  • To create a new condition, click the New icon. Condition(n) is created, where (n) is the number, and added to the Conditions drop-down list. You may type in a unique condition name, choose Selected values, and set the condition settings.
  • Click the Delete icon to remove the selected condition from the list. Note that the Default condition name cannot be deleted.
Actions

Select an action for the chain link to control. The options offer variations to populate, show, hide, execute, and select the values. The list of available options are:

  • Populate, show. Populates the control and displays it at run time. This is the default action for all conditions.
  • Populate, hide. Populates the control and does not display it at run time.
  • Populate with alternate, show. Populates the control with alternate values derived from a procedure, or value list, that is not the default and displays the control at run time.
  • Populate with alternate, hide. Populates the control with alternate values derived from a procedure, or value list, that is not the default and does not display the control at run time.
  • Show. Shows the control but does not populate it.
  • Hide. Hides the control but does not populate it.
  • Execute. Executes the bound object. For example, if you bind a control to a Submit button and change the value in the control at run time, the report/chart automatically executes when you change the value, without having to click the Submit button.
  • Select. Selects the bound object. For example, if you bind a control to a tab item and select a value in the control at run time, the bound object (the tab item) is automatically selected as the active tab on the page.
Values compare operator

Values compare operator provides chaining logic scenarios to include such options as Equal, Not Equal, Greater Than, Less Than, and so on. This option sets the condition for how to populate the control being linked to.

Equal is the default Values compare operator.

Selected values

Selected values enable you to provide the values used in the condition. When creating a new condition, the Selected values section is activated. You may type selected values in the input box or click the ellipsis button to select values from the list.

The list of values that appears is based on the values of the prior bound control in the chain.

When selected values are entered, the Multiselect operator field is activated.

Multiselect operator

The Multiselect operator options are activated when selected values are entered for the condition. Options are One of or All of. One of is based on one of the values shown in the Selected values, being selected in the prior control, in the chain. All of is based on the value of all of the Selected values, being selected in the prior control, in the chain.

One of is the default multiselect operator.

Resolves parameter (“To:” field is required)

From. The From field specifies where to get the value used in the To field, if the control being chained from is a map or activeX control.

To. The To field is used to dynamically generate the selection list used to populate the control being chained to. This field displays the parameter whose value will drive the condition evaluation. The parameter name linked to the prior control in the chain is displayed by default. The ellipsis button provides a pop-up dialog of the other parameter values (from the report) to be resolved.

Compare operator

The Parameter’s compare operator provides chaining logic scenarios to include such options as Equal, Not Equal, Greater Than, Less Than, and so on. This sets the compare operator to populate the control.

Equal is the default Compare operator.



x
Procedure: How to Create a New Condition
  1. Insert a report with parameters in the HTML canvas.
  2. Drag control objects on the Parameters tab to create a chain.

    Chains are represented by lines connecting control objects on the Parameters tab.

    Chaining controls will populate parameters with values at run time, based on values selected in prior controls on the chain.

  3. Click a link in the chain.

    The Settings panel shows the bound control values and the Default condition settings for the link in the chain.

  4. Click the New icon to create a multiple condition for the chain.

    Condition(n) is created, where (n) is the number, and added to the Conditions drop-down list, and the Selected values section is activated. You may type in a unique condition name.

  5. You may type in a unique condition name, choose Selected values, and set the condition settings for the new condition.
  6. Optionally, you may click the Delete button to remove the selected condition from the list.

    Note: Default, the initial condition, cannot be deleted.



x
Procedure: How to Select the Action for a Condition
  1. Insert a report with parameters in the HTML canvas.
  2. Drag control objects on the Parameters tab to create a chain.

    Chains are represented by lines connecting control objects on the Parameters tab.

    Chaining controls will populate parameters with values at run time, based on values selected in prior controls on the chain.

  3. Click a link in the chain.
  4. In the Setting panel, select the action for the condition from the Actions drop-down list. For example, to hide the control being chained to, select Hide.

    Populate, show is the default option.

  5. Close the Settings panel.

When running the HTML page, the action for the chained control is applied.



x
Procedure: How to Select the Values Compare Operator for a Condition
  1. Insert a report with parameters in the HTML canvas.
  2. Drag control objects on the Parameters tab to create a chain.

    Chains are represented by lines connecting control objects on the Parameters tab.

    Chaining controls will populate parameters with values at run time, based on values selected in prior controls on the chain.

  3. Click a link in the chain.
  4. In the Setting panel, select the chaining logic for the parameter being chained to, in the condition, from the Values compare operator drop-down list.

    Equal is the default option.

The compare operator is applied to the value selected.



x
Procedure: How to Apply Selected Values With a Multiselect Operator to a Condition
  1. Insert a report with parameters in the HTML canvas.
  2. Drag control objects on the Parameters tab to create a chain.

    Chains are represented by lines connecting control objects on the Parameters tab.

    Chaining controls will populate parameters with values at run time, based on values selected in prior controls of the chain.

  3. Click a link in the chain.
  4. In the Setting panel, click the New icon to create a multiple condition for the chain.

    Condition(n) is created, where (n) is the number, and added to the Conditions drop-down list, and the Selected values section is activated. You may type in a unique condition name.

  5. You may type selected values in the input box or click the ellipsis button to select values from the list.

    The list of values that appears is based on the values of the prior bound control in the chain.

    Tip: You may also use the pop-up icons to select a field and close the pop-up dialog. The green icon is OK, the red icon is Cancel, double-clicking a value will select the value and close the dialog without using any button, and pressing the Esc key will cancel the dialog without using any button.

    When selected values are entered, the Multiselect operator field is activated.

  6. Select the chaining logic for the selected values from the Multiselect operator drop-down list.
    • One of is based on one of the values shown in the Selected values, being selected in the prior control, in the chain. This is the default selection.
    • All of is based on the value of all of the Selected values, being selected in the prior control, of the chain.

The selected values and multiselect operator are applied to the condition.



x
Procedure: How to Resolve Parameters for a Condition

It is recommended that you populate the controls first, before chaining. When you populate first certain information is obtained that allows the determination of the best choice for Resolves parameter. If you chain first and then populate, the information cannot be obtained because the chaining is already established. If you chain first, you must manually set Resolves parameter.

  1. Insert a report with parameters in the HTML canvas.
  2. Drag control objects on the Parameters tab to create a chain.

    Chains are represented by lines connecting control objects on the Parameters tab.

    Chaining controls will populate parameters with values at run time, based on values selected in prior controls on the chain.

  3. Click a link in the chain.
  4. In the Setting panel, click the Resolves parameter ellipsis button to select a parameter name to resolve. If a custom procedure that has a filter (or filters) populates the control, the values list shows the parameters from the filters. If a data source populates the control, the values list shows all of the fields from the data source shown in the Object Inspector.

    The value in the Resolves parameter field should be either:

    • The field name that limits the values for the next control in the chain, if a data source populates the control.
    • The parameter name from the procedure, if a procedure populates the control.

    In most cases, this value will be populated by default and will not need to be changed.

    Tip: You may also use the pop-up icons to select a field and close the pop-up dialog. The green icon is OK, the red icon is Cancel, double-clicking a value will select the value and close the dialog without using any button, and pressing the Esc key will cancel the dialog without using any button.

  5. Close the Settings panel.

The parameter value is resolved in the chain if no filter is specified.



x
Procedure: How to Select the Compare Operator for the Parameter

An example of when to apply chaining logic is when a form offers two lists of dates so that you can select a FROM/TO date range. By chaining these parameters together and applying the Greater than parameter compare operator, this ensures that when a date is selected for the FROM parameter, only dates that follow the FROM date display in the TO date control, eliminating the possibility of selecting an invalid date range.

  1. Insert a report with parameters in the HTML canvas.
  2. Drag control objects on the Parameters tab to create a chain.

    Chains are represented by lines connecting control objects on the Parameters tab.

    Chaining controls will populate parameters with values at run time, based on values selected in prior controls on the chain.

  3. Click a link in the chain.
  4. In the Setting panel, select the chaining logic option from the Compare operator drop-down list. This sets the compare operator to populate the control.

    Equal is the default option.

The compare operator is applied to the parameter selected.



x
Procedure: How to Enable Cache Processing for Chained Values

You may enable cache processing for chained values in two ways:

Caching options are turned off by default.

  1. To enable caching options for all objects on the HTML page, in the App Studio Options dialog box:
    • Select the HTML Page tab.
    • Select Default caching option.
    • Click OK to close the App Studio Options dialog box.
  2. To enable caching options for a dynamic control or condition:

    A chain contains conditions for each link in the chain. The conditions are linked to the values being chained to the control object. If you change the options for the condition, it will also be applied to the control, and vice versa.

    For a dynamic control:

    1. Create a dynamic input control to supply parameter values.
    2. Select the dynamic control object from the Parameters tab.

      The Settings panel opens, showing the dynamic control options.

    3. Select Cache run time data to cache the run time data for the selected input control.

      Note: This setting overrides the Default caching option from the HTML Page tab, in the App Studio Options dialog box.

    4. Select the center of the control object and drag the control to the center of the next control object.

      When binding controls, the conditions inherit the values set in the dynamic control settings.

    For a dynamic condition:

    1. Click a link on the chain to open the Settings panel for the condition.
    2. Select Cache run time data to cache the run time data for the selected input control. This option is only available for dynamic controls.

      This setting overrides the Default caching option from the HTML Page tab, in the App Studio Options dialog box.

    When running the HTML page, data for the chained value is cached to improve performance.



x
Setting the Default Link

If a control or parameter has two or more incoming bindings, one of those bindings can be set as the default link. This ensures that population occurs in the control or parameter. When a control or parameter has multiple incoming bindings, the shortcut menu for each of those bindings has the Default link option, as shown in the following image.

When a binding is the default link, it will have a check mark next to the Default link option in the shortcut menu, as shown in the following image.

Note:

If two controls are chained to a third control, the binding that has Default link selected shows which control will be used to populate the third control by default. Similarly, if two controls are bound to a parameter, the Default link option shows which control is used to populate the parameter.

If two parameters are bound to a control, the binding that has Default link selected makes the initial selection in the control.


WebFOCUS