Using Parameters

In this section:

Parameters, or "variables," are a good way to make a single HTML page valuable to a wide range of end users. For example, if you have a parameter for region, the end users can select their own region at run time. This improves performance, saves users from scrolling through data that is not pertinent, and saves you from having to build multiple pages.

Parameter values and input controls can be created with a dynamic or static list of values:

Working With the Parameters Tab

The Parameters tab enables you to create and modify parameter values, input controls, and customize parameter conditions. You can also bind parameters to controls and chain controls to one another. The Parameters tab consists of the following components:

Adding a New Unbound Parameter

How to:

An unbound parameter is useful when passing a parameter value used on another page. You may also bind the new parameter to a control to create an incoming parameter, or bind a control to the parameter.

Procedure: How to Add a New Unbound Parameter

The following steps describe how to add a new parameter:

  1. Right-click anywhere on the Parameters tab and select Add parameter.

    Enter the parameter value information. Options are Single select, Multiselect OR, and Multiselect AND.

  2. If using single value, select Single select.

    Note: Single select is the default option when adding a new parameter.

    1. Enter the Selected Value to be assigned to a single variable.
    2. Enter the name for the parameter in the Name field, or keep the default name.
    3. Optionally, you may use the Format field to define the format of the parameter, such as A20, or D12.2.

      If this field is left blank, it automatically applies the Alphanumeric format to the value field.

  3. If using a multiselect value, select Multiselect OR or Multiselect AND.

    The Value, Display, and Selected columns appear.

    1. Click the New button to enter a list of static values.
    2. In the Value column, enter the value to be passed to the selected parameter.
    3. In the Display column, enter the text that represents the parameter value in the control the user views.
    4. In the Selected column, check the box for the value you want to be selected by default. More than one value can be selected.

    Repeat these steps until the list contains all of the values you want to include.

  4. Optionally, you may select values and click the Delete button to eliminate any values, and use the up and down arrows to rearrange the order of the values.
  5. To modify the parameter value, right-click the parameter on the Parameters tab and select Settings to make your edits.

    Tip: You may also use the Undo and Redo buttons located on the Standard toolbar. Note that undo/redo treats the entire Settings panel as one action.

  6. Optionally, bind a control to a parameter to populate the parameter. Select the center of the parameter name object and drag the parameter to the center of the control object.
  7. Optionally, bind the new parameter to a control to create an incoming parameter. Select the center of the control object and drag the control to the center of the parameter object.

Procedure: How to Link an Unbound Parameter to a Procedure

The following steps describe how to link an unbound parameter to a procedure. As an example, a heading is added to a report in the steps below.

  1. Create a new HTML page.
  2. From the Requests & Data Sources panel, click the New drop-down arrow and select External Request - WebFOCUS Procedure.
  3. Select any simple or parameterized procedure.

    Note: In this example, we are using a report.

  4. Insert a frame in the canvas.
  5. In the Tasks & Animations panel, select the load task.
  6. Click the arrow in the Requests/Animations section, select Run Request and select your procedure.
  7. Select the Target type as Frame.
  8. Select the frame from the Target/Template Name drop-down list.
  9. In the Requests & Data Sources panel, right-click Parameters Created in Current Page and select New Parameter.

    Note: You can also create a new unbound parameter as described in How to Add a New Unbound Parameter.

  10. Navigate to the Parameters tab and drag Parameter1 outside the Unbound Parameters box.
  11. Select Parameter1 and in the Settings panel, enter A20 in the Format field.
  12. Select the check box in the Apply To field next to the procedure you want to link, as shown in the following image.
  13. Enter an alphanumeric value in the Selected Value field.
  14. Open the procedure.
  15. From the Report group on the Report tab, use the Header & Footer option to add a Report Header.
  16. Enter &Parameter1 in the Report Heading text box.
  17. Run the HTML page.

    Notice that the value entered in the Settings panel for Parameter1 is displayed in the report heading.

Creating a Static List of Values

How to:

Reference:

When creating a list of static values, you can select from the following options:

When the options are added to the Value list, the display text can be customized, but the value cannot be changed.

You may create an unbound static parameter, an incoming static parameter (a parameter that is bound to a control), or a control that is bound to a static parameter.

Reference: Settings Panel (Incoming Static Parameter and Unbound Control)

The Settings panel appears when creating or editing a static value on the Parameters tab.

The options available depend on the type of static value.

The Settings panel contains the following fields and options when Static is selected as the Data type.

Data type

Determines whether values are obtained from a static or dynamic list, an Analytic Document, or table of contents.

Static. Uses a static list of values you supply. A list of static values can also be created in the Report canvas.

Static values

Is a list of supplied values for a static list.

Value. The value to be passed to the selected parameter.

Display. The text that represents the value in the control the user views. Press the Ctrl + Shift keys to add a value to the Display field.

Selected. The value to act as the default value. If the control is multiselect, more than one value can be selected.

New. Creates a new value.

Delete. Deletes a supplied value from the list.

Move Up. Moves the selected value up in the list.

Move Down. Moves the selected value down in the list.

Send display value

Select this option to send the display value, rather than the actual data, to the parameter.

Values are procedures names

Select this option to have a control populated with procedure names, so that when a value is selected, that procedure executes. The Value column is the procedure name itself and cannot be edited. The Display column is editable.

Reference: Settings Panel (Unbound Parameter)

The Settings panel appears when creating or editing a static value on the Parameters tab.

The options available depend on the type of static value.

The Settings panel contains the following fields and options when adding an unbound parameter with Single select. Single select is the default option when adding a new parameter.

Name

The default name assigned to the parameter. Optionally, you may enter a new name for the parameter.

Format

The Format field defines the format of the parameter, such as A20, or D12.2.

This field is optional. If this field is left blank, it automatically applies the Alphanumeric format to the value field.

Selected Value

