Building the Syntax Template

The syntax template specifies the command syntax that will be generated by the custom dialog. A single custom dialog can generate command syntax for any number of built-in IBM® SPSS® Statistics commands or extension commands.

The syntax template can consist of static text that is always generated and control identifiers that are replaced at run time with the values of the associated custom dialog controls. For example, command names and subcommand specifications that don't depend on user input would be static text. The set of variables that is specified in a target list, however, would be represented with the control identifier for the target list control.

To Build the Syntax Template

  1. For static command syntax that does not depend on user-specified values, enter the syntax as you would in the Syntax Editor. The Syntax Template supports the auto-completion and color coding features of the Syntax Editor. See the topic Using the Syntax Editor for more information.
  2. Add control identifiers of the form %%Identifier%% at the locations where you want to insert command syntax that is generated by controls, where Identifier is the value of the Identifier property for the control.
    • You can insert a control identifier by selecting a row in the table of identifiers, right-clicking and selecting Add to syntax template. You can also insert a control identifier by right-clicking a control on the canvas and selecting Add to syntax template.
    • You can also select from a list of available control identifiers by pressing Ctrl+Spacebar. The list contains the control identifiers followed by the items available with the syntax auto-completion feature.
    If you manually enter identifiers, retain any spaces, since all spaces in identifiers are significant.

    At run time, and for all controls other than check boxes and check box groups, each identifier is replaced with the current value of the Syntax property of the associated control. For check boxes and check box groups, the identifier is replaced by the current value of the Checked Syntax or Unchecked Syntax property of the associated control, depending on the current state of the control--checked or unchecked. See the topic Control types for more information.

Note: The syntax that is generated at run-time automatically includes a command terminator (period) as the very last character if one is not present.

Example: Including Run-time Values in the Syntax Template

Consider a simplified version of the Frequencies dialog that contains only a source list control and a target list control, and generates command syntax of the following form:

FREQUENCIES VARIABLES=var1 var2...
  /FORMAT = NOTABLE
  /BARCHART.

The syntax template to generate this syntax might look like:

FREQUENCIES VARIABLES=%%target_list%%
  /FORMAT = NOTABLE
  /BARCHART.
  • %%target_list%% is the value of the Identifier property for the target list control. At run time it will be replaced by the current value of the Syntax property of the control.
  • Defining the Syntax property of the target list control to be %%ThisValue%% specifies that at run time, the current value of the property will be the value of the control, which is the set of variables in the target list.

Example: Including Command Syntax from Container Controls

Building on the previous example, consider adding a Statistics sub-dialog that contains a single group of check boxes that allow a user to specify mean, standard deviation, minimum, and maximum. Assume that the check boxes are contained in an item group control.

An example of the generated command syntax would be:

FREQUENCIES VARIABLES=var1 var2...
  /FORMAT = NOTABLE 
  /STATISTICS MEAN STDDEV
  /BARCHART.

The syntax template to generate this syntax might look like:

FREQUENCIES VARIABLES=%%target_list%%
  /FORMAT = NOTABLE 
  %%stats_group%%
  /BARCHART.
  • %%target_list%% is the value of the Identifier property for the target list control and %%stats_group%% is the value of the Identifier property for the item group control.

The following definitions illustrate one way to specify the Syntax properties of the item group and the check boxes that are contained within it to generate the correct result. The Syntax property of the target list would be set to %%ThisValue%%, as described in the previous example.

Syntax property of item group: /STATISTICS %%ThisValue%%

Checked Syntax property of mean check box: MEAN

Checked Syntax property of stddev check box: STDDEV

Checked Syntax property of min check box: MINIMUM

Checked Syntax property of max check box: MAXIMUM

At run time, %%stats_group%% will be replaced by the current value of the Syntax property for the item group control. Specifically, %%ThisValue%% will be replaced by a blank-separated list of the values of the Checked or Unchecked Syntax property of each check box, depending on its state--checked or unchecked. Since we only specified values for the Checked Syntax property, only checked boxes will contribute to %%ThisValue%%. For example, if the user checks the mean and standard deviation boxes, the run time value of the Syntax property for the item group will be /STATISTICS MEAN STDDEV.

If no boxes are checked, then the Syntax property for the item group control will be empty, and the generated command syntax will not contain any reference to %%stats_group%%. This might or might not be desirable. For example, even with no boxes checked you might still want to generate the STATISTICS subcommand. This can be accomplished by referencing the identifiers for the check boxes directly in the syntax template, as in:

FREQUENCIES VARIABLES=%%target_list%%
  /FORMAT = NOTABLE 
  /STATISTICS %%stats_mean%% %%stats_stddev%% %%stats_min%% %%stats_max%%
  /BARCHART.