Read-Variable Parameters in SPE

Overview

As stated in my previous post, the Read-Variable SPE function displays a dialog box where users can enter parameters through visual fields for your script. These fields are specified through the “Parameters” parameter in Read-Variable. Parameters is an array, so you can specify one or more fields for your dialog.

Text Parameters

Text parameters allow users to enter any text. You have two types of text parameters: single line and multiple line, as shown in the following example:

$dialogParams = @{
    Title = "Dialog title"
    Description = "Description under title"
    OkButtonName = "Execute"
    CancelButtonName = "Close"
    ShowHints = $true
    Parameters = @(
        @{
            Name = "singleLineText"
            Title = "Single Line Text"
            Placeholder = "This is a single line text field"
            Tooltip = "Tooltip for single line text"
        }
        @{
            Name ="multiLineText"
            Title = "Multiple Line Text"
            Lines = 3
            Placeholder = "This is a multiple line text field"
            Tooltip = "Tooltip for multiple line text"
        }
    )
}
 
$dialogResult = Read-Variable @dialogParams

If you run this snippet in PowerShell ISE, you will get the following dialog:

The only difference between the single-line and multi-line text fields is the “Lines” parameter. Assign it a number greater than 1 to get a multi-line field. The value returned in the variables for these fields ($singleLineText and $multiLineText in the example) is a string.

Dropdown List Parameters

Use dropdown list parameters when you need users to choose a single item in the Sitecore tree. There are two ways of doing this: using a pre-defined root element or using a droptree editor:

$dropDownSelector = Get-Item -Path "master:\content"
 
$dialogParams = @{
    Title = "Dialog title"
    Description = "Description under title"
    OkButtonName = "Execute"
    CancelButtonName = "Close"
    ShowHints = $true
    Parameters = @(
        @{
            Name = "dropDownSelector"
            Title = "Dropdown Selector"
            Root = "/sitecore/content/"
            Tooltip = "Enter item name or select from tree"
        }
        @{
            Name = "dropTreeSelector"
            Title = "Droptree Selector"
            Editor = "droptree"
            Source = "/sitecore/content"
            Tooltip = "Select from dropdown tree"
        }
    )
}
 
$dialogResult = Read-Variable @dialogParams

Executing this script in PowerShell ISE will show you the following window:

If you click on the first field’s down arrow, you will get a tree with the valid item selections. In the field definition, the “Root” parameter allows limiting the selections to a single branch of the tree:

If you click on the second field’s down arrow, you will get a tree with the valid item selections. Note that the definition for this field uses the “Editor” parameter, and it is set to “droptree”. Also, it is optional for these fields to have a “Source” parameter, that allows you to limit the branch where the user can select items:

Also note that the droptree field includes the “[none]” option. The field is usually defaulted to this option, and appears blank in the field when selected. It is important to note this, because if[none] is selected, the returned value will be $null.

These fields return Sitecore.Data.Items.Item objects. That means that you can access the regular Item fields as you do in your .NET code, for example:

Write-Host "Selected in dropdown: " $dropDownSelector.DisplayName
 
# Test $dropTreeSelector for $null
if ($dropTreeSelector -ne $null) {
    Write-Host "Path of selected in droptree: " $dropTreeSelector.FullPath
}

Multi-list Parameters

Use multi-list parameters when you need users to choose one or more items from the Sitecore tree. You can use treelists or one-level multilists:

$dialogParams = @{
    Title = "Dialog title"
    Description = "Description under title"
    OkButtonName = "Execute"
    CancelButtonName = "Close"
    ShowHints = $true
    Parameters = @(
        @{
            Name = "treeListSelector"
            Title = "Treelist Selector"
            Editor = "treelist"
            Source = "DataSource=/sitecore/layout/Placeholder Settings&DatabaseName=master&IncludeTemplatesForDisplay=Placeholder"
            Tooltip = "Select one or more from tree"
        }
        @{
            Name = "multiListSelector"
            Title = "Multilist Selector"
            Editor = "multilist"
            Source = "DataSource=/sitecore/layout&DatabaseName=master"
            Tooltip = "Select one or more from list"
        }
    )
}
 
$dialogResult = Read-Variable @dialogParams

If you run this code snippet in PowerShell ISE, it will show something like this:

Both are differentiated only by the Editor parameter. Treelists have Editor set to “treelist”, and Multi-lists set to “multilist”. Both have a Source parameter, a string with several sub-parameters to customize and restrict the left list/tree. (You can find a reference for these sub-parameters in many blogs and the Sitecore Data Definition Cookbook.) When using sub-parameters, you MUST include the “DatabaseName” sub-parameter, otherwise you will get an error when trying to execute the script (i.e. press the OK button).

The value returned by these fields is an array of Sitecore.Data.Items.Item objects. If no items are selected by the user, these fields return an empty array. In the following example, it displays the number of items selected in each field, and it displays the name and full path of each item selected:

Write-Host "Selected items in treelist: " $treeListSelector.length
Write-Host "Selected items in multilist: " $multiListSelector.length
 
if ($treeListSelector.length -ge 1) {
    $treeListSelector | Select-Object DisplayName, FullPath
}
 
if ($multiListSelector.length -ge 1) {
    $multiListSelector | Select-Object DisplayName, FullPath
}

Checkboxes and radio buttons with fixed values

If you want to include extra custom options that can be selected by the user, you can use checkboxes and radio buttons.

$radioOptions = [ordered]@{
    "Option 1 This is option number 1" = 1
    "Option 2 This is option number 2" = 2
    "Option 3 This is option number 3" = 3
}
 
$checkListOptions = [ordered]@{
    "Checkbox 1" = 1
    "Checkbox 2" = 2
    "Checkbox 3" = 3
}
 