Enter the selected value to be assigned to the parameter.

Static values

Is a list of supplied values for a static list.

Value. The value to be passed to the selected parameter.

Display. The text that represents the value in the control the user views. Press the Ctrl + Shift keys to add a value to the Display field.

Selected. The value to act as the default value. If the control is multiselect, more than one value can be selected.

New. Creates a new value.

Delete. Deletes a supplied value from the list.

Move Up. Moves the selected value up in the list.

Move Down. Moves the selected value down in the list.

Reference: Settings Panel (Bound Parameter)

The Settings panel appears when selecting a bound parameter on the Parameters tab. The Settings panel for a parameter is read-only, and displays the values for the bound control.

The Settings panel contains the following read-only values:

Value

Shows the selected value for the static parameter data.

Display

Shows the static parameter display value.

Procedure: How to Add a New Static Value

The steps below describe how to manually add a new static value:

You may create an unbound static parameter, an incoming static parameter (a parameter that is bound to a control), or a control that is bound to a static parameter.

  1. Create a new parameter.
    1. Right-click anywhere on the Parameters tab and select Add parameter.
    2. Enter the parameter value information in the Settings panel. Options are Single select, Multiselect OR, and Multiselect AND.
    3. If using single value, select Single select.

      Single select is the default option when adding a new parameter.

      • Enter the Selected Value to be assigned to a single variable.
      • Enter the name for the parameter in the Name field, or keep the default name.
      • Optionally, you may use the Format field to define the format of the parameter, such as A20, or D12.2.

        If this field is left blank, it automatically applies the Alphanumeric format to the value field.

    4. If using a multiselect value, select Multiselect OR or Multiselect AND.

      The Value, Display, and Selected columns appear.

      • Click the New button to enter a list of static values.
      • In the Value column, enter the value to be passed to the selected parameter.
      • In the Display column, enter the text that represents the parameter value in the control the user views.
      • In the Selected column, check the box for the value you want to be selected by default. More than one value can be selected.

        Repeat these steps until the list contains all of the values you want to include.

      • Optionally, you may select values and click the Delete button to eliminate any values, and use the up and down arrows to rearrange the order of the values.

    An unbound static parameter is useful when passing a parameter value used on another page. You may also bind the new parameter to a control to create an incoming parameter, or bind a control to the parameter.

  2. Bind the new parameter to a control.

    Binding a new parameter to a control creates an incoming parameter. An incoming parameter is a static parameter that is bound to a control. The parameter value will populate the control.

    1. Select the Design tab and create an input control. For example, insert a list box or a drop-down list.
    2. Click the Parameters tab.

      The Settings panel appears for the control.

    3. Select the center of the parameter name object and drag the parameter to the center of the control object.
    4. To unbind the parameter, select the arrow head on the line, so that the line is bold, right-click, and select Break binding.
  3. Create a control that is bound to a parameter.

    Create a control with static values and bind the control to a parameter to populate the parameter with the control values.

    1. From the Design view of the HTML canvas, select a control.

      The pointer changes into a crosshair.

    2. Drag the crosshair to create the control and adjust it to the size you want.
    3. Click the Parameters tab.

      The Settings panel appears for the control.

    4. Select Static as the Data type.

      Static is selected, by default.

    5. Create the parameter values for the control:
      • In the Value column, enter the value to be passed to the control.
      • In the Display column, enter the text that represents the static parameter value in the control the user views.
      • In the Selected column, check the box for the value you want to be selected by default. More than one value can be selected.

        Repeat these steps until the list contains all of the values you want to include.

      • Optionally, you may select values and click the Delete button to eliminate any values, and use the up and down arrows to rearrange the order of the values.
    6. Bind the new control to a parameter: Select the center of the control object and drag the control to the center of the parameter object.
    7. To unbind the control, select the arrow head on the line, so that the line is bold, right-click and select Break binding.
    8. To change the default type of control, right-click the control object on the Parameters tab or the Design tab and select Set Control Type.

      The options are Calendar, Check box, Drop down list, Hidden, List box, Radio button, Text Area, Edit box, Single source Tree control, and Multi source Tree control.

  4. To modify the static value, right-click the control, or parameter, on the Parameters tab and select Settings to make your edits.

Reference: Adding Static Field Values From the Report Canvas

Instead of adding new static values, you may also import static value parameters that you created from the Variable Editor dialog box. Parameter values can be data values to limit your data or field names to select the fields in your report. Both types of static lists can be created in the Report canvas. This example details how to supply field values to a report through the HTML canvas and the Report canvas.

For the purposes of this example, use the CAR Master File (car.mas) that is supplied with App Studio.

  1. From the HTML canvas, insert a new report.

    The pointer changes into a crosshair.

  2. Drag the crosshair to create a report object and adjust it to the size you want.
  3. Double-click the report object.

    The Open File dialog box appears.

  4. Select the car.mas Master File and click OK.

    The Report canvas opens.

  5. From the Object Inspector, expand Variables, right-click Report Variables, and click New Report Variable Field.

    The Variable Editor dialog box opens.

    • Enter SORTVAR in the Name and Prompt input fields, and keep the Variable Type as Single Select.
    • Click Static list from the Accept List section.
    • Double-click COUNTRY and BODYTYPE from the Fields from database Data Context area.

      The fields are added to the Static Accept List.

    • Click OK to save the variable.
  6. Create a second variable.
    • Right-click Report Variables and click New Report Variable Field.

      The Variable Editor dialog box.

    • Enter MEASURES in the Name and Prompt input fields.
    • Click Multiselect AND from the Variable Type drop-down list.
    • Click Static list from the Accept List section.
    • Double-click CAR, DEALER_COST, RETAIL_COST, and SALES from the Fields from database Data Context area.

      The fields are added to the Static Accept List.

    • Click OK to save the variable.
  7. Double-click &SORTVAR and &MEASURES from the Report Variables in the Object Inspector.

    The variables are added to the report.

  8. Click &SORTVAR and select Sort Down from the Column Type group on the ribbon.

    Note: If the parameter is to be used as a By field in a report, it must be the single-select variable type.

  9. Save and close the report.

    You are returned to the HTML canvas and since you are adding a report with parameters, the New Parameters dialog box appears.

  10. From the New Parameters dialog box:
    • Select Double list control from the Control Type list for MEASURES.
    • Select Do not create a form from the Parameter grouping options drop-down list.
    • Click OK to close the New Parameters dialog box.

    The report and associated parameters are added as static field values. You may rearrange or lengthen the controls in the layout.

  11. Save and run the layout.

    Select the static field values (By field and the associated measures) and run the report.

