Working with the Options Element

About the Options Element

The Options element identifies the options that are required in order to run the task. The Option tag, which is the only child of the Options element, describes the assigned option.

Attribute	Description
`name`	specifies the name assigned to this option.
`defaultValue`	specifies the initial value for the option.
`inputType`	specifies the input control for this option. Here are the valid values: `checkbox` `color` `combobox` `datepicker` `distinct` `inputtext` `modelbuilder` `multientry` `numstepper` `numbertext` `radio` `select` `slider` `string` `textbox` `validationtext` For more information, see Supported Input Types.
`indent`	specifies the indention for this option in the task interface. Here are the valid values: `1` – minimal indention (about 17px) `2` – average indention (about 34px) `3` – maximum indention (about 51px)
`returnValue`	applies to strings that are used by input types (such as `combobox` and `select`) where the user has a selection of choices. If the `returnValue` attribute is specified in other contexts, this attribute is ignored. For more information, see Specifying a Return Value Using the returnValue Attribute.

Supported Input Types

checkbox

This input type does not have additional attributes. The valid values for checkbox are 0 (unchecked) and 1 (checked).

The code in the sample task definition creates two check boxes.

<Option name="GROUP1" inputType="string">CHECK BOXES</Option>
<Option name="chkCheck" defaultValue=1" inputType="checkbox">
   Enable another field</Option>
<Option name="chkEXAMPLE" defaultValue="0" inputType="checkbox">
   Check box</Option>

Here is an example of a check box control in the user interface:

Example of Check Boxes in the Sample Task Definition

color

This input type does not have additional attributes. Here is an example from the sample task definition:

<Option name="colorEXAMPLE defaultValue="gray" 
   inputType="color">Choose Color</Option>

Here is an example of a color control in the user interface:

combobox

This input type has one attribute.

Attribute	Description
`width`	specifies the width of the control. This value can be in percent (%), em, or px. By default, SAS Studio sizes the control based on the available width and content.

The code in the sample task definition creates a combination box called Drop-down list. This list contains three options: Value 1, Value 2, and Value 3.

<Option name="comboEXAMPLE" defaultValue="value2" inputType="combobox">
   Drop-down list:</Option>
<Option name="value1" inputType="string">Value 1</Option>
<Option name="value2" inputType="string">Value 2</Option>
<Option name="value3" inputType="string">Value 3</Option>

Here is an example of a combobox control in the user interface:

datepicker

This input type has these attributes:

Attribute	Description
`format`	specifies the format of the date value. You can use any valid SAS date format. If no format attribute is provided, it defaults to mmddyys8. (12/24/93).
`required`	specifies whether a date is required. By default, no date is required.
`width`	specifies the width of the control. This value can be in percent (%), em, or px. By default, SAS Studio sizes the control based on the available width and content.

If you specify the defaultValue attribute for this input type, the value must be in ISO8601 format (yyyy-mm-dd).

This code creates a datepicker control called Vacation Day that has a default value of 6/30/2014.

<Option name="myDate" defaultValue="2014-06-30" inputType="datepicker"
      format="mmddyys8.">Vacation Day</Option>

Here is an example of a datepicker control in the user interface:

distinct

This input type has these attributes:

Attribute	Description
`source`	specifies the role to use to get the distinct values. The `maxVars` control for the role must be set to 1. In other words, users can assign only one variable to this role.
`max`	specifies the maximum number of distinct values to obtain and display in the UI. By default, the maximum value is 100. Larger maximum values might cause a long delay in populating the UI control. Note: Missing values are ignored, so missing values do not appear in the list of distinct values.
`width`	specifies the width of the control. This value can be in percent (%), em, or px. By default, SAS Studio sizes the control based on the available width and content.

In this example, you want the user of this task to see the first 15 distinct values for the response variable.

In the code, you first specify the Datasources element because an input data set is required to run this task. Then in the Roles element, you specify that only one response variable is required to run this task. The name attribute for this role is VAR.

