Smart Controls

Defining Smart Controls

Creating Smart Controls consists of two main components: a Query List definition and a Smart Control (or a Smart Chart) definition. Furthermore, creating Smart Charts requires one additional component, a Query AutoChart definition, before the Smart Chart definition can be created.

1.	Create a Query List Definition:	To specify the details and format of the dataset to be loaded
2.	Create a Query AutoChart Definition:	*(For Smart Charts Only)* To define a NOMADS AutoChart based on the columns of a Query List definition
3.	Create a Smart Control (or Smart Chart) Definition:	To associate the query and to set up optional Trigger Variables, Conditional Trigger Test and Load Logic

Creating a Query List Definition

Smart Controls use a Query object definition to determine the content of the Smart Control in terms of file selection, column definition and selection criteria. A Query List object consists of a query-like definition that is used exclusively by Smart Controls to auto-load a list of records from a data file or database table. This type of definition is a subset of the Standard Query with header information containing the file and key information only and the column definitions having limited options.

You can also use a Standard Query definition for Smart Controls (with the exception of the Smart Multi-Line); however, the control will only use this same subset of information and ignores the information in the other fields.

See Query Header for information on Standard Query header options.

To create a Query List Definition:

In NOMADS Library Object Selection, click the Query toolbar button (if using Toolbar View) or select Objects > Query Object from the menu bar.

Type a new Name for the Query List definition. When prompted for Query Type, select Query List. Click OK, which brings up the Query Definition - File information window for defining the Query List header information.

Alternatively, a new Query List can be defined in the Smart Control Definition window. To do this, type a new Panel name for the Query List definition. Click the Define button, which brings up the Query Definition - File information window for defining the Query List header information.

The Query Definition - File information window consists of the following options:

Data Source

Options for defining the query's data source:

Database	If this check box is selected, the information to be displayed will be from an external database table. If not selected *(Default)*, the information is assumed to be from a PxPlus data file.
Database Type	*(Available when Database check box is selected)* Select from the following types: ODBC, ODBC (Local), Oracle, Oracle (Local), DB2, DB2 (Local), MySQL, MySQL (Local), ADO, ADO (Local).
Data Source Name	*(Available when Database check box is selected)* Enter the database name (Fixed value or Expression).
Connect Option	*(Available when Database check box is selected)* Connection options to be appended to an OPEN statement when opening the database.

File/Table

Name of the primary file or database table to be displayed in the query (Fixed value/Expression).

The Query system provides a drop-down list of all files in the PxPlus data dictionary (providex.ddf) or all tables in the specified database. If accessing a database, you must select a table name from the drop-down list. For PxPlus data files, select an existing file or table by using one of the following methods:

Type the physical file or table name.
Click the Query Table View button (magnifying glass) for a tree view of table names by Group. For information on creating a filter to locate a specific table name, see Filtering the Table Names Lookup.
Click the Browse button (file folder) to look through the directory structure to find a file or table name.

If you are not maintaining the data file in the data dictionary, then you must manually define the data fields. Data can have internal or external keys or can be sort files.

Key Information

Options for defining the key information:

Sort By	Select the key by which a PxPlus data file is to be sorted. At run time, you can override this setting by loading the %NOMADS'Query_Kno variable with an alternate key number.
Smart Key (Multi-lines Only)	An expression consisting of any combination of trigger variables from the panel, global variables, and/or literal values that may be concatenated to create the key value to read the record to attain the required data. *Example:* %COMPANY_CODE$+CLIENT_CODE$

Other Options

Static Columns (Grids Only)

Number of columns in a Grid that remain fixed when the display is shifted horizontally.

Row Highlight

Add (Edit) row display option

Click the link to invoke the Row Display Option window that is used to assign visual attributes, such as bold text, text color or highlight color, to a row based on specified conditions.

(The Add (Edit) row display option was added in PxPlus 2021.)

When you have finished entering the Query List header information, click OK, which brings up the Query List Definition window for defining the Query List contents.

This window is identical to the Query Definition window that is used to define a Standard Query where you can set up link files, define columns, edit file information and set up selection parameters. Query Security can also be set up for the Query List.

However, the query selection criteria for a Query List definition (using the Filter toolbar button) is slightly different from the Query Selection Criteria for a Standard Query. The names and values of the trigger variables are available to the Query Load logic; therefore, these variables may be used to define Prefix and Range values as opposed to the Load logic of a Standard Query that uses global variables for these values. In addition, the Prefix and Range values can be applied to the Sort By key rather than just the primary key.