$dialogParams = @{
    Title = "Dialog title"
    Description = "Description under title"
    OkButtonName = "Execute"
    CancelButtonName = "Close"
    ShowHints = $true
    Parameters = @(
        @{
            Name = "radioSelector"
            Title = "Radio Button Selector"
            Editor = "radio"
            Options = $radioOptions
            Tooltip = "Select an option"
        }
        @{
            Name = "checkListSelector"
            Title = "Checklist Selector"
            Editor = "checklist"
            Options = $checkListOptions
            Tooltip = "Select one or more options"
        }
    )
}
 
$dialogResult = Read-Variable @dialogParams

The following dialog will appear if you run this code snippet in PowerShell ISE:

Fixed options are defined at the start of the script, using the $radioOptions and $checkListOptions ordered hash tables. For both types of fields, use the Options parameter to assign the options to the field. For radio buttons, you can use custom HTML formatting for the options (this won’t work for checkbox lists). Use the Editor “radio” for radio buttons, and “checklist” for checkbox list.

If you need to specify a default selected value, use the Value parameter set to the option value you want to select (option values are the numbers next to the equals = sign in the ordered hash tables). For example, if in the first field you want the second option to be preselected when opening the window, and in the second field you want the first and third options preselected, do something like this in the field definitions:

@{
    Name = "radioSelector"
    Title = "Radio Button Selector"
    Editor = "radio"
    Options = $radioOptions
    Value = 2
    Tooltip = "Select an option"
}
@{
    Name = "checkListSelector"
    Title = "Checklist Selector"
    Editor = "checklist"
    Options = $checkListOptions
    Value = @(1, 3)
    Tooltip = "Select one or more options"
}

The radio button list will return a single value or $null if not selected. The checkbox list will return an array of the selected values, or an empty array if none are selected:

if ($radioSelector -ne $null) {
    Write-Host "Radio list value selected: " $radioSelector
} else {
    Write-Host "No radio list value selected."
}
 
if ($checkListSelector.length -ge 1) {
    Write-Host "Checklist values selected: " $checkListSelector
} else {
    Write-Host "No checklist values selected."
}

Miscellaneous Parameters

There are other parameters types that can be used to select date/time, users, and display read-only information:

$dialogParams = @{
    Title = "Dialog title"
    Description = "Description under title"
    OkButtonName = "Execute"
    CancelButtonName = "Close"
    ShowHints = $true
    Parameters = @(
        @{
            Name = "dateSelector"
            Title = "Date Selector"
            Value = [System.DateTime]::Now
            Tooltip = "Select a date"
        }
        @{
            Name = "dateTimeSelector"
            Title = "Date and Time Selector"
            Editor = "datetime"
            Value = [System.DateTime]::Now
            Tooltip = "Select a date and time"
        }
        @{
            Name = "userSelector"
            Title = "User Selector"
            Editor = "user"
            Value = $me
            Tooltip = "Select a user"
        }
        @{
            Title = "Info"
            Value = "Static information text"
            Editor = "info"
        }
    )
}
 
$dialogResult = Read-Variable @dialogParams

If you run this code snippet in PowerShell ISE, you will get the following dialog:

A date-only selector is defined as a regular text field, but with the Value parameter set at any System.DateTime object (in the example, set to the current system DateTime). It can also be defined without a Value, and with the Editor parameter set to “date”. A date-time selector is similar, but with the Editor set to “datetime”. It is always recommended to pre-set the Value to the current system date/time if possible.

The user selector is defined with Editor set to “user”. If you need to select multiple users, set it to “user multiple”. When the user clicks on the ellipsis (…) button, they will get the user selector screen.

Finally, you can include static text in your dialogs to instruct or inform the user about anything. You don’t need to specify a Name for this type of parameter, only specify a Title, Value, and Editor set to “info”.

The date or date/time fields return an object of type System.DateTime. As you might already know, System.DateTime is a struct, so it cannot be set to $null. If the user didn’t enter a date/time and there is no pre-set default value, it will return a[System.DateTime]::MinValue object, so you have to check for equality against this value. The user selector returns an array of strings, each string containing a username in the form “domain\username”. If no users are selected, it returns an empty array.

if ($dateTimeSelector -ne [System.DateTime]::MinValue) {
    Write-Host "Selected date/time: " $dateTimeSelector
} else {
    Write-Host "No date/time selected."
}
 
if ($userSelector.length -ge 1) {
    Write-Host "User(s) selected: " $userSelector
} else {
    Write-Host "No user(s) selected."
}

Summary of Options

The following is a quick summary of the options you can apply to each Parameter field:

• Name: always set this (except for Info fields), use a predefined naming convention such as camelCase.

• Title: required, title of the field displayed in bold in the dialog.

• Tooltip: optional, it displays an additional description under the field’s title. This is displayed ONLY if the ShowHints parameter is set to $true for the dialog (Read-Variable)

• Value: mostly optional, the default value for the field. For text fields, it pre-sets a text value. For radio/checklists, it pre-selects options. For date/time fields, it pre-sets the date/time. For user fields, it pre-sets the user (use $me for the current user)

• Editor: use to specify a UI editing field. See the examples in this post for details on each one.

• Placeholder: optional text placeholder (it is not a value for the field)

• Options: for radio and checklists, a hash table with the list of options and values.

• Source: for lists and dropdowns, the item path to restrict selectable items. For multiple selection lists, a parameterized string with data source and other restrictions/selection options.

• Root: for simple dropdowns, the Sitecore.Data.Items.Item object that is the root for the selectable items in the field.

In my next post I'll cover Validations for user-entered data in these fields.

• Part 1: Implementing User Input with Read-Variable in SPE

• Part 2: How to define fields in the dialog box using Parameters in Read-Variable

• Part 3: Read-Variable Parameter Validation in SPE