Now, you want to create an option that lists the first 15 distinct values in the VAR variable. The code for the distinct input type includes these attributes.

The source attribute specifies that the values that appear in the Age of interest option come from the VAR role (in this example, the Age variable).
The max attribute specifies that a maximum of 15 values should be available for the Age of interest option.

<DataSources>
   <DataSource name="DATASOURCE">
      <Roles>
         <Role type="A" maxVars="1" order="true" minVars="1" 
            name="VAR">Response variable</Role>
      </Roles>
   </DataSource>
</DataSources>
<Options>
   <Option name="values" inputType="distinct" source="VAR" 
      max="15">Age of interest:</Option>
</Options>

Here is an example of the distinct control in the user interface:

inputtext

This input type has these attributes:

Attribute	Description
`required`	specifies whether any input text is required. Valid values are `true` and `false`. The default is false.
`missingMessage`	specifies the tooltip text that appears when the text box is empty but input text is required. No message is displayed by default.
`promptMessage`	specifies the tooltip text that appears when the text box is empty and the user has selected the text box.
`width`	specifies the width of the control. This value can be in percent (%), em, or px. By default, SAS Studio sizes the control based on the available width and content.

The code in the sample task definition creates a text box called Indented field with default value. The default value for this option is output.xls. If the user removes this text, the message “Enter a filename” appears because a valid filename is required.

<Option name="txtEXAMPLE" defaultValue="output.xls" inputType="inputtext" 
   width="100%"
   indent="1"
   required="true"
   promptMessage="Enter a filename"
   missingMessage="Missing filename">Indented field 
      with default value:</Option>

Here is an example of an inputtext control in the user interface:

Indented field with default value Text Box

modelbuilder

A model is an equation that consists of a dependent or response variable and a list of effects. The user creates the list of effects from variables and combinations of variables.

Here are examples of effects:

main effect

For variables Gender and Height, the main effects are Gender and Height.

interaction effect

For variables Gender and Height, the interaction is Gender * Height. You can have two-way, three-way, ...n-way interactions.

The order of the variables in the interaction is not important. For example, Gender * Height is the same as Height * Gender.

nested effect

For variables Gender and Height, an example of a nested effect is Gender(Height).

polynomial effect

You can create polynomial effects with continuous variables. For the continuous variable X, the quadratic polynomial effect is X*X. You can have second-order, third-order, ...nth-order polynomial effects.

The modelbuilder input type has these attributes:

Attribute	Description
`required`	specifies whether any input text is required. Valid values are `true` and `false`. The default is false.
`roleContinuous`	specifies the role that contains the continuous variables. The default value is null.
`roleClassification`	specifies the role that contains the classification variables. The default value is null.
`excludeTools`	specifies the effect and model buttons to exclude from the user interface. Valid values are `ADD`, `CROSS`, `NEST`, `TWOFACT`, `THREEFACT`, `FULLFACT`, `NFACTORIAL`, `POLYEFFECT`, `POLYMODEL`, and `NFACTPOLY`. Separate multiple values with spaces or commas.
`width`	specifies the width of the control. The width value can be specified in percent, em, or px. By default, the control is automatically sized based on the available width and content.

Note: At least one of the role attributes (roleContinuous or roleClassification) is required. If both attributes are set to null, no variables are available to create the model.

Here is some example code for the modelbuilder input type from the Generalized Linear Model task:

<Option excludeTools="THREEFACT,NFACTPOLY" inputType="modelbuilder"
   name="modelbuilder" roleClassification="classVariables" 
   roleContinuous="continuousVariables" 
   width="100%">Model</Option>

Here is an example of a modelbuilder control in the user interface:

After selecting an input data source and identifying the columns that contain the continuous or classification variables, you can start building your model. This example uses the Sashelp.Cars data set as the input data source. MSRP, EngineSize, Invoice, and Cylinders are the continuous variables.

Example of Creating Model Effects in the Model Effects Builder

multientry

This input type has these attributes:

Attribute	Description
`required`	specifies whether a value is required. Valid values are `true` and `false`. The default value is false.
`width`	specifies the width of the control. This value can be in percent (%), em, or px. By default, SAS Studio sizes the control based on the available width and content.

In this example, you want a multi-entry control where users can specify the educational degrees that they have earned. In the Options element, you define three values (High school diploma, Bachelor’s degree, and Master’s degree) to appear in the list.

In the UI element, you use the OptionsChoice tag to assign default values for the multi-entry control.

<Options>
   <Option name="multiExample" required="true" 
      inputType="multientry">Multi-Entry:</Option>
   <Option name="ONE" inputType="string">High school diploma</Option>
   <Option name="TWO" inputType="string">Bachelor's degree</Option>
   <Option name="THREE" inputType="string">Master's degree</Option>
</Options>
<UI>
   <Container option="OPTIONSTAB">
      <Group option="GROUP2">
         <OptionChoice option=multiExample">
         <OptionItem option="ONE"/>
         <OptionItem option="TWO"/>
         <OptionItem option="THREE"/>
      </Group>

...
   </Container>
</UI>

Here is an example of a multi-entry control in the user interface.

Levels of education Option with Three Default Values

The user can select any of these values. This type of control also enables users to add values (such as PhD) to this list.

Adding the PhD Value to the Levels of education Option

numbertext

This input type has these attributes:

Attribute	Description
`decimalPlaces`	specifies the number of decimal places to display. Valid values include a single value or a range. To create a field that allows 0 to 3 decimal places, specify `decimalPlaces=”0,3”`. The maximum number of decimal places is 20.
`invalidMessage`	specifies the tooltip text that appears when the content is invalid.
`maxValue`	specifies the maximum value that is allowed. If the user tries to exceed this value, a message appears. The default value is 9000000000000.
`minValue`	specifies the minimum value that is allowed. If the user specifies a value that is below the minimum value, a message appears.
`missingMessage`	specifies the tooltip text that appears when the text box is empty, but a value is required.
`promptMessage`	specifies the tooltip text that appears when the text box is empty, and the field has focus.
`rangeMessage`	specifies the tooltip text that appears when the value in the text box is outside the specified range.
`required`	specifies whether a value is required. Valid values are `true` and `false`. The default value is false.
`width`	specifies the width of the control. This value can be in percent (%), em, or px. By default, SAS Studio sizes the control based on the available width and content.

This example code creates a field called Number to order.

<Option name="amt" defaultValue="1" inputType="numbertext"
   minValue="0" maxValue="100">Number to order:</Option>

Here is an example of the numbertext control in the user interface:

According to the code, the minimum value for this field is 0, and the maximum value is 100. Because 110 exceeds the maximum value, the default out of range message appears.

numstepper

This input type has these attributes:

Attribute	Description
`decimalPlaces`	specifies the number of decimal places to display. Valid values include a single value or a range. To create a field that allows 0 to 3 decimal places, specify `decimalPlaces=”0,3”`.
`increment`	specifies the number of values that the option increases or decreases when a user clicks the up or down arrow. The default value is 1.
`maxValue`	specifies the maximum value that is allowed. If the user tries to exceed this value, a message appears. The default value is 9000000000000.
`minValue`	specifies the minimum value that is allowed. If the user specifies a value that is below the minimum value, a message appears.
`required`	specifies whether a value is required. Valid values are `true` and `false`. The default value is false.
`width`	specifies the width of the control. This value can be in percent (%), em, or px. By default, SAS Studio sizes the control based on the available width and content.

The first example in the sample task definition creates an option with an assigned default value of 5.

<Option name="labelNumStepperEXAMPLE1" inputType="string">
   Numeric stepper with default values:</Option>
<Option name="basicStepperEXAMPLE" defaultValue="5" inputType="numstepper"
   indent="1">Label:</Option>

Here is an example of a numstepper control in the user interface:

Numeric stepper with default values Option

The second example in the sample task definition creates an option with a specified minimum value, maximum value, and increment.

