Read-Variable
Prompts user to provide values for variables required by the script to perform its operation.
Syntax
1
Read-Variable [-Parameters <Object[]>] [-Description <String>] [-CancelButtonName <String>] [-OkButtonName <String>] [-ShowHints] [-Validator <ScriptBlock>] [-Title <String>] [-Width <Int32>] [-Height <Int32>]
Copied!
Detailed Description
Prompts user to provide values for variables required by the script to perform its operation. If user selects the "OK" button the command will return 'ok' as its value. If user selects the "Cancel" button or closes the window with the "x" button at the top-right corner of the dialog the command will return 'cancel' as its value.
© 2010-2019 Adam Najmanowicz, Michael West. All rights reserved. Sitecore PowerShell Extensions
Parameters
-Parameters <Object[]>
Specifies the variables that value should be provided by the user. Each variable definition can have the following structure:
- Name - the name of the PowerShell variable - without the $ sign
- Value - the initial value of the variable - if the variable have not been created prior to launching the dialog - this will be its value unless the user changes it. if Value is not specified - the existing variable name will be used.
- Title - The title for the variable shown above the variable editor.
- Tooltip - The hint describing the parameter further - if the -ShowHints parameter is provided this value will show between the Variable Title and the variable editor.
- Editor - If the default editor selected does not provide the functionality expected - you can specify this value to customize it (see examples)
- Tab - if this parameter is specified on any Variable the multi-tab dialog will be used instead of a simple one. Provide the tab name on which the variable editor should appear.
Variable type specific:
- Root - for some Item selecting editors you can provide this to limit the selection to only part of the tree
- Source - for some Item selecting editors you can provide this to parametrize the item selection editor. (Refer to examples for some sample usages)
- Lines - for String variable you can select this parameter if you want to present the user with the multiline editor. The for this parameter is the number of lines that the editor will be configured with.
- Domain - for user and role selectors you can limit the users & roles presented to only the domain - specified)
Aliases
​
Required?
false
Position?
named
Default Value
​
Accept Pipeline Input?
false
Accept Wildcard Characters?
false
-Description <String>
Dialog description displayed below the dialog title.
Aliases
​
Required?
false
Position?
named
Default Value
​
Accept Pipeline Input?
false
Accept Wildcard Characters?
false
-CancelButtonName <String>
Text shown on the cancel button.
Aliases
​
Required?
false
Position?
named
Default Value
​
Accept Pipeline Input?
false
Accept Wildcard Characters?
false
-OkButtonName <String>
Text shown on the OK button.
Aliases
​
Required?
false
Position?
named
Default Value
​
Accept Pipeline Input?
false
Accept Wildcard Characters?
false
-ShowHints <SwitchParameter>
Specifies whether the variable hints should be displayed. Hints are shown below each the variable title but above the variable editing control.
Aliases
​
Required?
false
Position?
named
Default Value
​
Accept Pipeline Input?
false
Accept Wildcard Characters?
false
-Validator <ScriptBlock>
Aliases
​
Required?
false
Position?
named
Default Value
​
Accept Pipeline Input?
false
Accept Wildcard Characters?
false
-Title <String>
Dialog title - shown at the top of the dialog.
Aliases
​
Required?
false
Position?
named
Default Value
​
Accept Pipeline Input?
false
Accept Wildcard Characters?
false
-Width <Int32>
Dialog width.
Aliases
​
Required?
false
Position?
named
Default Value
​
Accept Pipeline Input?
false
Accept Wildcard Characters?
false
-Height <Int32>
Dialog width.
Aliases
​
Required?
false
Position?
named
Default Value
​
Accept Pipeline Input?
false
Accept Wildcard Characters?
false
Inputs
The input type is the type of the objects that you can pipe to the cmdlet.
- Sitecore.Data.Items.Item
Outputs
The output type is the type of the objects that the cmdlet emits.
- System.String
Notes
Help Author: Adam Najmanowicz, Michael West
Examples
EXAMPLE 1
The following provides a dialog with a dropdown of options.
1
$options = @{
2
"A"="a"
3
"B"="b"
4
}
5
​
6
$props = @{
7
Parameters = @(
8
@{Name="selectedOption"; Title="Choose an option"; Options=$options; Tooltip="Choose one."}
9
)
10
Title = "Option selector"
11
Description = "Choose the right option."
12
Width = 300
13
Height = 300
14
ShowHints = $true
15
}
16
​
17
Read-Variable @props
Copied!
EXAMPLE 2
Following is an example of a simple dialog asking user for various variable types.
The type of some of the controls displayed to the user are iferred from the variable type (like the $item variable or DateTime) The editors for some other are set by providing the "editor" value
1
$item = Get-Item master:\content\home
2
$result = Read-Variable -Parameters `
3
@{ Name = "someText"; Value="Some Text"; Title="Single Line Text"; Tooltip="Tooltip for singleline"; Placeholder="You see this when text box is empty"},
4
@{ Name = "multiText"; Value="Multiline Text"; Title="Multi Line Text"; lines=3; Tooltip="Tooltip for multiline"; Placeholder="You will see this when text box is empty"},
5
@{ Name = "from"; Value=[System.DateTime]::Now.AddDays(-5); Title="Start Date"; Tooltip="Date since when you want the report to run"; Editor="date time"},
6
@{ Name = "user"; Value=$me; Title="Select User"; Tooltip="Tooltip for user"; Editor="user multiple"},
7
@{ Name = "item"; Title="Start Item"; Root="/sitecore/content/"} `
8
-Description "This Dialog shows less editors, it doesn't need tabs as there is less of the edited variables" `
9
-Title "Initialise various variable types (without tabs)" -Width 500 -Height 480 -OkButtonName "Proceed" -CancelButtonName "Abort"
Copied!
EXAMPLE 3
Following is an example of a multi tabbed dialog asking user for various variable types.
The type of some of the controls displayed to the user are inferred from the variable type (like the $item variable or DateTime) The editors for some other are set by providing the "editor" value
1
$item = Get-Item master:\content\home
2
$result = Read-Variable -Parameters `
3
@{ Name = "silent"; Value=$true; Title="Proceed Silently"; Tooltip="Check this if you don't want to be interrupted"; Tab="Simple"},
4
@{ Name = "someText"; Value="Some Text"; Title="Text"; Tooltip="Just a single line of Text"; Tab="Simple"; Placeholder="You see this when text box is empty"},
5
@{ Name = "multiText"; Value="Multiline Text"; Title="Longer Text"; lines=3; Tooltip="You can put multi line text here"; Tab="Simple"; Placeholder="You see this when text box is empty"},
6
@{ Name = "number"; Value=110; Title="Integer"; Tooltip="I need this number too"; Tab="Simple"},
7
@{ Name = "fraction"; Value=1.1; Title="Float"; Tooltip="I'm just a bit over 1"; Tab="Simple"},
8
@{ Name = "from"; Value=[System.DateTime]::Now.AddDays(-5); Title="Start Date"; Tooltip="Date since when you want the report to run"; Editor="date time"; Tab="Time"},
9
@{ Name = "fromDate"; Value=[System.DateTime]::Now.AddDays(-5); Title="Start Date"; Tooltip="Date since when you want the report to run"; Editor="date"; Tab="Time"},
10
@{ Name = "item"; Title="Start Item"; Root="/sitecore/content/"; Tab="Items"},
11
@{ Name = "items"; Title="Bunch of Templates";
12
Source="DataSource=/sitecore/templates&DatabaseName=master&IncludeTemplatesForDisplay=Node,Folder,Template,Template Folder&IncludeTemplatesForSelection=Template";
13
editor="treelist"; Tab="Items"},
14
@{ Name = "items2"; Title="Bunch of Templates";
15
Source="DataSource=/sitecore/templates&DatabaseName=master&IncludeTemplatesForDisplay=Node,Folder,Template,Template Folder&IncludeTemplatesForSelection=Template";
16
editor="multilist"; Tab="More Items"},
17
@{ Name = "items3"; Title="Pick One Template";
18
Source="DataSource=/sitecore/templates&DatabaseName=master&IncludeTemplatesForDisplay=Node,Folder,Template,Template Folder&IncludeTemplatesForSelection=Template";
19
editor="droplist"; Tab="More Items"},
20
@{ Name = "user"; Value=$me; Title="Select User"; Tooltip="Tooltip for user"; Editor="user multiple"; Tab="Rights"},
21
@{ Name = "role"; Title="Select Role"; Tooltip="Tooltip for role"; Editor="role multiple"; Domain="sitecore"; Tab="Rights"}, `
22
@{ Name = "userOrRole"; Title="Select User or Role"; Tooltip="Tooltip for role"; Editor="user role multiple"; Domain="sitecore"; Tab="Rights" } `
23
-Description "This Dialog shows all available editors in some configurations, the properties are groupped into tabs" `
24
-Title "Initialise various variable types (with tabs)" -Width 600 -Height 640 -OkButtonName "Proceed" -CancelButtonName "Abort" -ShowHints
25
if($result -ne "ok")
26
{
27
Exit
28
}
Copied!
Related Topics
Last modified 2yr ago
Export as PDF
Copy link