Read-Variable Validation with Sitecore PowerShell Extensions

Sitecore PowerShell Extensions (SPE) comes with many custom cmdlets that tie into the Sitecore API and other components of the platform. The Read-Variable cmdlet display a highly-configurable UI for getting user input. This UI can be configured to use dozens of input types, including textboxes, dropdowns, radio, checkboxes, droptrees - the list goes on.

A simple UI might look like this:

Here's the code for that dialog:

$props = @{
    Title = "Create a Profile"
    Description = "Adds a new profile for incoming team members."
    OkButtonName = "Submit"
    CancelButtonName = "Cancel"
    Width = 500
    Height = 500
    Parameters = @(

		@{ Name = "fullName"; Title = "Full Name"; Editor = "text"; }

		@{ Name = "userBirthday"; Title = "Birthday"; Editor = "date"; }

        @{ Name = "profilePagePath"; Title = "Select an Item"; Editor = "droptree"; Source = "/sitecore/content/sites/profiles" }
    )
}

# Display the dialog window to the user
Read-Variable @props

It's important to validate user input, and the Read-Variable cmdlet offers a few ways to do that:

• Inline Mandatory parameter (accepts true or false values)
• Custom Validator parameter (a script block)

Let's focus on validation and take a look at both of these options.

Inline Mandatory Validation

Each form control defined in the Parameters property accepts an optional Mandatory parameter. This true/false value determines if a field is required. For example:

@{ Name = "fullName"; Title = "Full Name"; Editor = "text"; Mandatory = $true }

The resulting error message:

Custom Validator

Some validation goes beyond simply "required" or "not required." Read-Variable provides a Validator property that allows additional scripting to be used for executing custom validation logic. An example:

Validator = {

    # Ensure the user name isn't too long
    if ($variables.fullName.Value.Length -gt 25)
    {
        $variables.fullName.Error = "Username must be 25 characters or less."
    }

    # Ensure user age is a reasonable value
    $selectedValue = $variables.userBirthday.Value
    $minDate = Get-Date -Year 1900 -Month 1 -Day 1
    $maxDate = Get-Date

    if ($selectedValue -lt $minDate -or $selectedValue -gt $maxDate)
    {
        $variables.userBirthday.Error = "Birthday is out of range! Should be between 1900 and today."
    }

    # Ensure the user selected a valid root item for the profile page
    if ($variables.profilePagePath.TemplateName -ne 'Profile Folder')
    {
        $variables.profilePagePath.Error = "Please select a Profile folder."
    }

}

A few highlights from the above code:

• Any PowerShell code can be used in the script block, including cmdlets.
• $variables contains all the variables parsed and assigned from the Parameters property.
  • For example: @{ Name = 'fullName' } is referenced as $variables.fullName
• Each variable has a Value and Error property:
  • Value references the value selected by the user.
  • Error is the error message to be displayed on the form.

The above validation with all error states appears like this:

The full script:

$props = @{
    Title = "Create a Profile"
    Description = "Adds a new profile for incoming team members."
    OkButtonName = "Submit"
    CancelButtonName = "Cancel"
    Width = 500
    Height = 500
    Parameters = @(
		@{ Name = "fullName"; Title = "Full Name"; Editor = "text"; Mandatory = $true }
		@{ Name = "userBirthday"; Title = "Birthday"; Editor = "date"; }
        @{ Name = "profilePagePath"; Title = "Select an Item"; Editor = "droptree"; Source = "/sitecore/content/sites/profiles" }
    )

    Validator = {

        # Ensure the user name isn't too long
        if ($variables.fullName.Value.Length -gt 25)
        {
            $variables.fullName.Error = "Username must be 25 characters or less."
        }
    
        # Ensure user age is a reasonable value
        $selectedValue = $variables.userBirthday.Value
        $minDate = Get-Date -Year 1900 -Month 1 -Day 1
        $maxDate = Get-Date
    
        if ($selectedValue -lt $minDate -or $selectedValue -gt $maxDate)
        {
            $variables.userBirthday.Error = "Birthday is out of range! Should be between 1900 and today."
        }
    
        # Ensure the user selected a valid root item for the profile page
        if ($variables.profilePagePath.TemplateName -ne 'Profile Folder')
        {
            $variables.profilePagePath.Error = "Please select a Profile folder."
        }

    }
}

# Display the dialog window to the user
Read-Variable @props

Further Reading

• Read-Variable cmdlet documentation
• Read-Variable cmdlet source code