<Option name="labelNumStepperEXAMPLE2" inputType="string">
   Numeric stepper with a minimum value of -10, a maximum value of 120, and 
   an increment of 2.</Option>
<Option name="advancedStepperEXAMPLE" defaultValue="80" inputType="numstepper" 
   increment="2"
   minValue="-10"
   maxValue="120"
   decimalPlaces="0,2"
   size="8em"
   indent="1">Label:</Option>

When you run the code, here is the resulting user interface:

Numeric stepper with a minimum value of –10, a maximum value of 120, and an increment of 2

radio

This input type has one attribute:

Attribute	Description
`variable`	specifies a variable that contains the name of the currently selected radio button.

The second example in the sample task definition creates an option called Radio button group label with the Radio button 1 button selected by default.

<Option name="labelEXAMPLE2" inputType="string">Radio button group label:</Option>
<Option name="radioButton1" variable="radioEXAMPLE" defaultValue="radioButton1"
   inputType="radio">Radio button 1</Option>
<Option name="radioButton2" variable="radioEXAMPLE" 
   inputType="radio">Radio button 2</Option>
<Option name="radioButton3" variable="radioEXAMPLE" 
   inputType="radio">Radio button 3</Option>

Here is an example of a radio control in the user interface:

select

This input type has these attributes:

Attribute	Description
`multiple`	specifies if users can select one or multiple items from the list. Valid values are `true` and `false`. The defaultvalue is true.
`required`	specifies whether the user must select a value from the list. Valid values are `true` and `false`. The default value is false.
`sourceLink`	specifies that the data for this control should come from another option.
`width`	specifies the width of the control in percent (%), em, or px.
`height`	specifies the height of the control in em or px.

This example creates a selection list called Subjects of interest and has three choices: Biology, Chemistry, and Physics. The defaultValue attribute specifies the item or items that should be selected by default. Multiple items are in a comma-separated list. In this example, item1 (Biology) and item2 (Chemistry) are selected by default.

<Option name="selectExample" inputType="select" multiple="true"
   defaultValue="item1, item2">Subjects of interest</Option>
   <Option name="item1" inputType="string">Biology</Option>
   <Option name="item2" inputType="string">Chemistry</Option>
   <Option name="item3" inputType="string">Physics</Option>

Here is an example of the select control in the user interface:

Example of a Select Box with Two Items Selected

slider

This input type has these attributes:

Attribute	Description
`discreteValues`	specifies the number of discrete values in the slider. For example, if `discreteValues=”3”`, the slider has three values: a minimum value, a maximum value, and a value in the middle.
`maxValue`	specifies the maximum value for this option.
`minValue`	specifies the minimum value for this option.
`showButtons`	specifies whether to show the increase and decrease buttons for the slide. Valid values are `true` and `false`. The default value is true.

The first example in the sample task definition creates a slider option with buttons.

<Option name="labelSliderEXAMPLE1" inputType="string">
      Slider with buttons.</Option>
<Option name="labelSliderEXAMPLE1" defaultValue="80.00" 
   inputType="slider" discreteValues="14" minValue="-10"
   maxValue="120">Label</Option>

When you run the code, here is the resulting user interface:

The second example in the sample task definition creates a slider option without buttons.

<Option name="labelSliderEXAMPLE2" 
   inputType="string">Slider without buttons.</Option>
<Option name="labelSliderEXAMPLE2" defaultValue="80.00" 
   inputType="slider" discreteValues="14" minValue="-10"
   maxValue="120" showButtons="false">Label</Option>

When you run the code, here is the resulting user interface:

string

The string input type can be used to display informational text to the user, to define strings for the OptionChoice tags, and to define string values that are used by the Velocity code.

Attribute	Description
`returnValue`	is the string that is returned in the control’s Velocity variable (instead of the control’s name). This attribute applies only when the string is used in an `OptionChoice` tag.

The code for the sample task definition contains several examples of the string input type. In the code for the slider option, the explanatory text (Slider with buttons) is created by the string input type.