The trigger variables are also available in an identical set of variables with a _VAR. prefix, which allows you to build selection tests that compare the external trigger variables with the _VAR. prefix to variables in the Query definition with the same name, e.g. _VAR.GLAcct$=GLAcct$.

The Choose initial sort column option is available for Smart Report View List Boxes and Grids. However, unlike a query where the sort column is implemented only on the initial load, with Smart Controls, the sort column is implemented each time the control is reloaded.

(The use of _VAR. aliases for variables passed to the *winlist logic was added in PxPlus 2021.)
(The Choose initial sort column option was added in PxPlus 2022.)

When you have finished entering this information, click the Save toolbar button to save the current Query List definition.

Creating a Query AutoChart Definition

Note:
(Smart Charts) A Query AutoChart definition is required before the Smart Chart Definition can be created.

Create a NOMADS AutoChart based on the columns in a Query List definition:

In NOMADS Library Object Selection, select the existing Query List object that will be used for creating the AutoChart.

The Query List Definition window displays. Click the Define Chart toolbar button.

The Welcome panel of the Chart Wizard displays. The Chart Wizard walks you through the steps for creating and saving an AutoChart.

Creating a Smart Control (or Smart Chart) Definition

The Smart Control Definition window is used to turn on the Smart Load logic and assign a Query to the target control (List Box, Drop Box, Grid, Multi-Line or Chart) to supply the list content and formatting information. It also allows you to optionally define load-triggering criteria (trigger variables and loading conditions) for the control, as well as specify Pre- and Post-Load logic as desired.

Note:
(Multi-Lines Only) Smart Load logic is not compatible with EZ Load logic.

To invoke the Smart Control Definition window:

In the NOMADS Panel Designer, access the Properties window for the target List Box, Drop Box, Grid, Multi-Line or Chart control.

Locate the Smart Load button:

• For List Boxes, Drop Boxes, Grids and Multi-Lines, the Smart Load button is located on the Attributes tab (using the Folder Style version of the NOMADS designer).

• For Charts, the Smart Load button is located in the upper right corner of the main panel.

Click the Smart Load button:

• When defining Smart List Boxes, Drop Boxes, Grids and Multi-Lines, the Smart Control Definition window is displayed.

• When defining Smart Charts, the Smart Chart Definition window is displayed, which includes additional Chart Selection options.

Note:
Smart Charts are available only if Query+ queries are being used, as Classic queries do not support charting.

The Smart Control Definition window consists of the following options:

Use Smart Load logic

Select this check box to enable Smart Load logic for the control. (By default, it is not selected.)

Query Selection

(For List Boxes, Drop Boxes, Grids and Multi-Lines - Available when Use Smart Load logic check box is selected)

The query assigned to a Smart Control must be a Query List or a Standard Query definition.

If a query has already been assigned on the Query tab of the Properties dialogue, it will be loaded as the Query Selection in the Smart Control Definition. (See Important Note.) Alternately, when a query is selected in the Smart Control Definition, it is reflected on the Query tab of the Properties dialogue. The query can be assigned in either location.

Important Note:
If a query has been assigned on the Query tab of the Properties dialogue, it must be a Panel Query Type. If it is an alternate Query Type (Query Program, Non-Query Logic, Spinner Controls, Calendar), clicking the Smart Load button will display a message, prompting you to clear the current query associated with the Smart Load before continuing.

Select Query	Button that invokes the Select a Query Definition window. This window presents a tree-view structure that lists Query Lists and Queries that exist at the current display level and lower, arranged by directory, screen library and query. Select a Query by clicking on the Query item or one of its columns. When a Query List or Query is selected, the Library and Query Definition input fields (described below) are automatically populated. A Query definition can also be selected by entering the Library and Query Definition input fields manually, as described below. (The Select Query button was added in PxPlus 2020.)
Library	Enter the path to the library containing the query definition. Click the drop-down arrow to invoke a list of recently used libraries. The Browse button allows you to browse the directory to locate the library. Be sure to *use the simplest form of the path* for your application. Note: The Library name may be a specific or generic reference. See Cascading Language Suffixes.
Panel	Name of the query definition to invoke. Click the drop-down arrow for a list of all query panels in the selected library. If the query has not yet been defined, enter a new name and then click the Define button to create it. Note: When entering a new name, valid characters are: letters (A-Z, a-z); numbers (0-9); ~ (tilde); @ (at symbol); . (period); $ (dollar sign); _ (underscore); - (dash); + (plus sign). If an invalid character is used, a message will display.
Define	Button that launches a query definition window using the Panel name to either create a new or edit an existing query definition. If creating a new query definition, it will default to a Query List type of definition.

