An Independent Sitecore Learning Resource

Menu

Read-Variable Validation with Sitecore PowerShell Extensions

Read-Variable Validation with Sitecore PowerShell Extensions

Author

Brandon Bruno

Published

July 15, 2020

Tags

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:

Example of a Read-Variable dialog window.

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:

Example of the error message output by the Mandatory parameter.

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:

All form fields in an error state.

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

Do you have questions, comments, or corrections for this post? Find me on Twitter: @SitecoreSpark