Procedure: How to Add an Ignore Value

The add ignore value option sends _FOC_NULL to the server at run time and is intended for use with complex applications. The add ignore value option is available for Multiselect OR and Multiselect AND static parameters.

  1. From the HTML canvas, use controls to supply parameter values for a report.

    A report with parameters requires that you to select values (at run time) in order to generate the output.

  2. Click the Parameters tab.

    The parameters associated with each control can be controlled with the Parameters tab. The properties of a control can be controlled with the Properties tab.

  3. Select a multiselect control object from the Parameters tab.

    The Settings panel opens.

  4. Select Add ignore value from the Static values drop-down list.
  5. Optionally, select Send display value to send the display value, rather than the actual data, for the parameter values in the report.
  6. Close the Settings panel.
  7. Run the HTML page and select the Ignore All value to ignore the parameter values.

Note: Sending _FOC_NULL to a procedure will result in any clause of that procedure that uses that variable to be ignored.

Procedure: How to Add an Everything Value

The add everything value option uses JavaScript to send every value present in the parameter list to the server at run time. The add everything value option is available for Multiselect OR and Multiselect AND static parameters.

The add everything value option is not available for a Double List Control.

  1. From the HTML canvas, use controls to supply parameter values for a report.
  2. Click the Parameters tab.
  3. Select a multiselect control object from the Parameters tab.

    The Settings panel opens.

  4. Select Add everything value from the Static values drop-down list.
  5. Optionally, select Send display value to send the display value, rather than the actual data, for the parameter values in the report.
  6. Run the HTML page and click the Select All parameter value to view all the parameter values.

Procedure: How to Use Values From a Procedure

This is the default option which populates the static list with field names predefined in the procedure. The use values from procedure option is available for Multiselect OR and Multiselect AND static parameters, and when adding static field values from the Report canvas.

  1. From the HTML canvas, use controls to supply parameter values for a report.
  2. Click the Parameters tab.
  3. Select a multiselect control object from the Parameters tab.

    The Settings panel opens.

  4. Select Use values from procedure from the Static values drop-down list.

    The field names from the procedure appear in the Settings panel.

  5. Optionally, select Send display value to send the display value, rather than the actual data, for the parameter values in the report.
  6. Run the HTML page and select the parameter values from the procedure.

Procedure: How to Import Values From an External File

This option enables you to use a local external file to provide values for the parameter. The import values from an external file option is available for Multiselect OR and Multiselect AND static parameters.

  1. From the HTML canvas, use controls to supply parameter values for a report.
  2. Click the Parameters tab.
  3. Select a multiselect control object from the Parameters tab.

    The Settings panel opens.

  4. Select Use values from external file from the Static values drop-down list.

    The Open File dialog box appears.

  5. Select a text file from your local machine and click Open.

    The external file can be a file with single values on each line, or two values per line, comma-delimited.

    For example, in the following text file, BOS is the data value and Boston is the display value.

    The imported values are loaded into the Static values area of the Parameters tab.

    If there is only one value on the line in the text file, the value will populate both the data value and the display values.

  6. Run the HTML page to see the imported values for the selected parameter.

Creating a Dynamic List of Values

How to:

Reference:

Dynamic values are available by default if a parameter used in the procedure is associated with the selected control. A dynamic list retrieves values from a specified data source when the request is run.

Reference: Settings Panel (Dynamic Values)

The Settings panel appears when creating or editing a dynamic parameter on the Parameters tab.

The Settings panel contains the following fields and options when Dynamic is selected as the Data type:

Data type

Determines whether values are obtained from a static or dynamic list, an Analytic Document, or table of contents.

Dynamic uses a list of values retrieved from a selected data source when the request is executed. This is the default if you use an Accept clause in a Master File to create an amper variable parameter within a procedure.

Default

Is the data source from which the values will be retrieved. This is the default value when Dynamic is selected as the Data Type.

Explicit (Requests panel)

Is the existing procedure that will be called.

You may modify the explicit procedure directly from the Settings panel on the Parameters tab. If you modify the request, you can save the explicit procedure and overwrite the original request.

Data Source

Is the data source from which the values will be retrieved.

Value from field

Is the data source field from which the values will be retrieved.

Display from field

Is the text that represents the parameter value in the control the user views.

There should be a relationship between the Value from field and the Display from field. The Display from field is user-friendly text corresponding to the Value from field.

Source Code for the procedure
  • When the Value from field is selected for the default procedure, the corresponding source code appears.

    Tip: You may manually edit the source code if you are familiar with WebFOCUS syntax. For example, you may right-click and choose Select a field from the data source to add to the request. You can also right-click and choose Use the default request.

    The source code for a default procedure includes the line // TODO: Add your filters here to replace defaults, as a placeholder for you to enter filters, or WHERE clauses, for the request to resolve at run time. If entering filters, only dynamic filters can be specified.

    The //TODO line must remain in the source code in order to resolve filters at run time. One such example of this is when filters are based on chains that have conditions. If you want your own filters specified, then delete this line.

  • When an explicit procedure is selected, the corresponding source code appears.

    Tip: You may manually edit the source code if you are familiar with WebFOCUS syntax. For example, you may right-click and choose Select a field from the data source to add to the request. After editing the procedure that is associated with a control, right-click and choose Reload explicit procedure to reload and display the new syntax in the Settings panel. You can also right-click and choose Save explicit procedure. Saving the explicit procedure overwrites the original requests.