Chart Selection

(For Charts Only - Available when Use Smart Load logic check box is selected)

Select Chart	Button that invokes the Select a Chart Definition window. This window presents a tree-view structure that lists all the public query AutoChart definitions that exist at the current display level and lower, arranged by directory, screen library, query and chart definition. When a chart definition is selected, the Library, Panel and Chart Name input fields in the Smart Chart Definition window are automatically populated. A chart can also be selected by entering the Library, Panel and Chart Name input fields manually.
Library	Enter the path to the library containing the chart definition. Click the drop-down arrow to invoke a list of recently used libraries. The Browse button allows you to browse the directory to locate the library. Be sure to *use the simplest form of the path* for your application. Note: The Library name may be a specific or generic reference. See Cascading Language Suffixes.
Panel	Name of the query definition to invoke. Click the drop-down arrow for a list of all query panels in the selected library. If the query has not yet been defined, enter a new name and then click the Define button to create it. Note: When entering a new name, valid characters are: letters (A-Z, a-z); numbers (0-9); ~ (tilde); @ (at symbol); . (period); $ (dollar sign); _ (underscore); - (dash); + (plus sign). If an invalid character is used, a message will display.
Define	Button (next to Panel input field) that launches a query definition window using the Panel name to either create a new or edit an existing query definition. If creating a new query definition, it will default to a Query List type of definition.
Chart Name	Name of the Query+ AutoChart definition to be used to load the chart. Click the drop-down arrow for a list of all public chart definitions that belong to the selected query. The name of a chart definition can also be entered manually.
Define	Button (next to Chart Name input field) that launches the Chart Wizard based on the selected query panel to either create a new or edit an existing chart definition. See Run-Time Query Charts.
Ignore Query chart format	By default, the chart format and titles are derived from the Query+ AutoChart definition. Select the Ignore Query chart format check box to use the format and titles from the chart control definition.

(Chart Selection was added in PxPlus 2019.)

Trigger Variables and Controls

Trigger variables serve two purposes:

They initiate the Load logic. If trigger variables are used, any change in the value of a trigger variable will cause the Smart Control to be reloaded after the trigger control's On Change logic has been executed (provided that the conditional trigger test is satisfied as well). If no trigger variables are defined, the Smart-enabled control will be loaded whenever a panel is drawn. When there is more than one folder on a main panel, the control is reloaded each time you switch to a folder with a Smart Control.

The trigger variables are made available to the special Smart Control Load logic. This means that you can use these variables in the Query Selection Definition of the associated query object to filter the records to be displayed.

The trigger variables are also available in an identical set of variables with a _VAR. prefix, which allows you to build selection tests that compare external variables with the _VAR. prefix to variables in the Query definition with the same name, e.g. _VAR.GLAcct$=GLAcct$.

(The use of _VAR. aliases for variables passed to the *winlist logic was added in PxPlus 2021.)

The following options are available when a query is assigned for the Query Selection:

Variables	Enter the name of a variable from your PxPlus application. Click the Add Variable button to add the variable to the Selected Triggers list.
Controls	Lists all available controls in the current panel. Click the Add Control button to move a selected control to the Selected Triggers list.
Selected Triggers	Lists variables and controls currently selected to be used in the trigger criteria. To remove a selected item from this list, click the Remove button.

Conditional Trigger Test

(Not Applicable for Smart Multi-Lines)

Additional test to be imposed on load-triggering criteria. If defined, the Conditional Trigger Test must be satisfied for the Load logic to be triggered.

Text to Display if Read Fails

(For Smart Multi-Lines Only - Available when Query Selection is entered)

Text to load into the Multi-Line when the query fails to retrieve data. Can be a Fixed value, string Expression or Message Library entry (see Message Library Maintenance). If left blank, spaces will be loaded.

Options

Clear control when all Triggers are null

If this check box is selected, the Smart control being defined will be cleared whenever all the variables/controls in the Selected Triggers list are null.

(The Clear control when all Triggers are null check box was added in PxPlus 2021.)

Hide control during load

(Not Applicable for Smart Multi-Lines)

