How the Options Elements Appear in the Velocity Code :: SAS(R) Studio 3.5: Developer's Guide to Writing Custom Tasks

checkbox

The Velocity variable for the checkbox input type holds the state information for the check box option. If the check box is selected, the variable is set to 1. If the check box is not selected, the variable is set to 0.

In this example, the code outputs the character N if the Print row numbers check box is selected.

<Options>
   <Option name="PRINTNUMROWS" defaultValue="1" 
      inputType="checkbox">Print row numbers</Option>
</Options>
<Code Template>
   <![CDATA[
#if ($PRINTNUMROWS == '1')
      N
#end]]>
</CodeTemplate>

color

The Velocity variable for the color input type holds the specified color.

In this example, the code template is printed as colorEXAMPLE=specified-color.

<Options>
   <Option name="colorEXAMPLE" defaultValue="white" 
      inputType="color">Select a color</Option>
</Options>
<CodeTemplate>
   <![CDATA[
%put colorEXAMPLE=$colorEXAMPLE;
#end]]>
</CodeTemplate>

combobox

The Velocity variable for the combobox input type holds the name of the selected option. If no option is selected, the variable is null.

This example outputs the string HEADING=option-name, where option-name is the value selected from the Direction of heading drop-down list. If the user selects Horizontal from the Direction of heading drop-down list, the output is HEADING=”horizontal”.

<Options>
   <Option name="HEADING" defaultValue="default"
      inputType="combobox">Direction of heading:</Option>
   <Option name="default" inputType="string">Default</Option>
   <Option name="horizontal" inputType="string">Horizontal</Option>
   <Option name="vertical" inputType="string">Vertical</Option>
</Options>
<UI>
   <Container option="OPTIONSTAB">
      <OptionChoice option="HEADING">
         <OptionItem option="default"/>
         <OptionItem option="horizontal"/>
         <OptionItem option="vertical"/>
      </OptionChoice>
   </Container>
</UI>
<CodeTemplate>
   <![CDATA[
#if ($HEADING && (&HEADING !="default"))
      HEADING=$HEADING
#end
]]>
</CodeTemplate>

datepicker

The Velocity variable for the datepicker input type holds the date that is specified in the datepicker control. By default, this variable is an empty string. If the user selects a date or you specify a default value for the date in the code, the variable holds the specified date. You specify the format of the date by using the format attribute.

This example outputs a date if one has been selected. If no date is selected, the “You have not selected a date.” message appears.

<Options>
   <Option name="myDate" inputType="datepicker" format="monyy7.">
      Select a date:</Option>
</Options>
<CodeTemplate>
   <![CDATA[
#if( $myDate == "" )
You have not selected a date.
#else
The date you selected is: $myDate
#end
]]>
</CodeTemplate>

distinct

The Velocity variable for the distinct input type holds the information for the distinct control. By default, this variable is the first distinct value in the list.

In this example, the Response variable is Age, and the distinct value is 15. The Velocity script produces the line Age(event=15).

<DataSources>
   <DataSource name="Class">
      <Roles>
         <Role name="responseVariable" type="A" minVars="1" 
            maxVars="1">Response</Role>
      </Roles>
   </DataSource>
</DataSources>
<Options>
   <Option name="referenceLevelCombo" inputType="distinct" 
      source="responseVariable">Event of interest:</Option>
</Options>
<CodeTemplate>
   <![CDATA[
   #foreach( $item in $responseVariable ) $item (event='$referenceLevelCombo')#end
</CodeTemplate>

dualselector

The Velocity variable for the dualselector input type holds the array of selected values.

This example is for a dualselector control that contains three values: anothertest1, anothertest2, and anothertest3. Any or all of these values can be selected. Only the values that are selected in the dualselector control appear in the Velocity code.

<OptionChoice name="ANOTHERLIST" inputType="dualselector">
   <OptionItem option="anothertest1"/>
   <OptionItem option="anothertest2"/>
   <OptionItem option="anothertest3"/>
<OptionChoice>
...
<CodeTemplate>
<![CDATA[
#if ($ANOTHERLIST && $ANOTHERLIST.size() > 0)
#foreach($item in $ANOTHERLIST) $item #end
#end
]]>
</CodeTemplate>

inputtext

The Velocity variable for the inputtext input type holds the string that was specified in the text box.

This example outputs the string OBS= and the text specified in the Column text box. If the user enters

Student
                     Number

into the Column text box, the output is OBS=”Student Number”.

<Options>
   <Option name="OBSHEADING" indent="1" defaultValue="Row number"
      inputType="inputtext">Column label:</Option>
 </Options>
<CodeTemplate>
   <![CDATA[
OBS="$OBSHEADING"#end]]>
</CodeTemplate>

mixedeffects

The Velocity variable that holds the output of the mixed effects control is a data structure containing two members, modelSummaryValues and mixedEffectsModels.

The modelSummaryValues member summarizes the user’s interaction with the mixed effects control. Here are members for the mixed effects control:

Member	Description
`randomEffectsSetCount`	specifies the number of random effects model sets that were created.
`repeatedEffectsSetCount`	specifies the number of repeated effects model sets that were created.
`fixedEffectsCount`	specifies the number of fixed effects that were created.
`fixedContinuousMainEffectsCount`	specifies the number of main fixed effects that were created for a continuous variable.
`fixedClassificationMainEffectsCount`	specifies the number of main fixed effects that were created for a classification variable.
`fixedInterceptValue`	specifies the value of the intercept of the fixed effects model set. Valid values are `true`, `false`, or null.
`fixedModelsetInvalidStateCount`	specifies the number of fixed effects model sets with an invalid context.
`randomModelsetInvalidStateCount`	specifies the number of random effects model sets with an invalid context.
`repeatedModelsetInvalidStateCount`	specifies the number of repeated effects model sets with an invalid context.
`meansModelsetInvalidStateCount`	specifies the number of means effects model sets with an invalid context.
`zeroInflatedModelsetInvalidStateCount`	specifies the number of zero-inflated effects model sets with an invalid context.

The mixedEffectsModels member describes the detailed results of the interactions with the mixed effects control. This member is an array of models created by the user. The models are in the order in which they were created.

Member	Description
`emtype`	specifies the type of model.
`intercept`	specifies whether the intercept is visible to the user. Valid values are `true`, `false`, or null.
`modelEffects`	specifies the array of effects that create this model. `effectType`: main, interaction, or nested `effectName`: the display name `memberSet1`: the members for this effect `memberSet2`: for nested effects, the inner members within the outer members
Additional Members for Random and Repeated Effects
`groupEffect`	contains information about the group effect if one is defined. Otherwise, the value is null. `effectType`: main, interaction, or nested `effectName`: the display name `memberSet1`: the members for this effect `memberSet2`: for nested effects, the inner members within the outer members
`subjectEffect`	contains information about the subject effect if one is defined. Otherwise, the value is null. `effectType`: main, interaction, or nested `effectName`: the display name `memberSet1`: the members for this effect `memberSet2`: for nested effects, the inner members within the outer members
`covarianceStructures`	specifies the array that contains the covariance structure, if one is defined. Only one covariance structure can be defined. If no structure is defined, the array is empty. `csType` specifies the type of covariance structure. `csParameterValues` specifies the parameter value for the covariance structure. If no parameter value is needed, `csParameterValues` is set to null.

The following Velocity code does not generate SAS code. The purpose of this code is to demonstrate how to parse the Velocity structure for mixed effects.

<CodeTemplate>
<![CDATA[
/* ======== MEC Summary Values START ========*/
#if ( $mixedEffects.modelSummaryValues )
Random Effects Set Count: $mixedEffects.modelSummaryValues.randomEffectsSetCount;
Repeated Effects Set Count: $mixedEffects.modelSummaryValues.repeatedEffectsSetCount;
Fixed Effects Count: $mixedEffects.modelSummaryValues.fixedEffectsCount;
Fixed Continuous Main Effects Count: 
   $mixedEffects.modelSummaryValues.fixedContinuousMainEffectsCount;
Fixed Classification Main Effects Count: 
   $mixedEffects.modelSummaryValues.fixedClassificationMainEffectsCount;
#if ( $mixedEffects.modelSummaryValues.fixedInterceptValue )
Fixed Intercept Value: $mixedEffects.modelSummaryValues.fixedInterceptValue;
#else
Fixed Intercept Value: null;
#end
Fixed Classification Main Effects Count: 
   $mixedEffects.modelSummaryValues.fixedClassificationMainEffectsCount;
/* Model set invalid state count: */
Fixed: $mixedEffects.modelSummaryValues.fixedModelsetInvalidStateCount;
Random: $mixedEffects.modelSummaryValues.randomModelsetInvalidStateCount;
Repeated: $mixedEffects.modelSummaryValues.repeatedModelsetInvalidStateCount;
Means: $mixedEffects.modelSummaryValues.meansModelsetInvalidStateCount;
Zero-Inflated: $mixedEffects.modelSummaryValues.zeroInflatedModelsetInvalidStateCount;
#else
/* No summary values found. */
#end
/* ======== MEC Summary Values END ==========
 *
 *
 * ======== MEC models START ========*/
#if ( $mixedEffects.mixedEffectsModels )
#foreach( $model in $mixedEffects.mixedEffectsModels )
/*
 * **** Begin $model.emtype effects model ****
 */
#if ( $model.intercept == "True" )
/* This model has an intercept. */
#elseif ( $model.intercept == "False" )
/* This model has no intercept. */
#end
/* User has generated $model.modelEffects.size() model effects */
#if ( $model.modelEffects.size() > 0 )
#foreach( $modelEffect in $model.modelEffects )
## if the effectType is 'nested', then this is a nested effect
#if ( $modelEffect.effectType == 'nested' )
$velocityCount $modelEffect.effectType effect: #foreach( $subitem1 in 
   $modelEffect.memberSet1 )$subitem1#if($velocityCount < 
   $modelEffect.memberSet1.size())*#end#end(#foreach($subitem2 in 
   $modelEffect.memberSet2)$subitem2#if($velocityCount < 
   $modelEffect.memberSet2.size())*#end#end);
## handle 'main' or 'interaction' effects
#else
$velocityCount $modelEffect.effectType effect: #foreach( $subitem in
   $modelEffect.memberSet1 )$subitem#if($velocityCount < 
   $modelEffect.memberSet1.size())*#end#end;
#end
#end
#else
/* User hasn't generated any model effects yet */
#end
#if ( $model.subjectEffect )
/* user has generated a subject effect */
#set ( $modelEffect = $model.subjectEffect )
## if the effectType is 'nested', then this is a nested effect
#if ( $modelEffect.effectType == 'nested' )
$modelEffect.effectType effect: #foreach( $subitem1 in 
   $modelEffect.memberSet1 )$subitem1#if($velocityCount < 
   $modelEffect.memberSet1.size())*#end#end(#foreach($subitem2
   in $modelEffect.memberSet2)$subitem2#if($velocityCount < 
   $modelEffect.memberSet2.size())*#end#end);