Sort

Clicking Sort enables you to set the sort order for displaying values in dynamic list controls. This option is useful when you want to sort each control independently of the others.

By default, the request retrieves dynamic display values from the BY sort field in the request. The results display values based on the value field.

Sort by

When Sort is enabled, you may sort the display value by the Value field or the Display field selected from the Settings panel. The default is Value field.

Sort order

When Sort is enabled, you may select the sort order as Ascending or Descending. The default sort order is Ascending.

Values are procedures/html files

Indicates that the values in the control are procedures or HTML pages. You can create a task using the Run Procedures/HTML From Control request option in the Tasks & Animations panel to run the file selected in the control.

Check for duplicate values

When creating a dynamic list of values for a report, you may remove duplicate values from input controls.

Add "All" Option

Adds the option to select all data source values to the control. Alternate text can be substituted for All using the text field to the right.

Note: If the dynamic list contains only one value, the All option does not display in the control.

Add ‘No selection' option

Optimizes performance by populating a chain one control at a time, instead of all the controls when the page initially loads. Selecting the Add ‘No selection’ option enables you to populate controls when necessary.

Cache run time data

When adding dynamic parameters to the HTML page, input controls retrieve data through procedures. Select this option to cache the run-time data for the selected input control. This setting is off by default.

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

Limit values returned

Indicates that a specific number of field values will be retrieved from the data source. The specific number of fields is selected with the menu to the right.

Use last modified filter only

Selecting this option ensures that if two controls are chained into a third control, only the value selected last will be used to populate the third control.

Send display value

Select this option to send the display value, rather than the actual data, to the parameter.

Selected Value

Enter the value to be selected as the default value whenever the procedure is run.

Reference: Settings Panel (Bound Parameter)

The Settings panel appears when selecting a bound parameter on the Parameters tab. The Settings panel for a parameter is read-only and displays the values for the bound control.

The Settings panel contains the following read-only values:

Data Source

Shows the selected Master File for the parameter data source.

Value from

Shows the value field for the dynamic parameter data.

Display from

Shows the dynamic parameter display field.

Multiselect

Shows OR or AND, if there is a Multiselect OR or Multiselect AND dynamic parameter.

Selected Value

Shows the selected value, if there is one assigned to the variable.

Procedure: How to Create a Dynamic Value

The steps below describe how to create a dynamic list of values.

You may need to create a dynamic control that is bound to a parameter. Creating a control with dynamic values and binding the control to a parameter will populate the parameter with the control values.

  1. From the Design view of the HTML canvas, select a control from the Controls submenu of the Insert menu. For example, insert a list box or drop-down list.

    The pointer changes into a crosshair.

  2. Drag the crosshair to create the control and adjust it to the size you want.
  3. Click the Parameters tab.

    The Settings panel opens.

  4. Select Dynamic as the Data type.

    The dynamic value options appear.

  5. Create the dynamic values for the control.
    1. If you are using a default procedure to supply dynamic values, follow the steps below.
      • Click the browse (...) button adjacent to the Data Source drop-down list.

        The Open File dialog box appears.

      • Select the Master File name and click OK.
      • Click the browse (...) button adjacent to the Value from field.

        The Object Inspector opens with the field names from the selected Master File.

      • Double-click a field name to add it to the Value from field.

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

        The selected field is automatically added to the Display field and the source code for the procedure appears.

      • Optionally, you may click the browse (...) button adjacent to the Display from field to select a different field name for the Display field. (You may also use the Object Inspector icons to select a field and close the Object Inspector).
      • You may manually edit the source code if you are familiar with WebFOCUS syntax. Right-click and choose Select a field from the data source to add to the request. For example, add an additional BY sort field to the request.
      • To remove any syntax that you added, right-click and select Use the default request.
      • The source code for a default procedure includes the line // TODO: Add your filters here to replace defaults, as a placeholder for you to enter filters, or WHERE clauses, for the request to resolve at run time. If you are entering filters, only dynamic filters can be specified. For example, enter a filter for the CITY in the request.

        The //TODO line must remain in the source code in order to resolve filters at run time. One example of this is when filters are based on chains that have conditions. If you want your own filters specified, then delete this line.

    2. If you are using an explicit procedure to supply dynamic values, follow the steps below.
      • Select Explicit (Requests Panel).
      • Select a procedure from the Requests drop-down list.

        The parameter names from the procedure are automatically added to the Value from field and Display from field, and the source code for the explicit procedure appears.

      • Optionally, you may click the browse (...) button adjacent to the Value from field and Display from field to select different field names.

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

        Only the parameter names from the explicit procedure will be available for selection.

      • You may manually edit the source code if you are familiar with WebFOCUS syntax. Additionally, you may right-click and choose Select a field from the data source to add to the request.
      • If you modify the request that is associated with a control, you can right-click and choose Reload explicit procedure to reload and display the new syntax in the Settings panel. Or right-click and choose to Save explicit procedure. Saving the explicit procedure overwrites the original requests.
  6. Optionally, select Add "All" option to add the ability to select all data source values to the control.
  7. Optionally, select Add 'No selection' option to optimize performance by populating a chain one control at a time instead of all the controls when the page initially loads.
  8. Optionally, select Cache run time data to cache the run time data for the selected input control.
  9. Optionally, select Limit values returned, and select or type the number of field values you want to retrieve from the data source in the box to the right of this option.
  10. Optionally, click the Sort option to enable and select the sort order options for displaying values in dynamic list control.
  11. Optionally, select Check for duplicate values to remove any duplicate value entries from the input control at run time.
  12. Bind the new control to a parameter. Select the center of the control object and drag the control to the center of the parameter object.
  13. To unbind the control, select the arrow head on the line, so that the line is bold, right-click and select Break binding.
  14. To change the default type of control, right-click the control object on the Parameters tab or the Design tab and select Set Control Type.

    The options are Calendar, Check box, Drop down list, Hidden, List box, Radio button, Text Area, Edit box, Single source Tree control, and Multi source Tree control.

  15. To modify the dynamic value, right-click the control and select Settings to make your edits.

