> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/powershell-universal/apps/interaction.md). # Interaction Build interactive PowerShell Universal apps using browser local storage, clipboard, downloads, toast, modal, JavaScript cmdlets, and PowerShell host features. ```powershell Invoke-UDRedirect https://devolutions.net/powershell-universal/ ``` Universal Apps enables the ability to create interactive websites with PowerShell. Several cmdlets provide feedback to the user, update components, read component state, and persist browser-local preferences. ## Clipboard You can set string data into the user's clipboard with `Set-UDClipboard`. ```powershell New-UDButton -Text 'Clipboard' -OnClick { Set-UDClipboard -Data 'Hello, there!' } ``` #### API * Set-UDClipboard ## Downloads You can start a download within the user's browser by using `Start-UDDownload`. Due to browser security, the user needs to take an action, such as clicking a button, to allow the download. `Start-UDDownload` is not suited for large file downloads. ```powershell New-UDButton -Text 'Download' -OnClick { Start-UDDownload -StringData 'Hello, World!' } ``` ## Local storage Use `Set-UDLocalStorage` and `Get-UDLocalStorage` to persist a user's app preferences in browser local storage. Values remain available after a page reload and when the user opens the same app later in the same browser profile. PowerShell Universal scopes stored values to the dashboard and browser. They are not shared with other users, browsers, or dashboards. Use these cmdlets from an interactive event handler so PowerShell Universal can communicate with the connected browser. Values are serialized with the PowerShell serializer before they are stored, so you can save and retrieve PowerShell objects and hashtables. `Get-UDLocalStorage` returns `$null` when the item does not exist. ```powershell New-UDForm -Content { New-UDTextbox -Id 'theme' -Label 'Theme' -Value 'Dark' New-UDTextbox -Id 'pageSize' -Label 'Page Size' -Value '25' } -OnSubmit { Set-UDLocalStorage -Name 'preferences' -Value @{ Theme = $EventData.theme PageSize = [int]$EventData.pageSize } Show-UDToast -Message 'Preferences saved.' } New-UDButton -Text 'Show preferences' -OnClick { $preferences = Get-UDLocalStorage -Name 'preferences' if ($null -eq $preferences) { Show-UDToast -Message 'No preferences have been saved.' return } Show-UDToast -Message "Theme: $($preferences.Theme); page size: $($preferences.PageSize)" } ``` Browser local storage is readable and modifiable by code running in the page. Do not store passwords, credentials, API keys, tokens, or other sensitive data in it. Treat stored values as user-controlled input. #### API * Set-UDLocalStorage * Get-UDLocalStorage ## Event Handlers Many components support event handlers in the form of script blocks. You may also see these referred to as endpoints, as that is what they were called in Universal Dashboard v2. These event handlers allow you to invoke PowerShell scripts when certain actions take place on the page. For example, you may have a button click that calls an event handler. This button shows a toast when clicked. You can include any valid PowerShell cmdlet within the event handler code. ```powershell New-UDButton -Text 'Click Me' -OnClick { Show-UDToast 'Hello!' } ``` ### Variable Scope Variables are automatically scoped into event handlers. You can access variables that you define outside of the event handler. ```powershell $MyVariable = "Hello!" New-UDButton -Text 'Click Me' -OnClick { Show-UDToast $MyVariable } ``` ### Event Data Some event handlers provide data as a string or as a hashtable. This depends on the event handler you are using. For example, the `New-UDButton` `-OnClick` event handler does not provide data. On the other hand, the `New-UDSelect` `-OnChange` provides event data. You can access the event data by using the `$Body` variable as a string, sometimes formatted as JSON, or by using the `$EventData` variable as a hashtable. ```powershell New-UDSelect -Option { New-UDSelectOption -Name 'One' -Value 1 New-UDSelectOption -Name 'Two' -Value 2 New-UDSelectOption -Name 'Three' -Value 3 } -OnChange { Show-UDToast -Message $EventData } ``` ## Forms ### Submit a Form You can force a form to submit using the `Invoke-UDForm` cmdlet. You can optionally enforce validation by including the `-Validate` parameter. ```powershell New-UDForm -Id 'form' -Content { New-UDTextbox -Id 'Text' -Label 'Submit Me' } -OnSubmit { Show-UDToast "Hello!" } New-UDButton -Text "Submit Form" -OnClick { Invoke-UDForm -Id 'form' } ``` ### Validate a Form You can force a form to validate by using `Test-UDForm`. ```powershell New-UDForm -Id 'form' -Content { New-UDTextbox -Id 'Text' -Label 'Submit Me' } -OnSubmit { Show-UDToast "Hello!" } -OnValidate { New-UDValidationResult } New-UDButton -Text "Submit Form" -OnClick { Test-UDForm -Id 'form' } ``` ## JavaScript You can invoke JavaScript from PowerShell by using the `Invoke-UDJavaScript` cmdlet. ```powershell New-UDButton -Text 'Alert Me' -OnClick { Invoke-UDJavaScript -JavaScript 'alert("Hello!")' } ``` #### API * Invoke-UDJavaScript ## Toast ### Show a toast You can use the `Show-UDToast` cmdlet to create a toast message that appears on the end user's webpage. It happens over a WebSocket and shows the toast immediately. ```powershell Show-UDToast -Message 'Hello, World!' ``` ### Show a toast with an icon Toasts support icons as strings. You can use all FontAwesome v5 icons. ```powershell Show-UDToast -Icon "Ad" -Message "Test" ``` ### Hide a toast Hide a toast based on the specified ID. ```powershell Show-UDToast -Message 'Hello, World!' -Id 'Toast' -Duration 30000 New-UDButton -Text 'Click' -OnClick { Hide-UDToast -Id 'Toast' } ``` ### API * Show-UDToast * Hide-UDToast ## Redirect You can redirect users to different pages using the `Invoke-UDRedirect` cmdlet. It happens over a WebSocket and redirects as soon as the cmdlet is called. ```powershell Invoke-UDRedirect http://www.ironmansoftware.com ``` `Invoke-UDRedirect` automatically redirects to pages in the dashboard when using a relative path. ```powershell Invoke-UDRedirect '/page1' ``` If you would like to redirect to a local path outside of the dashboard, use the `-Native` parameter. ```powershell Invoke-UDRedirect '/publishedFolder/test.txt' -Native ``` #### API * Invoke-UDRedirect ## Modal You can open a modal using the `Show-UDModal` cmdlet. It opens as soon as you call it. You can include whatever components you like within the modal. Read more about Modals here. ## Managing Component State You can manage component state dynamically by using the UDElement commands. ### Getting Component State You can receive the state of an element using `Get-UDElement`. The state is returned as a hashtable. This is primarily useful for input components. ```powershell $Value = (Get-UDElement -Id 'txtExample').value ``` ### Setting Component State Alternatively, you can set component state using `Set-UDElement`. You need to specify an ID and a hashtable of properties to set on the component. All built-in components support `Set-UDElement`. ```powershell New-UDTextbox -Id 'textbox' New-UDButton -Text 'Click' -OnClick { Set-UDElement -Id 'textbox' -Properties @{ Value = 'My Value' } } ``` ### Removing a component You can remove components from the page using `Remove-UDElement`. The component no longer appears on the page. ```powershell Remove-UDElement -Id 'txtExample' ``` ### Adding a component Add a child component to an existing parent component. ```powershell New-UDElement -Id 'myDiv' -Tag div New-UDButton -Text 'Click' -OnClick { Add-UDElement -ParentId 'myDiv' -Content { New-UDTypography -Text 'Hi' } } ``` ### Clear a component You can remove all child components from an existing component by using `Clear-UDElement`. ```powershell New-UDElement -Id 'myDiv' -Tag div New-UDButton -Text 'Click' -OnClick { Add-UDElement -ParentId 'myDiv' -Content { New-UDTypography -Text 'Hi' } Add-UDElement -ParentId 'myDiv' -Content { New-UDTypography -Text 'Hi' } Add-UDElement -ParentId 'myDiv' -Content { New-UDTypography -Text 'Hi' } } New-UDButton -Text 'Clear' -OnClick { Clear-UDElement -Id 'myDiv' } ``` ### Reloading a component Some components support reloading. You can trigger a reload of a component using `Sync-UDElement`. ```powershell New-UDDynamic -Id 'reloadMe' -Content { Get-Date } New-UDButton -Text 'Click' -OnClick { Sync-UDElement -Id 'reloadMe' } ``` ### Select a component You can select a component with `Select-UDElement`. ```powershell New-UDElement -Id 'txt' -Tag input -Properties @{ type = text } New-UDButton -Text 'Select' -OnClick { Select-UDElement -Id 'txt' -ScrollToElement } ``` ## PowerShell Host Integration Dashboards integrate directly with the PowerShell host to provide features based on standard cmdlets. ### Read-Host Using the `Read-Host` cmdlet causes a dialog to show on the user's dashboard. The text entered is returned by the cmdlet. ```powershell $Text = Read-Host 'Enter Some Text' Show-UDToast $Text ```
### Get-Credential Using `Get-Credential` causes a dialog to show that accepts a username and password. A `PSCredential` object is returned from the cmdlet. ```powershell Get-Credential -UserName "adam" ```
### Write-Progress Cmdlets that use the progress stream or `Write-Progress` result in a progress dialog. The popup shows the activity, percent completed, and current operation. ```powershell 1..100 | ForEach-Object { Write-Progress -PercentComplete $_ -Activity 'Processing...' -CurrentOperation "User $_" Start-Sleep -Milliseconds 500 } ```
You can disable the Write-Progress integration by setting `$ProgressPreference` to `SilentlyContinue`. ```powershell $ProgressPreference = 'SilentlyContinue' ``` ### Prompt for choice You can use the `$Host.UI.PromptForChoice` function to display a multi-select dialog. ```powershell $Title = "Welcome" $Info = "Just to Demo Prompt for Choice" $options = [System.Management.Automation.Host.ChoiceDescription[]] @("Power", "Shell", "Quit") [int]$defaultchoice = 2 $opt = $host.UI.PromptForChoice($Title, $Info, $Options, $defaultchoice) switch ($opt) { 0 { Show-UDToast "Power" } 1 { Show-UDToast "Shell" } 2 { Show-UDToast "Good Bye!!!" } } ```
### Write-Host `Write-Host` within apps writes to the **Log** tab in the Admin Console for the app. To receive these log messages in your browser's developer-tools console, enable console logging in `appsettings.json`. ```json { "UniversalDashboard": { "ConsoleLog": true } } ``` ## API * Get-UDElement * Set-UDElement * Clear-UDElement * Remove-UDElement * Sync-UDElement * Select-UDElement --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.devolutions.net/powershell-universal/apps/interaction.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.