## handle 'main' or 'interaction' effects
#else
$modelEffect.effectType effect: #foreach( $subitem in 
   $modelEffect.memberSet1 )$subitem#if($velocityCount < 
   $modelEffect.memberSet1.size())*#end#end;
#end
#end
#if ( $model.groupEffect )
/* user has generated a group effect */
#set ( $modelEffect = $model.groupEffect )
## if the effectType is 'nested', then this is a nested effect
#if ( $modelEffect.effectType == 'nested' )
$modelEffect.effectType effect: #foreach( $subitem1 in 
   $modelEffect.memberSet1 )$subitem1#if($velocityCount < 
   $modelEffect.memberSet1.size())*#end#end(#foreach($subitem2
   in $modelEffect.memberSet2)$subitem2#if($velocityCount < 
   $modelEffect.memberSet2.size())*#end#end);
## handle 'main' or 'interaction' effects
#else
$modelEffect.effectType effect: #foreach( $subitem in 
   $modelEffect.memberSet1 )$subitem#if($velocityCount
   < $modelEffect.memberSet1.size())*#end#end;
#end
#end
#if ( $model.covarianceStructures )
/* User has generated $model.covarianceStructures.size()
   covariance structures */
#if ( $model.covarianceStructures.size() > 0 )
#foreach( $covStruct in $model.covarianceStructures )
$velocityCount $covStruct.csType parameters: 
   [#foreach( $subitem in $covStruct.csParameterValues
   )$subitem#if($velocityCount < 
   $covStruct.csParameterValues.size()),#end#end];