Procedure: How to Create Dynamic Parameters by Adding a Filter

You may create new dynamic parameters by adding a filter to a report or graph component in the layout.

  1. To create dynamic parameters for your report or graph in the Design view, right-click the report or graph object and select Add a filter from the shortcut menu.

    The Filter options dialog box opens.

  2. Select the field to be used for the parameter, the Multiselect option, and click OK.

    The New Parameters dialog box appears.

    You may select a control type for the parameter from this dialog box, or adjust them later using the Settings panel on the Parameters tab.

    If the New Parameters dialog box does not appear, ensure that Show New Parameters dialog is selected from the HTML Page tab. To access the HTML Page tab, select Options from the Window menu to open the App Studio Options dialog box. From the App Studio Options dialog box, select the HTML Page tab.

  3. Click OK to close the New Parameters dialog box.
  4. The filter appears above the report or graph object.

    Repeat this procedure for each additional parameter for the report or graph.

Procedure: How to Sort the Dynamic List of Values

This option is useful when you want to sort each control independently of the others.

Note: If sort options are not selected, the request retrieves dynamic display values from the BY sort field in the request, and the results display values based on the value field. Sort options are not selected by default.

  1. Select a dynamic control from the Parameters tab.

    The Settings panel opens.

  2. Select Sort to enable the sort options.

    You may select the Sort by and Sort order options for the control.

  3. Select the Sort by options:
    • Sort by Value sorts the value by the field name from the Value field. This is the default Sort by selection.
    • Sort by Display sorts the value by the field name from the Display field.
  4. Select the Sort order options:
    • Sort order Ascending sorts the value from lowest to highest. This is the default Sort order selection.
    • Sort order Descending sorts the value from highest to lowest.
  5. Run the HTML page to see the sort results.

Procedure: How to Check for Duplicate Values

When creating a dynamic list of values for a report, you may remove duplicate values from input controls. This is useful if you are using your own procedure that does not use a structured data source.

The Check for duplicate values option is turned off by default.

  1. From the HTML canvas, create an input control with a dynamic list of values.
  2. Select the input control and click the Parameters tab.

    The Settings panel opens for the input control.

  3. Select the Check for duplicate values check box.

    The Check for duplicate values option is only available when creating a dynamic list of values for an input control.

  4. Save and run the HTML page.

    The input control removes duplicate value entries.

    The following example shows a list box with a list of city values. The first list box shows the list of values with duplicate entries. The second list box shows the list with duplicate values removed.

Using Custom Procedures to Retrieve Dynamic Values

You have the option to allow customized retrieval of dynamic parameter values. By using a custom procedure, you can use the WebFOCUS language to utilize temporary HOLD files, filtering, and so on. This allows the HTML canvas to better integrate with a multitude of large and/or proprietary data sources that may require unique retrieval methods. The procedure must meet the following criteria:

Note: Different parameters in the same procedure can use both this option and the data source method.

For chained controls, there are two options based on whether caching is enabled:

Example: Retrieving Dynamic Parameter Values With One Value

The following example shows the same value being used for the submission value and display value. 

TABLE FILE GGSALES
PRINT DST.PRODUCT
BY PRODUCT
ON TABLE SET HOLDLIST PRINTONLY
ON TABLE PCHOLD FORMAT XML
END

The XML output is:

<?xml version="1.0" encoding="ISO-8859-1" ?> 
- <fxf version="1.0" data="hold"> 
- <report records="4317" lines="10" columns="2" rows="10"> 
    <target format="" version="" type="" destination="HOLD" /> 
  - <column_desc> 
      <col colnum="c0" fieldname="PRODUCT" alias="E01" datatype="char"
         width="16" focus_format="A16" description="Product name"
         accept="" help_message="" title="Product" within="" property=""
         reference="" valign="left" />
      <col colnum="c1" fieldname="PRODUCT" alias="E02" datatype="char"
         width="16" focus_format="A16" description="Product name"
         accept="" help_message="" title="Product" within="" property=""
         reference="" valign="left" />
    </column_desc> 
  - <table>
    - <tr linetype="data" linenum="1"> 
        <td colnum="c0">Biscotti</td>
        <td colnum="c1">Biscotti</td>
      </tr>
    - <tr linetype="data" linenum="2">
        <td colnum="c0">Capuccino</td>
        <td colnum="c1">Capuccino</td>
      </tr>
    - <tr linetype="data" linenum="3">
        <td colnum="c0">Coffee Grinder</td>
        <td colnum="c1">Coffee Grinder</td>
      </tr>
    - <tr linetype="data" linenum="4">
        <td colnum="c0">Coffee Pot</td>
        <td colnum="c1">Coffee Pot</td>
      </tr>

Example: Retrieving Dynamic Parameter Values With Two Values

The following example shows two different field values being used for the submission value and display value. In this case, PRODUCT (Product Description) is used for the display value and PCD (Product Code) is used as the submission value. 

TABLE FILE GGSALES 
PRINT DST.PRODUCT 
BY PCD 
ON TABLE SET HOLDLIST PRINTONLY 
ON TABLE PCHOLD FORMAT XML 
END

The XML output is:

<?xml version="1.0" encoding="ISO-8859-1" ?>
- <fxf version="1.0" data="hold">
  - <report records="4317" lines="10" columns="2" rows="10">
     <target format="" version="" type="" destination="HOLD" />
      - <column_desc>
        <col colnum="c0" fieldname="PCD" alias="E01" datatype="char"
           width="4" focus_format="A04"
            description="Product Identification code (for sale)" accept="" 
           help_message="" title="Product ID" within=""
           property="" reference="" valign="left" />
        <col colnum="c1" fieldname="PRODUCT" alias="E02" datatype="char"
           width="16" focus_format="A16"
           description="Product name" accept="" help_message=""
           title="Product" within="" property="" reference=""
            valign="left" />
        </column_desc>
     - <table>
       - <tr linetype="data" linenum="1">
           <td colnum="c0">C141</td>
           <td colnum="c1">Espresso</td>
         </tr>
       - <tr linetype="data" linenum="2">
           <td colnum="c0">C142</td>
           <td colnum="c1">Latte</td>
         </tr>
       - <tr linetype="data" linenum="3">
           <td colnum="c0">C144</td>
           <td colnum="c1">Capuccino</td>
         </tr>

Note: The procedure does not have to follow this WebFOCUS syntax exactly, but the end result must be two values per data line in XML format.

Example: Retrieving Values for Chained Variables With Caching Disabled

In the following procedures, there are three parameters (REGION, ST, CITY). Caching is disabled, so each parameter control must be mapped to its own procedures.

Procedure 1 (REGION)

TABLE FILE GGSALES 
PRINT DST.REGION 
BY REGION 
ON TABLE SET HOLDLIST PRINTONLY 
ON TABLE PCHOLD FORMAT XML 
END

Procedure 2 (ST)

TABLE FILE GGSALES 
PRINT DST.ST 
BY ST WHERE REGION EQ '&REGION'; 
ON TABLE SET HOLDLIST PRINTONLY 
ON TABLE PCHOLD FORMAT XML 
END

Procedure 3 (CITY)

TABLE FILE GGSALES 
PRINT DST.CITY 
BY CITY WHERE REGION EQ '&REGION'; WHERE ST EQ '&ST'; 
ON TABLE SET HOLDLIST PRINTONLY 
ON TABLE PCHOLD FORMAT XML 
END

Example: Retrieving Chained Variable Values With Caching Enabled

In the following example, caching is enabled, so a single procedure is used to populate the controls. 

TABLE FILE GGSALES 
PRINT DST.REGION DST.ST DST.CITY 
BY REGION 
BY ST 
BY CITY 
ON TABLE SET HOLDLIST PRINTONLY 
ON TABLE PCHOLD FORMAT XML 
END

The XML output is:

- <table>
 - <tr linetype="data" linenum="1">
     <td colnum="c0">Midwest</td>
     <td colnum="c1">IL</td>
     <td colnum="c2">Chicago</td>
     <td colnum="c3">Midwest</td>
     <td colnum="c4">IL</td>
     <td colnum="c5">Chicago</td>
   </tr>

Automatically Populating Fields With Dynamic Values

When the name of a dynamic parameter matches a corresponding field name in a data source, the HTML canvas automatically populates the field name values for the parameter.

The data source is populated by a default based on the first data source specified by a TABLE FILE or GRAPH FILE command. The data source field is populated for the Value and Display fields in the Settings panel of the Parameters tab (when Dynamic is selected as the Data type). This generates a layout report that is ready to run as long as the parameter names match the field names.

Example: Automatically Populating Fields With Dynamic Parameter Values

When the following report request is called from the HTML canvas with a push button control, the Settings panel for the PRODUCT parameter on the Parameters tab is automatically populated to dynamically retrieve the values of the PRODUCT field. 

TABLE FILE GGSALES 
SUM UNITS 
BY PRODUCT WHERE ( PRODUCT EQ '&PRODUCT.Product:.' ); 
END

Creating a Static or Dynamic Parameter Value List

How to:

When creating a static or dynamic list of values, you may add an ALL value to the list of values and/or send the display value in a parameter.

The ALL feature allows developers to automatically add an ALL value to a list of values. An ALL value does the following:

When using a Dynamic or Analytic Document Data type, you may enter the value(s) to be selected as the default value whenever the procedure is run.

Note: You may also enter the selected value when adding a new unbound parameter on the Parameters tab.

Procedure: How to Send the Display Value for Static and Dynamic Controls

From the HTML canvas, you may send the display value, rather than the actual data, to the parameter. The display value can also be used for headings and footings in the report output.

  1. From the HTML canvas, import or create a report that contains a parameter.

    When importing a report with parameters, the New Parameters dialog box appears prompting you to create the control type.

    The report and control is added to the HTML canvas.

  2. To send the display value for the parameter selection, select the control object (for example, select listboxn) in the Design view and click the Parameters tab.
  3. Navigate to the Settings panel.

    Note: The options available in the Settings panel vary, depending on the type of values (static or dynamic) you are creating.

  4. For a static list of values, the Value, Display, and Selected columns appear on the Settings panel.
    • In the Value column, enter the value to be passed to the control.
    • In the Display column, enter the text that represents the static parameter value in the control the user views.
    • In the Selected column, check the box for the value you want to be selected by default. More than one value can be selected.

      Repeat these steps until the list contains all of the values you want to include.

    • Select Send display value.

      Tip: You may also update the display values from the Variable Editor dialog box in the Report canvas.

    • Optionally, you may select values and click the Delete button to eliminate any values, and use the up and down arrows to rearrange the order of the values.
    • Click the Design tab to view the display values in the control object of the HTML canvas.
  5. For a dynamic list of values, the Value from field and the Display from field appear on the Settings panel.
    • Add the request to the Requests & Data sources panel.
    • Select Explicit (Requests Panel).
    • Select the procedure from the Requests drop-down list.
    • Click the ellipsis button from the Value field.

      The Object Inspector opens with the field names from the selected Master File.

    • Double-click a field name to add it to the Value field.

      The selected field is automatically added to the Display field and the source code for the default procedure appears.

    • Optionally, you may click the Display field ellipsis button to select a different field name for the Display field.
    • Optionally, select Add "All" option to automatically add an all value to a list of parameter values.
    • Optionally, select Add 'No selection' option to optimize performance by populating a chain one control at a time instead of all the controls when the page initially loads.
    • Select Send display value.

      When Send display value is selected, the &Variable gets the display value, instead of the actual value.

  6. Optionally, you may add a heading to the report to show the display value. Double-click the report from the HTML canvas to open and edit the report.

    The report opens in the Report canvas.

  7. Add &Variable_TEXT to the report heading or footing.

    Note: If the report procedure uses it, &Variable_TEXT will always be passed, regardless of if Send display value is selected.

    The heading as Display Value: &STCD_TEXT, where Store Code (STCD) is the variable name.

    Tip: This is different from adding the actual value from the data source, where clicking the variable name would add <STCD to the report heading.

  8. Save and close the report to return the HTML canvas.

    When you create the Text variable (&Variable_TEXT), you are not prompted to set a control type for this variable when returning to the HTML canvas, as no control type is needed.

  9. Run the HTML page.
  10. Select the parameter for the report and run the report.

    The display value is shown in the report heading.

    Note: The HTML canvas passes &Variable_TEXT if the report procedure uses it, regardless of whether the send display value check box is checked or unchecked.

