# Interactive Dialogs

We've provided a few commands to interact with the user through dialogs.

## Simple Dialogs

Simple in the sense that the dialogs present the user with a short message and one or two buttons.

### Alert

The *Alert* dialog is a way to notify the user of important information with an "OK" button.

**Example:** The following display a modal dialog.

```powershell
Show-Alert -Title "SPE is great!"
```

No return value.

![Show Alert](https://165468320-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LA37Eh9vuWwQHUTc2NT%2Fuploads%2Fgit-blob-c9270954bd675f2e1452da04eb9a6de71f730ce5%2Fmodaldialog-showalert.png?alt=media)

### Confirmation

The *Confirmation* dialog is a way to verify with the user before proceeding.

**Example:** The following displays a modal dialog with an OK or Cancel confirmation.

```powershell
Show-Confirm -Title "Click OK to acknowledge SPE is great!"
```

| Button Name | Return Value |
| ----------- | ------------ |
| OK          | yes          |
| Cancel      | no           |

![Show Confirm](https://165468320-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LA37Eh9vuWwQHUTc2NT%2Fuploads%2Fgit-blob-181f53dbce0cb477afda199c0d817f87351e91e9%2Fmodaldialog-showconfirm.png?alt=media)

### User Input

**Example:** The following displays an input dialog for text.

```powershell
Show-Input "Please provide 5 characters at most" -MaxLength 5
```

| Button Name | Return Value   |
| ----------- | -------------- |
| OK          | < user input > |
| Cancel      | $null          |

![Show Input](https://165468320-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LA37Eh9vuWwQHUTc2NT%2Fuploads%2Fgit-blob-da72b8bd383d3f53caea8a221c34f5b21885ff30%2Fmodaldialog-showinput.png?alt=media)

**Example:** The following displays an input dialog with a error validation message.

```powershell
$inputProps = @{
    Prompt = "Enter a new name for the item:"
    Validation = [Sitecore.Configuration.Settings]::ItemNameValidation
    ErrorMessage = "'`$Input' is not a valid name."
    MaxLength = [Sitecore.Configuration.Settings]::MaxItemNameLength
}

Show-Input @inputProps
```

![Show Input](https://165468320-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LA37Eh9vuWwQHUTc2NT%2Fuploads%2Fgit-blob-fcd34377720f531241513e22b2a33311d5da2ed7%2Fmodaldialog-showinput-errortext.png?alt=media)

## Advanced Dialogs

### Variable Settings

The `Read-Variable` command provides a way to prompt the user for information and then generate variables with those values.

**Example:** The following displays a dialog with a dropdown.

**Note:** The name *selectedOption* will result in a variable that contains the selected option.

```powershell
$options = @{
    "A"="a"
    "B"="b"
}

$props = @{
    Parameters = @(
        @{Name="selectedOption"; Title="Choose an option"; Options=$options; Tooltip="Choose one."}
    )
    Title = "Option selector"
    Description = "Choose the right option."
    Width = 300
    Height = 300
    ShowHints = $true
}

Read-Variable @props
```

| Button Name   | Return Value  |
| ------------- | ------------- |
| OK            | ok            |
| Cancel        | cancel        |
| < variables > | < selection > |

![Read Variable](https://165468320-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LA37Eh9vuWwQHUTc2NT%2Fuploads%2Fgit-blob-e9e3ac90e2a17b92605a536931184107a1a6dabe%2Fmodaldialog-readvariable.png?alt=media)

**Supported Parameter Values**

| Key                    | Type                                | Description                                          | Example                   |
| ---------------------- | ----------------------------------- | ---------------------------------------------------- | ------------------------- |
| Name                   | string                              | Variable name                                        | isSilent                  |
| Value                  | bool string int float datetime Item | Default value                                        | $true                     |
| Title                  | string                              | Header or Label                                      | "Proceed Silently         |
| Tooltip (optional)     | string                              | Short description or tooltip                         | "Check to run quietly     |
| Tab (optional)         | string                              | Tab title                                            | "Simple"                  |
| Placeholder (optional) | string                              | Textbox placeholder                                  | "Search text..."          |
| Lines (optional)       | int                                 | Line count                                           | 3                         |
| Editor (optional)      | string                              | Control type                                         | "date time"               |
| Domain (optional)      | string                              | Domain name for security editor                      | "sitecore"                |
| Options (optional)     | string OrderedDictionary Hashtable  | Data for checklist or dropdown                       | @{"Monday"=1;"Tuesday"=2} |
| Columns                | int string                          | Number between 1 and 12 and string 'first' or 'last' | 6 first                   |

**Editor Types**

* bool
* check
* date
* date time
* droplist
* droptree
* email
* groupeddroplink
* groupeddroplist
* info
* item
* link
* marquee
* multilist
* multilist search
* multiple user
* multiple user role
* multiple role
* multitext
* number
* pass
* radio
* rule
* rule action
* tree
* treelist
* tristate
* time

### Confirmation Choice

The *Confirmation Choice* dialog allows for multiple combinations like that seen with a "Yes, Yes to all, No, No to all" scenario.

**Example:** The following displays a modal dialog with choices.

```powershell
Show-ModalDialog -Control "ConfirmChoice" -Parameters @{btn_0="Yes - returns btn_0"; btn_1="No - returns btn_1"; btn_2="returns btn_2"; te="Have you downloaded SPE?"; cp="Important Questions"} -Height 120 -Width 650
```

**Note:** The hashtable keys should be incremented like *btn\_0*, *btn\_1*, and so on. The return value is the key name.

| Button Name       | Return Value |
| ----------------- | ------------ |
| < first button >  | btn\_0       |
| < second button > | btn\_1       |
| < third button >  | btn\_2       |

![Show Confirm Choice](https://165468320-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LA37Eh9vuWwQHUTc2NT%2Fuploads%2Fgit-blob-069050eff91234fa4a7eaab6e6f088be3b73a5a5%2Fmodaldialog-showconfirmchoice.png?alt=media)

### Upload

The *Upload* dialog provides a way to upload files from a local filesystem to the media library or server filesystem.

**Example:** The following displays an advanced upload dialog.

```powershell
Receive-File (Get-Item "master:\media library\Files") -AdvancedDialog
```

No return value.

![Receive File](https://165468320-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LA37Eh9vuWwQHUTc2NT%2Fuploads%2Fgit-blob-7af5b8ba9157ca862905cdafab4098f056dc6774%2Fmodaldialog-receivefileadvanced.png?alt=media\&token=e65c19f8-275a-4b8d-a5e8-6ee4f4c97a84)

### Download

The *Download* dialog provides a way to download files from the server to a local filesystem.

**Example:** The following displays a download dialog.

```powershell
Get-Item -Path "master:\media library\Files\readme" | Send-File
```

![Download](https://165468320-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LA37Eh9vuWwQHUTc2NT%2Fuploads%2Fgit-blob-d61d1dc19a5183d0c5507fb80ee4a8a77824e35f%2Fmodaldialog-download.png?alt=media)

### Field Editor

The *Field Editor* dialog offers a convenient way to present the user with fields to edit.

**Example:** The following displays a field editor dialog.

```powershell
Get-Item "master:\content\home" | Show-FieldEditor -Name "*" -PreserveSections
```

| Button Name | Return Value |
| ----------- | ------------ |
| OK          | ok           |
| Cancel      | cancel       |

![Show Field Editor](https://165468320-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LA37Eh9vuWwQHUTc2NT%2Fuploads%2Fgit-blob-6a734d266edafe38f434541a2959185901a5a7d7%2Fmodaldialog-showfieldeditor.png?alt=media)

### File Browser

The *File Browser* is an obvious choice when you need to upload, download, or delete files.

**Example:** The following displays a file browser dialog for installation packages.

```powershell
Show-ModalDialog -HandleParameters @{
    "h"="Create an Anti-Package";
    "t" = "Select a package that needs an anti-package";
    "ic"="People/16x16/box.png";
    "ok"="Pick";
    "ask"="";
    "path"= "packPath:$SitecorePackageFolder";
    "mask"="*.zip";
} -Control "Installer.Browse"
```

| Button Name | Return Value      |
| ----------- | ----------------- |
| OK          | < selected file > |
| Cancel      | undetermined      |

![Show File Browser](https://165468320-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LA37Eh9vuWwQHUTc2NT%2Fuploads%2Fgit-blob-aef41f4d5dd6fe45c998736bd5b885635c6787e1%2Fmodaldialog-showfilebrowser.png?alt=media)

**Example:** The following displays a simple file browser dialog.

```powershell
Show-ModalDialog -HandleParameters @{
    "h"="FileBrowser";
} -Control "FileBrowser" -Width 500
```

| Button Name | Return Value      |
| ----------- | ----------------- |
| OK          | < selected file > |
| Cancel      | undetermined      |

![Show File Browser](https://165468320-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LA37Eh9vuWwQHUTc2NT%2Fuploads%2Fgit-blob-bb4378470cfbb32db972ef600c4e5bfbed7a340f%2Fmodaldialog-simplefilebrowser.png?alt=media\&token=370026fa-acd6-4748-9c62-1ecacf10cd35)

**Example:** The following displays a Sheer UI control without any additional parameters.

```powershell
Show-ModalDialog -Control "SetIcon"
```

### Data List

The "Data List" is essentially a report viewer which supports custom actions, exporting, and filtering.

**Example:** The following displays a list view dialog with the child items under the Sitecore tree.

```powershell
Get-Item -Path master:\* | Show-ListView -Property Name, DisplayName, ProviderPath, TemplateName, Language
```

![Show List View](https://165468320-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LA37Eh9vuWwQHUTc2NT%2Fuploads%2Fgit-blob-f848a5abbe060cc78399549b0eb8a920e850b180%2Fmodaldialog-showlistview.png?alt=media)

### Results

The *Results* dialog resembles the Console but does not provide a prompt to the user. This is useful for when logging messages.

**Example:** The following displays a dialog with the all the information written to the ScriptSession output buffer.

```powershell
for($i = 0; $i -lt 10; $i++) {
    Write-Verbose "Index = $($i)" -Verbose
}

Show-Result -Text
```

![Show Result Text](https://165468320-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LA37Eh9vuWwQHUTc2NT%2Fuploads%2Fgit-blob-3634638300284b9d94c7a21ae3bf59f68c7b7da3%2Fmodaldialog-showresulttext.png?alt=media)