#end
#else
/* User hasn't generated any covariance structures yet */
#end
#end
/*
 * **** End $model.emtype effects model ****
 */
#end
#else
/* User hasn't included any effects models yet */
#end
/* ======== MEC models END ==========
 *
 *
 * ======== MEC DEBUG START ========
 * modelSummaryValues property */
contents: $mixedEffects.modelSummaryValues;
/* Number of effects models: $mixedEffects.mixedEffectsModels.size()
 * mixedEffectsModels property */
contents: $mixedEffects.mixedEffectsModels;
/* ======== MEC DEBUG END ==========*/
]]>
    </CodeTemplate>

modelbuilder

Note: The modelbuilder control will be removed in a later release. All SAS Studio tasks that used the modelbuilder control have been revised to use the mixedeffects control.

The Model Effects Builder is a custom component. This example code shows how the Model Effects Builder might be used in the user interface for a task. The Velocity code shows how to process the effects that are generated by the modelbuilder component.

<Metadata>
   <DataSources>
      <DataSource name="dataset">
      <Roles>
      <Role type="N" maxVars="0" minVar="1" order="true"
         name="CONTVARS">Continuous variables</Role>
      <Role type="A" maxVars="0" minVar="0" order="true"
         name="CLASSVARS">Classification variables</Role>
   </Roles>

   <Options>
      <Option inputType="string" name="modelGroup">MODEL</Option>
      <Option inputType="string" name="modelTab">MODEL</Option>
         <Option excludeTools="THREEFACT, NFACTPOLY" inputType="modelbuilder"
            name="modelBuilder roleClassification="classVariables"
            roleContinuous="continuousVariables" width="100%">Model</Option>
      <Option inputType="string" name="responseGroup">Response</Option>
    </Options>