Procedure: How to Use Procedure Names as Values

The Values are procedures names option lets you populate a control with procedure names or HTML file names. When that procedure name is clicked, the procedure executes.

  1. Create an HTML page that contains a list box, a push button, and a report.

    Note: In this procedure a list box is used, however, the following controls are also able to use the Values are procedures names option: double list, drop-down, radio button, and check box.

  2. Select the list box to bring up the Settings panel.

    Note: If the Settings panel does not open, select View and click Settings.

  3. Select Static as the Data type.
  4. At the bottom of the Settings panel, select Values are procedures/html names.
  5. Click the New button and select procedures from your directory.

    Note: You can add multiple procedure names to the Settings panel by multi-selecting procedures while in the Open File dialog box.

  6. Once the procedures have been added to the Settings panel, edit the display names of the procedures by double-clicking the display contents if they are not already highlighted.
  7. Right-click the button you created and click Create Hyperlink.

    The Hyperlink Properties dialog box opens.

  8. Create a hyperlink that opens a selected procedure from a control in the report frame created earlier.
    1. For the Action, select Procedures from control from the drop-down list.

      This option coincides with the Values are procedures names option found in the Settings panel. This option will point to an entire procedure for the hyperlink, rather than a simple value. This option is only available when a control on the HTML page is using the Values are procedures names option.

    2. Select listbox1 as the Source.

      The source can be different if you use a different control. For example, combobox1, customselect1, radio1, or checkbox1.

    3. Select Frame as the Target Type.

      You could also select New Window as the target if you wanted the procedure to open in a new window.

    4. Select report1 as the Target/Template Name.
  9. Run the page.
  10. Select the procedure from the list box and click the button.

    The report is run.

Procedure: How to Use Selected Values as the Default Value

When using a Dynamic or Analytic Document Data type, you may enter the values to be selected as the default value whenever the procedure is run.