<Option name="labelSliderEXAMPLE1" inputType="string">
   Slider with buttons.</Option>
<Option name="labelSliderEXAMPLE1" defaultValue="80.00" 
   inputType="slider" discreteValues="14" minValue="-10"
   maxValue="120">Label</Option>

When you run the code, here is the resulting user interface:

textbox

The textbox input type enables the user to enter multiple lines of text. This input type has these attributes:

Attribute	Description
`required`	specifies whether any input text is required. Valid values are `true` and `false`. The default is false.
`width`	specifies the width of the control. This value can be in percent (%), em, or px. By default, SAS Studio sizes the control based on the available width and content.
`height`	specifies the height of the control. This value can be in em or px. By default, SAS Studio sizes the control based on the available height and content.

If you specify the defaultValue attribute with this input type, you can specify the initial string to display in the text box. In this example, the text

’Enter
                        text here’

appears in the text box by default. Note the use of single quotation marks around the text. This example shows how you would include single quotation marks in your default text. These quotation marks are not required.

<Option name="textSimple" required="true" inputType="textbox" 
      defaultValue="'Enter text here'">Text Box</Option>

Here is an example of a textbox control in the user interface. Note this example uses the default text. When the user types in the textbox control, this text disappears.

Example of Text Box in the User Interface

validationtext

This input type has these attributes:

Attribute	Description
`required`	specifies whether any input text is required. Valid values are `true` and `false`. The default is false.
`invalidMessage`	specifies the tooltip text to display when the content in the text box is invalid. By default, no message is displayed.
`missingMessage`	specifies the tooltip text that appears when the text box is empty but text is required. By default, no message is displayed.
`promptMessage`	specifies the tooltip text that appears when the text box is empty and the text box is selected. By default, no message is displayed.
`regExp`	specifies the regular expression pattern to use for validation. This syntax comes directly from JavaScript Regular Expressions.
`width`	specifies the width of the control. This value can be in percent (%), em, or px. By default, SAS Studio sizes the control based on the available width and content.

The code for the sample task definition creates a text box called Label.

<Option name="validationTextExample" defaultValue="99999"
   inputType="validationtext"
   required="true"
   width="100%"
   promptMsg="A message that tells the user what type of value to enter"
   invalidMsg="Invalid value message"
   missingMsg="This value is required."
   regExp="\d{5}">Label:
</Option>

When you run the code, here is the resulting user interface:

If you remove the default value from this box, the This value is required message appears.

Example of “This value is required” Message for a Text Box

When the user begins entering a value, this message appears:

A message that
                           tells the user what type of value to enter

Example of Text That Could Appear When User Starts Entering Values into the Text Box

If the specified value is invalid, the Invalid value message appears.

Example of “Invalid value message” for a Text Box

Specifying a Return Value Using the returnValue Attribute

For input types (such as combobox and select) that enable users to select from a list of choices, the default behavior is to return the name of the selected item in the list. However, because the name attribute must be unique for every option, this default behavior could be limiting in some scenarios.

When you specify the returnValue attribute on an Option element, the string that is specified for the returnValue attribute is returned instead of the name.

In this example, the $vegetables Velocity variable has the value of 1, 2, or 3, depending on what option item the user selected in the user interface. If you do not specify the returnValue attribute, the Velocity variable returns carrots, peas, or corn.

<Options>
   <Option name="vegetables" inputType="select">Select a vegetable</Option>
   <Option name="carrots" returnValue="1" inputType="string">Carrots</Option>
   <Option name="peas" returnValue="2" inputType="string">Peas</Option>
   <Option name="corn" returnValue="3" inputType="string">Corn</Option>
</Options>
<UI>
   <Container option="OPTIONSTAB">
      <Group option="GROUP1">
         <OptionChoice option="vegetables">
            <OptionItem option="carrots"/>
            <OptionItem option="peas"/>
            <OptionItem option="corn"/>
         </OptionChoice>
      </Group>

...
   </Container>
</UI>

Populating the Values for a Select Control from a Source Control