</Metadata>
<UI>
   <Container option="modelTab">
      <Group open="true" option="modelGroup">
         <OptionItem option="modelBuilder"/>
      </Group>
   </Container>
</UI>

<CodeTemplate>
<![CDATA[

#macro ( ModelEffects )
#if ( $modelBuilder )
#foreach ( $item in $modelBuilder )
## if first element is 'm', then this is a main effect
#if ( $item.get(0) == 'm' )
#foreach( $subitem in $item.get(1) )$subitem #end
## if first element is 'i', then this is an interaction effect
#elseif ( $itemget(0) == 'i' )
#foreach( $subitem in $item.get(1) )$subitem#if($velocityCount
   < $item.get(1).size())*#else #end#end
## if first element is 'n', then this is a nested effect
#elseif ( $item.get(0) == 'n' )
#foreach( $subitem1 in $item.get(1) )$subitem1#if($velocityCount
   < $item.get(1).size())*#end#end(#foreach($subitem2 in 
   $item.get(2))$subitem(2)#if($velocityCount < 
   $item.get(2).size())*#end#end)
#end
#end
#end
#end



]]>
</CodeTemplate>

multientry

The Velocity variable for the multientry input type holds the array of specified values.

In this example, the multientry control contains the values of ONE, TWO, and THREE, so the array contains the values ONE, TWO, and THREE. Users can add new values (such as FOUR). Any new user-specified values are added to the array. In this example if the user specifies FOUR, the array contains the values ONE, TWO, THREE, and FOUR.

<UI>
   <Container option="OPTIONSTAB">
      <Group option="GROUP2">
         <OptionChoice name="multiExample" inputType="multientry">
            <OptionItem option="ONE"/>
           <OptionItem option="TWO"/>
           <OptionItem option="THREE"/>
       </OptionChoice>
      </Group>

...
   </Container>