If you import a procedure (.fex) that has a dynamic prompt value then the input box is populated with values retrieved from the data source. If the selected value is available in the data source, the values are selected by default. If the selected value is not available in the data source, then the value(s) that you entered are ignored and the first value retrieved from the data source is selected.

  1. Create or import a report that contains a parameter value.

    The report and control is added to the HTML canvas.

  2. To enter the selected value to be used as the default value, select the control object (for example, select listboxn) in the Design view and click the Parameters view tab.

    The Settings panel opens.

    Note: The options available in the Settings panel vary, depending on the type of values (static or dynamic) you are creating.

  3. For a dynamic list of values, the Value from field and the Display from field appear on the Settings panel.
    1. If using a default procedure to supply dynamic values, follow the steps below.
      • Select Default.
      • Click the ellipsis button adjacent to the Data Source field.

        The Open File dialog box appears.

      • Select the Master File name and click OK.
      • Click the ellipsis button adjacent to the Value from field.

        The Object Inspector opens with the field names from the selected Master File.

      • Double-click a field name to add it to the Value from field.

        The selected field is automatically added to the Display from field and the source code for the default procedure appears.

      • Optionally, you may click the Display from field ellipsis button to select a different field name for the Display from field.
      • Optionally, select Add "All" option to automatically add an all value to a list of parameter values.
      • Optionally, select Add 'No selection' option to optimize performance by populating a chain one control at a time instead of all the controls when the page initially loads.
      • Enter the exact parameter value in the Selected Value input field, as it appears in the data source.

        Parameter values are case sensitive.

      • Optionally, you may enter more than one value by using a semicolon (;) between the values. For example, CA;GA.

        You may enter selected values with a semicolon or a comma. Additionally, you may also have embedded commas or semicolons in the data values. If you have these embedded characters, you must enclose all of the values in the input area in double quotation marks ("). For example:

        ENGLAND;ITALY

        ENGLAND,ITALY

        “ENGLAND”,”IT,ALY”

        Note that even though one value in the last set has the embedded comma, both values need to be enclosed in double quotation marks (").

    2. If using an explicit procedure to supply dynamic values, follow the steps below.
      • Select Explicit (Requests Panel).
      • Select the procedure from the Requests drop-down list.

        The parameter names from the procedure are automatically added to the Value from field and Display from field, and the source code for the explicit procedure appears.

      • Optionally, you may click the Value from field and Display from field ellipsis button to select a different field name or to type the field name manually.

        Note: Only the parameter names from the explicit procedure will be available for selection.

      • Optionally, select Add "All" option to automatically add an all value to a list of parameter values.
      • Enter the exact parameter value in the Selected Value input field, as it appears in the data source.

        Parameter values are case-sensitive.

      • Optionally, you may enter more than one value by using a semicolon (;) between the values. For example, CA;GA.

        You may enter selected values with a semicolon (;) or a comma (,). Additionally, you may also have embedded commas or semicolons in the data values. If you have these embedded characters, you must enclose all of the values in the input area in double quotation marks ("). For example:

        ENGLAND;ITALY

        ENGLAND,ITALY

        “ENGLAND”,”IT,ALY”

        Note that even though one value in the last set has the embedded comma, both values need to be enclosed in double quotation marks (").

  4. For an Analytic Document list of values, the Available Analytic Documents, Menu Option Types, and Common Columns appear on the Settings panel.
    • Select one or more Analytic Documents from the list of Available Analytic Documents. The selected report will be bound to the Analytic Document control in the layout.

      When an Analytic Document is selected, the Refresh for Analytic Documents option, in the Settings panel, is enabled, by default.

    • Select the Menu Options Types for the Analytic Document control to sort, filter, list or select columns, and/or change presentation styles of the bound Analytic Document and the associated report and graph objects synchronized to the Analytic Document.
    • Optionally, select Add "All" option to automatically add an all value to a list of parameter values.
    • Enter the exact parameter value in the Selected Value input field, as it appears in the data source.

      Parameter values are case-sensitive.

    • Optionally, you may enter more than one value by using a semicolon between the values. For example, CA;GA.

      You may enter selected values with a semicolon or a comma. Additionally, you may also have embedded commas (,) or semicolons (;) in the data values. If you have these embedded characters, you must enclose all of the values in the input area in double quotation marks ("). For example:

      ENGLAND;ITALY

      ENGLAND,ITALY

      “ENGLAND”,”IT,ALY”

      Note that even though one value in the last set has the embedded comma, both values need to be enclosed in double quotation marks (").

  5. For a single-select unbound parameter, the Selected Value input field appears on the Settings panel.
    • Enter the exact parameter value in the Selected Value input field, as it appears in the data source.

      Parameter values are case sensitive.

    • Optionally, you may enter more than one value by using a semicolon between the values. For example, CA;GA.

      You may enter selected values with a semicolon or a comma. Additionally, you may also have embedded commas or semicolons in the data values. If you have these embedded characters, you must enclose all of the values in the input area in double quotation marks. For example:

      ENGLAND;ITALY

      ENGLAND,ITALY

      “ENGLAND”,”IT,ALY”

      Note that even though one value in the last set has the embedded comma, both values need to be enclosed in double quotation marks (").

    Even though it is a Single select parameter, multiple values are specified and selected.

  6. Click the Run button to run the report with the selected value parameters.

    The report output appears.

    The selected value, if available from the data source, is automatically selected (highlighted) in the parameter list.

    If the selected value is not available in the report results, then the value that you entered is ignored and the first value retrieved from the data source is shown.

Parameterizing Properties in the Properties Panel

How to:

You can parameterize properties in the Properties panel for all objects in an HTML page. This enables you to add values to amper variables and pass these variables to the corresponding property settings in App Studio so the HTML page behaves a specific way.

You can pass values using the !IBI.AMP.VarName variable or a URL call.

Procedure: How to Parameterize Properties in the Properties Panel

The following procedure shows how to parameterize properties in the Properties panel, using the !IBI.AMP.VarName variable and a procedure call to the HTML page.

  1. From the Environments tree, right-click a folder, point to New, and click HTML/Document to create a new HTML page.
  2. On the Components tab, in the Generic Elements group, click Button and draw a button on the canvas.
  3. On the Controls tab, click the Tree drop-down arrow, and select Multi source Tree to draw the control on the canvas.
  4. On the Requests & Data Sources panel, click the New drop-down arrow, and then click Add Data Source.
  5. Navigate to the ibisamp folder and select a Master File. For example, movies.mas.
  6. Select the button component on the HTML canvas.
  7. On the Properties panel:
    • Next to the Color property, type !IBI.AMP.MYCOLOR;.
    • Next to the Background-color property, type !IBI.AMP.BCOLOR;.

    The Properties panel with Color and Background-color values are shown in the following image.

  8. Select the Multi source Tree control on the HTML canvas. On the Properties panel, next to the Direction of text property, type !IBI.AMP.DIRECTION;.

    The Properties panel with the Direction of text value is shown in the following image.

  9. On the Settings panel, click the ellipsis for Value from and double-click Movie, as shown in the following image.
  10. Save and close the HTML page.
  11. From the Environments tree, right-click an application folder (for example, baseapp), point to New, and then click Procedure.
  12. Type the following code:
    -DEFAULT &DIRECTION='rtl';
-DEFAULT &MYCOLOR='RED';
-DEFAULT &BCOLOR='BLUE';
  13. From the Procedure View panel, right-click Comment, point to New, point to HtmlForm, and then click Referenced.
  14. Double-click the HTML page to reference.
  15. Close the procedure and save the file.
  16. From the Environments tree, right-click the procedure, and click Run.

    The following screen displays with the specified default values.

  17. Click the Run icon.

    Notice that the background color is blue, the button text is red, and the movie titles are right-justified.

  18. Click the Show filter panel icon, as shown in the following image.
  19. Change the direction to ltr (left to right) and the background color to yellow, as shown in the following image.
  20. Click the Run icon. Notice that the background color for the button is yellow and the movie titles are left-justified, as shown in the following image.

Note: You can also parameterize properties in the Properties panel using a URL in a browser. For example: 

http://host:port/app_directory/htmfilename.htm?bcolor=red

In this example:

  • &Varname (for example, &bcolor) must be added to the Properties panel for the parameter value.
  • bcolor refers to the background color.