About Data Linking

Data linking is a way to populate a control based on the contents of another control. Data linking is currently supported when a select control links to data from a role or from the model effects builder. If the select control links to anywhere else, any children in the OptionChoice tag are ignored.

The select control is the recipient of the data. The control that the select input type links to is called the source. To link a select input type to its source, you define the sourceLink attribute and use the name of the source control.

The Velocity code that is returned for the select control uses the same Velocity structure that you would expect from the source control.

Linking to a Role

If a select control is linked to a role, the values in the select control are the current list of roles in the roles option. In this example, the name of the role variable is NUMVAR (specified in the name attribute). In the select control, the sourceLink attribute links to NUMVAR.

<DataSources>
   <DataSource name="PRIMARYDATA">
      <Roles>
         <Role type="N" maxVars="0" order="true" minVars="0" name="NUMVAR"
            exclude="VAR">Numeric Variable</Role>
      </Roles>
   </DataSource>
</DatatSources>
<Options>
   <Option name="roleList" inputType="select" sourceLink="NUMVAR"/>

The Velocity variable that is created for the select control is $roleList. The contents of the $roleList variable mimic the output of a typical role control. For more information, see How the Roles Elements Appear in the Velocity Code.

Linking to Effects from the Model Builder

If a select control is linked to a modelbuilder input type, the values in the select control are the list of effects in the model effects builder.

An additional attribute called sourceType can be used to set a filter on the data that is sent to the select control. Currently, the only defined filter is ‘filterClassification’. When this filter is specified, only classification effects appear in the select control.

In this example, the modelbuilder control is named MEB. In the select control, the sourceLink attribute is linking to MEB, and the sourceType attribute specifies the ‘filterClassification’ filter. As a result, only classification effects appear in the source control.

<Options>
   <Option name="meb" inputType="modelbuilder" roleContinuous="CONTVARS"
      roleClassification="CLASSVARS"/>
   <Option name="mebList" inputType="select" sourceLink="MEB" 
      sourceType="filterClassification"/>
</Options>

The Velocity variable that is created for the select control is $mebList. The contents of the $mebList variable mimic the output of the model effects builder. For more information, see modelbuilder.

Another example is in the Linear Regression task. In this task, the effects listed in the model builder are the options for the Select the effects to test option on the Options tab.

The Variables pane in the model builder lists the variables that the user assigned to either the Classification variables role or the Continuous variables role. The user can create main, crossed, nested, and polynomial effects. These effects appear in the Model effects pane.

Example of Model effects in the Linear Regression Task

On the Options tab, all classification effects are available from the Select effects to test option.

Effects That the User Can Select for Multiple Comparisons

Here are the relevant portions of code from the Linear Regression task:

<Option inputType="string" name="modelGroup">MODEL EFFECTS</Option>
<Option inputType="string" name="modelTab">MODEL</Option>

1<Option inputType="modelbuilder" name="modelBuilder"
   excludeTools="POLYEFFECT,TWOFACT,THREEFACT,NFACTPOLY" 
   roleClassification="classVariable" 
   roleContinuous="continuousVariables"
   width="100%">Model</Option>
...
<Option inputType="string" name="multCompareGroup">Multiple Comparisons</Option>

2<Option indent="1" inputType="select" multiple="true" name="multCompareList"
   sourceLink="modelBuilder" sourceType="filterClassification">
   Select effects to test</Option>

1 Creates the model builder on the Models tab. Classification variables and continuous variables can be used to create the model effects.

Creates the Select effects to test option. The sourceLink attribute specifies that the initial list of values for this option is the list of model effects in the model builder. The sourceType attribute filters the list generated by the sourceLink attribute. The filterClassification filter specifies that only effects that include the classification variable should be available in the Select effects to test option.

In the Perform multiple comparisons option, the initial list of model effects includes region, line, product, region(line), line(product), and cost. However, cost is a continuous variable. When this list is filtered, only the model effects that involve classification variables (region, line, and product) are listed as values for the Select effects to test option.