</UI>
<CodeTemplate>
<![CDATA[
#if ($multiExample && $multiExample.size() > 0)
#foreach($item in $multiExample) $item #end
#end
]]>
</CodeTemplate>

numbertext

The Velocity variable for the numbertext input type holds the string specified in the numbertext option.

This example outputs the string AMOUNT and the value in the Number to order box. If the user enters 2 into the Number to order box, the string output is AMOUNT=5.

<Options>
   <Option name="AMT" defaultValue="1" minValue="0" maxValue="100"
      inputType="numbertext">Number to order:</Option>
</Options>
<CodeTemplate>
   <![CDATA[
AMOUNT=$AMT]]>
</CodeTemplate>

numstepper

The Velocity variable for the numstepper input type holds the string specified in the number control box.

This example outputs the string GROUPS= and the value in the Number of groups box. If the user enters 2 into the Number of groups text box, the string output is GROUPS=”2”.

<Options>
   <Option name="NUMGRPS" defaultValue="1" minValue="0" 
      inputType="numstepper" indent="1">Number of groups:</Option>
 </Options>
<CodeTemplate>
   <![CDATA[
GROUPS="$NUMGRPS"#end]]>
</CodeTemplate>

OptionTable

The Velocity variable for the option table holds information about the option’s current state. This variable has two members, rows and columns.

The rows member accesses the contents of the option table in an array of rows.

The following information can be retrieved from each item in a row:

Member	Description
`values`	specifies an array of values for each row. Each `values` array element contains these members: `id`—the ID of the row, which correlates to the row number. The row numbers start at 1. the column name as defined in the `Column` element.

The columns member accesses the contents of the option table in an array of columns. The following information can be retrieved from each item in a column:

Member	Description
column name as defined in the `Column` element	specifies the information specific to that column. This structure has these members: `values`—an array of the current values. `isValid`—a Boolean value (1 or 0) that indicates whether the column is currently valid. `numValues`—the current number of values for this column.

This code uses the metadata that you specified for the OptionTable element in Working with the Metadata Element. This code does not generate SAS code. Instead, it demonstrates how to parse the Velocity structure of the option table.

<CodeTemplate>
<![CDATA[

/* Print option table content - rows array */
$optionTable.rows;

/* Iterate over each row to obtain values */
#foreach($item in $optionTable.rows.values)
row[$item.id] = $item
#end
;

/* Print option table content - this time using a columns array */
$optionTable.columns;

/* Iterate over each column to obtain values */
#foreach($columnName in $optionTable.columns.keySet())
column[$columnName] = $optionTable.columns[$columnName]
#end
;

/* cell[row][column_name]*/
/* Row 2, Column TextBox */
$optionTable.rows.values[1].colTextBox;

/* cell[column][row]*/
/* Column ComboBox, Row 3 */
$optionTable.columns["colComboBox"].values[2];

]]>
</CodeTemplate>

outputdata

The Velocity variable for the outputdata control holds the string that appears in the text field. In this example, the name of the Velocity variable is $outputDSName, and the default name that appears in the Data set name: box is Outputds.

<Metadata>
   <Options>
      <Option inputType="string" name="outputGroup">OUTPUT DATA SET</Option>
      <Option defaultValue="Outputds" indent="1" inputType="outputdata"
         name="outputDSName" required="true">Data set name:</Option>
   </Options>
</Metadata>

<UI>
   <Group option="outputGroup" open="true">
      <OptionItem option="outputDSName"/>
   </Group>
</UI>
<CodeTemplate>
   <![CDATA[
      output = $outputDSName]>
   ]]>
</CodeTemplate>

radio

The radio button options are grouped together with the same variable attribute. It is this attribute that defines the Velocity scripting variable. The Velocity scripting variable holds the name of the selected radio button. If no radio button is selected, the variable is null.

In this example, there are four radio buttons.

If the first radio button is selected, there is no output.
If the second radio button is selected, the string output is GROUPS=”100”.
If the third radio button is selected, the string output is GROUPS=”10”.
If the fourth radio button is selected, the string output is GROUPS=”4”.

<Options>
   <Option name="RMSL" inputType="radio" variable="RMGRP" 
      defaultValue="1">Smallest to largest</Option>
   <Option name="RMPR" inputType="radio" 
      variable="RMGRP">Percentile ranks</Option>
   <Option name="RMDC" inputType="radio" variable="RMGRP">Deciles</Option>
   <Option name="RMQR" inputType="radio" variable="RMGRP">Quartiles</Option>
 </Options>
<CodeTemplate>
   <![CDATA[
#if ($RMGRP.equalsIgnoreCase("RMPR")) GROUP=100 #end
#if ($RMGRP.equalsIgnoreCase("RMDC")) GROUP=10 #end
#if ($RMGRP.equalsIgnoreCase("RMQR")) GROUP=4 #end
]]>
</CodeTemplate>

select

The Velocity variable for the select input type holds the array of selected values.

This example shows a selection list that contains three options. Any or all of these options can be selected.

<UI>
   <Container option="OPTIONSTAB">
   <Group option="GROUP1">
      <OptionChoice name="SELECTLIST" inputType="select" multiple="true"> 
         <OptionItem option="Choice1"/>
         <OptionItem option="Choice2"/>
         <OptionItem option="Choice3"/>
      </OptionChoice>
   </Group>

...
   </Container>
</UI>
<CodeTemplate>
<![CDATA[
#if ($SELECTLIST && $SELECTLIST.size() > 0)
#foreach($item in $SELECTLIST) $item #end
#end
]]>
</CodeTemplate>

slider

The Velocity variable for the slider input type holds the numeric string that is specified on the slider control.

This example outputs the string datalabelattrs=(size=n), where n is the value of the Label Font Size option. If the value of the Label Font Size option is 10, the output is datalabelattrs=(size=10).

<Options>
   <Option name="labelSIZE" defaultValue="7" inputType="slider"
      discreteValues="16" minValue="5" maxValue="20">Label Font Size</Option>
 </Options>
<CodeTemplate>
   <![CDATA[
datalabelattrs=(size=$labelSIZE]]>
</CodeTemplate>

string

A Velocity variable is created for the string input type. Here is an example:

<CodeTemplate>
   <![CDATA[
%put string=$str;
   ]]>
<CodeTemplate>

textbox

The Velocity variable for the textbox input type holds the current string in the text box.

In this example, the splitLines attribute is set to false, so newline characters are preserved in the Velocity object.

<CodeTemplate>
   <![CDATA[
%put Text entered: '$text';
]]>
</CodeTemplate>

If the user entered a phrase with a newline character in the text box, that newline character is preserved. Here is an example. In the text box, you entered this phrase:

Hello
World

Here is the resulting Velocity code:

%put Text entered:  'Hello
World';

In this example, the splitLines attribute is set to true, so the Velocity variable is an array of each line.

<CodeTemplate>
   <![CDATA[
#set($line = 1)
#if ( $text2.size() > 0 )
   #foreach( $item in $text2 )
      %put Text line $line: $item;
      #set($line = $line+1)
   #end
#end
   ]]>
</CodeTemplate>

Now if you enter

Hello
World

in the text box, here is the resulting Velocity code:

%put Text line 1: Hello;
%put Text line 2: World;

validationtext

The Velocity variable for the validationtext input type holds the string that was specified in the text box.

The following example outputs the string rho0= and the text in the Null hypothesis correlation option. If the user specifies 0, the resulting string is rho0=0.

<Options>
   <Option name="nullRho" indent="1" inputType="validationtext" 
      defaultValue="0" required="true"
      promptMessage="Enter a number greater than -1 and less than 1
         for the null hypothesis correlation"
      invalidMessage="Enter a number greater than -1 and less than 1
         for the null hypothesis correlation"
      missingMessage="Enter a number grearter than -1 and less than 1
         for the null hypothesis correlation"
      regExp="[-+]?((0\.\d*)|(\.\d+)|0)">Null hypothesis correlation:</Option>
 </Options>
<CodeTemplate>
   <![CDATA[
rh0=$nullRho]]>
</CodeTemplate>