Read-Variable Parameter Validation in SPE

Technology

Sitecore

Byron Calisto

May 24, 2019

Overview

In my previous post, I used examples demonstrating the different types of parameters (fields) that you can use in a user-input dialog generated by Read-Variable in Sitecore PowerShell. In this post I’m going to show how to do validations on these fields when the user tries to submit the information entered in the dialog.

Simple “Required” Validation

The simplest, built-in type of validation you can easily include in your fields is the “Required” validation. This works perfectly for any field that accepts empty values. It's as simple as adding the “Mandatory = $true” parameter to your field:

$dialogParams = @{
    Title = "Dialog title"
    Description = "Description under title"
    OkButtonName = "Execute"
    CancelButtonName = "Close"
    ShowHints = $true
    Parameters = @(
        @{
            Name = "textBox"
            Title = "Text Box"
            Tooltip = "Enter any text"
            Mandatory = $true
        }
    )
}
 
$dialogResult = Read-Variable @dialogParams

Run this snippet in your PowerShell ISE, and press on the Execute button without entering anything in the text box. You will get a validation error message in red under the field:

The dialog can’t be submitted by the user until a value is provided to the field. Once you enter anything in the field and click Execute, and the dialog will validate correctly and close.

Custom Validation

Simple “required” validation works well for a large number of scenarios where you only need the user to select something or enter a simple value. But there are more complex cases where you need specific validations for your data. The Read-Variable function provides the Validator property that can contain a block of code with your custom validations. Let’s check the following example:

$dialogParams = @{
    Title = "Dialog title"
    Description = "Description under title"
    OkButtonName = "Execute"
    CancelButtonName = "Close"
    ShowHints = $true
    Parameters = @(
        @{
            Name = "textBox"
            Title = "Text Box"
            Tooltip = "'continue' (without the quotes) is the only valid value"
        }
    )
    Validator = {
        $enteredText = $variables.textBox.Value
         
        if ($enteredText -ne "continue") {
            $variables.textBox.Error = "Please enter 'continue' to proceed."
        }
    }
}
 
$dialogResult = Read-Variable @dialogParams

Run this script in PowerShell ISE. Enter any text except “continue” in the box and click on Execute. You will get a validation error:

If you enter “continue”, the dialog will validate correctly and close.

In the Validator code, you refer to each field in the dialog by using the $variables object. In the provided example, since our field is called “textBox”, the correct way to refer to it is using $variables.textBox. And since what we need to validate is the value entered by the user, we assign to a variable the Value property from textBox using $variables.textBox.Value. Remember that Value will be of the type that the field returns, in this case it is a string. But in other cases, such as using droptrees or lists, check the type they are returning so you can implement your validation logic correctly.

Once you have your value extracted, perform your validations. In the provided example, our validation is rather simple, it only checks that the entered text equals “continue”, otherwise it will fail. To handle the failure, you need to tell the user what the mistake is. To do this, use the Error property for the field. As you can see in the example, $variables.textBox.Error is assigned an error message, and that is the one that is displayed in bright red when the validation fails.

The following is another example using a droptree field where we want to restrict the selection to only one type of item. Droptrees do not have the built-in restrictions you can add to multilists and treelists, so this is an ideal scenario to use the Validator code. For this specific example, we will restrict the user from selecting ONLY Workflow State items (template ID{4B7E2DA9-DE43-4C83-88C3-02F042031D04}). If you select any other item, such as a Workflow item, you will get a validation error:

$dialogParams = @{
    Title = "Dialog title"
    Description = "Description under title"
    OkButtonName = "Execute"
    CancelButtonName = "Close"
    ShowHints = $true
    Parameters = @(
        @{
            Name = "workflowState"
            Title = "Select a Workflow State"
            Editor = "droptree"
            Source = "/sitecore/system/Workflows"
            Tooltip = "Please select a valid Workflow State."
            Mandatory = $true
        }
    )
    Validator = {
        $selectedState = $variables.workflowState.Value
 
        if ($selectedState.TemplateID -ne "{4B7E2DA9-DE43-4C83-88C3-02F042031D04}") {
            $variables.workflowState.Error = "Please choose a valid Workflow State."
        }
    }
}
 
$dialogResult = Read-Variable @dialogParams

Execute this code snippet in your PowerShell ISE. Select any item that isn’t a Workflow State:

Click on the Execute button. You will get a validation error since you did not select a Workflow State item:

Now select a Workflow State (any of the immediate children of any Workflow item):

Click on the Execute button. You will not get any validation errors, and the dialog will close.

Conclusion

Read-Variable is a powerful UI tool. It allows regular users (not only experienced Sitecore developers or admins) to execute PowerShell scripts. Best of all, it doesn’t need any SPEAK or front-end knowledge to implement, it is fully code-defined. In my next post, I will write about including your scripts in the Sitecore Desktop UI, so your system users can easily find and run your custom scripts without even touching any of the SPE interfaces.