If this check box is selected, the control is hidden while it is being loaded. Loading is faster and cleaner in appearance, especially when displaying grids with graphical row/column displays.

(The Hide control during load check box was added in PxPlus 2021 Update 1.)

Suppress graphic row/column displays

(For Report View List Boxes and Grids Only)

If the query assigned to the Smart control uses Row Highlight or Column Display options such as bold text, foreground and background colors, images or percent bars, the graphic displays can be suppressed by selecting this check box.

Default is On for Grids and Off for Report View List Boxes.

(The Suppress graphic row/column displays check box was added in PxPlus 2021 Update 1.)

Load Logic

Pre-Load Logic	Optional logic to be processed prior to loading. Available processes are Ignore, Perform, Call, Execute. See Events Logic.
Post-Load Logic	Optional logic to be processed after loading. Available processes are Ignore, Perform, Call, Execute. See Events Logic.

Note:
Smart Multi-Lines are intended for information as display only. Typically, this type of field might be used to look up and display a client name beside the input field where the client code is entered. As display-only fields, it is common practice to turn Off the Tab Stop option and turn On the Locked and Borderless attributes for the Multi-Line.

As an alternative to Smart Multi-Lines, EZ Load Multi-Lines can be used.

Smart Controls

Creating a Query List Definition

Creating a Query AutoChart Definition

Note:
(Smart Charts) A Query AutoChart definition is required before the Smart Chart Definition can be created.

Creating a Smart Control (or Smart Chart) Definition

Note:
(Multi-Lines Only) Smart Load logic is not compatible with EZ Load logic.

Note:
Smart Charts are available only if Query+ queries are being used, as Classic queries do not support charting.

Note:
The Library name may be a specific or generic reference. See Cascading Language Suffixes.

Note:
When entering a new name, valid characters are: letters (A-Z, a-z); numbers (0-9); ~ (tilde); @ (at symbol); . (period); $ (dollar sign); _ (underscore); - (dash); + (plus sign). If an invalid character is used, a message will display.

Note:
The Library name may be a specific or generic reference. See Cascading Language Suffixes.

Note:
When entering a new name, valid characters are: letters (A-Z, a-z); numbers (0-9); ~ (tilde); @ (at symbol); . (period); $ (dollar sign); _ (underscore); - (dash); + (plus sign). If an invalid character is used, a message will display.

See Also

Smart Controls

Creating a Query List Definition

Creating a Query AutoChart Definition

Note:(Smart Charts) A Query AutoChart definition is required before the Smart Chart Definition can be created.

Creating a Smart Control (or Smart Chart) Definition

Note:(Multi-Lines Only) Smart Load logic is not compatible with EZ Load logic.

Note: Smart Charts are available only if Query+ queries are being used, as Classic queries do not support charting.

Note: The Library name may be a specific or generic reference. See Cascading Language Suffixes.

Note: When entering a new name, valid characters are: letters (A-Z, a-z); numbers (0-9); ~ (tilde); @ (at symbol); . (period); $ (dollar sign); _ (underscore); - (dash); + (plus sign). If an invalid character is used, a message will display.

Note: The Library name may be a specific or generic reference. See Cascading Language Suffixes.

Note: When entering a new name, valid characters are: letters (A-Z, a-z); numbers (0-9); ~ (tilde); @ (at symbol); . (period); $ (dollar sign); _ (underscore); - (dash); + (plus sign). If an invalid character is used, a message will display.

See Also

Note:
(Smart Charts) A Query AutoChart definition is required before the Smart Chart Definition can be created.

Note:
(Multi-Lines Only) Smart Load logic is not compatible with EZ Load logic.

Note:
Smart Charts are available only if Query+ queries are being used, as Classic queries do not support charting.

Note:
The Library name may be a specific or generic reference. See Cascading Language Suffixes.

Note:
When entering a new name, valid characters are: letters (A-Z, a-z); numbers (0-9); ~ (tilde); @ (at symbol); . (period); $ (dollar sign); _ (underscore); - (dash); + (plus sign). If an invalid character is used, a message will display.

Note:
The Library name may be a specific or generic reference. See Cascading Language Suffixes.

Note:
When entering a new name, valid characters are: letters (A-Z, a-z); numbers (0-9); ~ (tilde); @ (at symbol); . (period); $ (dollar sign); _ (underscore); - (dash); + (plus sign). If an invalid character is used, a message will display.