Dashboards can contain one or more pages. The simplest dashboard will contain a single page with some content. You can call any PowerShell cmdlet that is available on your machine to populate your dashboard.

Here's an example of simple dashboard that displays some text.

New-UDDashboard -Title 'My New Dashboard' -Content {
    New-UDTypography -Text 'Hello!'
}

New-UDDashboard

The top-level cmdlet for dashboards is New-UDDashboard. You need to call it when returning a dashboard. You can use it with or without pages.

Content

The content of the dashboard is a series of components to display on the page. It's a script block that will return all the components in the order they will be rendered on the page. You can use the Grid component to layout items and display things like text with typography.

New-UDDashboard -Title 'My New Dashboard' -Content {
    New-UDTypography -Text 'Hello!'
}

Header Customization

You can customize the header of the dashboard using several parameters.

To change the navigation layout, use the -Navigation and -NavigationLayout parameters.

New-UDDashboard -Content {
} -Navigation (
    New-UDList -Children {
        New-UDListItem -Label "Home"
        New-UDListItem -Label "Getting Started" -Children {
            New-UDListItem -Label "Installation" -OnClick {}
            New-UDListItem -Label "Usage" -OnClick {}
            New-UDListItem -Label "FAQs" -OnClick {}
            New-UDListItem -Label "System Requirements" -OnClick {}
            New-UDListItem -Label "Purchasing" -OnClick {}
        }
    }
) -NavigationLayout permanent

Components

Components are the individual widgets that you can place on you dashboard. There are components for displaying data, taking user input, adding text and images and more. Components can be downloaded as PowerShell modules and added to your dashboard.

Components are be caused using the standard verb-name syntax for any PowerShell cmdlet.

New-UDPage -Content {
    New-UDTextbox
}

Learn more about components here.

Pages

You can specify multiple pages within a dashboard. Each page defines a route. As for v3, all pages are dynamic. PowerShell will execute on each page load to render the new page. Since UD is a single page application, the web browser does not need to refresh the entire web page when navigating between the different dashboard pages.

$Pages = @()
$Pages += New-UDPage -Name 'My Home Page' -Content {}
$Pages += New-UDPage -Name 'Diagnostics' -Content {}
New-UDDashboard -Pages $Pages -Title 'Dashboard'

Learn more about Pages here.

Built-in Variables

Built-in variables can be found on the variables page.

Debugging

When building a dashboard, you will likely run into issues with cmdlet calls or syntax. Dashboards will auto reload as you make changes to the dashboard files. If a dashboard fails to start, you can navigate to the admin page, click Dashboards and click the Info button next to your dashboard.

The Log tab will show all the logging coming from the PowerShell execution from within in your dashboard. This should allow you to easily see errors and warnings coming from your dashboard.

You can use Write-Debug to add additional log messages to your dashboard. To enable debug logging, you will have to set the $DebugPreference variable at the top of your dashboard script.

$DebugPreference = 'Continue'

Menu

You can customize the dashboard menu by using the -Menu parameter.

New-UDDashboard -Title 'Dashboard' -Content {

} -Menu {
    New-UDMenuItem -Text 'Profile' -OnClick {
        Show-UDModal -Content {
            New-UDTypography -Text 'Welcome to your profile!'
        }
    }
}

Dashboards are individual websites created with Universal Dashboard. You can define settings for a dashboard and start and stop the dashboard from within the Universal administrative interface.

Adding a Dashboard

Dashboards can be added to Universal using the Add Dashboard button from the Dashboard / Dashboards page.

Name

Name is displayed throughout the UI and returned from the Universal cmdlets.

Base URL

The base URL is the URL that you will access to view this dashboard. This URL needs to be unique within this instance. You can specify the / root URL if you wish. You will have to visit /admin to login to the administrative page if you set the dashboard to the root URL.

File Name

The full file name to the dashboard file. This file needs to return a dashboard using New-UDDashboard.

Environment

The environment to run the dashboard within.

Authentication

Enables authentication for the dashboard.

Roles

Defines the role that is required to access the dashboard.

AutoStart

Determines whether the dashboard should start (or restart) when the server starts or changes are made to the dashboard files.

Starting and Stopping Dashboards

Similar to jobs, dashboards run in separate PowerShell processes. You can start and stop a dashboard process by clicking the Start or Stop button from the Dashboards page.

Viewing Diagnostic Information

You can view diagnostic information for a dashboard by clicking the Info button on the Dashboards page. This will show your start information for the dashboard as well as any error that were encountered when starting the dashboard.

Viewing the Dashboard

You can view the dashboard by clicking the View button. This will take you to the Base URL for the dashboard.

Executing Commands with the Dashboard

On the dashboard information page, click on the Console tab to view the UD console. The console allows you to run scripts from within the UD runspace so you can better debug the state of your script. You can evaluate variables and run commands that are available to the dashboard. You will be running in the context of your user in regards to the runspace but the process will be running as the service account user.

Persistent Runspaces

Persistent runspaces allow you to maintain runspace state within your dashboard endpoints. This is important for users that perform some sort of initialization within their endpoints that they do not want to execute on subsequent calls.

By default, runspaces will be reset after each execution. This will cause variables, modules and functions defined during the execution of an endpoint.

To enable persistent runspaces, you will need to configure an environment for your API. Set the -PersistentRunspace parameter to enable this feature. This is configured in the environments.ps1 script.

New-PSUEnvironment -Name 'Env' -Path 'powershell.exe' -PersistentRunspace

You will need to ensure that the environment is used by the dashboard.

Automatically Granting App Tokens

You can automatically grant app tokens to users that visit dashboards. This is useful if you want to invoke the management API for PowerShell Universal from within a dashboard. Your dashboard will need to have authentication enabled and you will have to use the -GrantAppToken switch parameter on New-PSUDashboard.

New-PSUDashboard -Name 'Dashboard' -BaseUrl '/' -Framework "UniversalDashboard:Latest" -Authenticated -GrantAppToken

From within your dashboard, you can now invoke the management API without having to worry about app token management. The API will be invoked in the context of the user that is visiting the dashboard.

New-UDDashboard -Title "Hello, World!" -Content {
    New-UDButton -Text 'Job' -OnClick {
        Invoke-UAScript -Name 'Test.ps1'
    }
}

Disable Error Toasts

By default, dashboards will display a toast message when an error is generated within an endpoint script. To avoid this behavior, you can use the -DisableErrorToast parameter of New-UDDashboard

New-PSUDashboard -Name 'Dashboard' -BaseUrl '/' -Framework "UniversalDashboard:Latest" -Authenticated -DisableErrorToast

New-UDDashboard -Title "Hello, World!" -Content {
    New-UDButton -Text 'Job' -OnClick {
        throw "Exception
    }
} 

Disable Startup Logging

When starting a dashboard, information about the variables and modules is displayed within the dashboard log. If you wish to suppress this information, you can use the -DisableStartupLogging parameter.

New-PSUDashboard -Name 'Dashboard' -BaseUrl '/' -Framework "UniversalDashboard:Latest" -DisableStartupLogging

Variables Available in Dashboards

Built-in variables are listed on the variables page.

A Universal Dashboard website is composed of components. In addition to the core component, you can also extend Universal Dashboard with a large set of community created components.

There are two non-framework components that are built into PSU. These include the Nivo charts library as well as the UDMap component. Additional components can be downloaded from the UD Marketplace.

External components are distributed as PowerShell modules and can be used in a dashboard by using Import-Module.

When building a dashboard, you can simply call the PowerShell cmdlets within your dashboard script to create a new component.

New-UDDashboard -Title 'Dashboard' -Content {
    New-UDTypography -Text 'Hello, world!'
}

Adding Components to Dashboards

You can add component modules by clicking the Components button on the Dashboard page and then adding the components. This list will also include components downloaded from the Marketplace.

Component Storage

Each version of PowerShell Universal includes some built in components. These components are included in the local installation directory. During start up, they are deployed to the assets folder. By default, this folder is %ProgramData%\PowerShellUniversal\Dashboard\Components .

You can change the assets folder by updating appsettings.json.

  "UniversalDashboard": {
    "AssetsFolder": "%ProgramData%\\PowerShellUniversal\\Dashboard",
  },

Manual Component Installation

You can manually install components into the assets folder by including the appropriate folder structure and files. All components need to be valid PowerShell modules.

Each component should be in a folder with the module name and an additional folder with the version.

Including Components in the Repository

You can also include components within the code Repository. By including them in the repository, they will be downloaded when using git sync. This functionality is only enabled when git sync is enabled.

After a git pull is performed on the remote repository, Components will be automatically loaded and available within the Components page within PowerShell Universal. The structure and layout of the components folder is the same as the main assets folder.

Display Processes

This example displays processes in a table.

New-UDDashboard -Title 'Processes' -Content {
    $Processes = Get-Process | Select-Object Id, Name
    New-UDTable -Columns @(
        New-UDTableColumn -Property 'Id' -Title 'Id'
        New-UDTableColumn -Property 'Name' -Title 'Name'
    ) -Data $Processes -ShowPagination
}

File System Browser

Create a file system browser with a dynamic tree view.

New-UDDashboard -Title 'Processes' -Content {
    Get-PSDrive -PSProvider 'FileSystem' | ForEach-Object {
        New-UDTreeView -Node { New-UDTreeNode -Name $_.Name -Id "$($_.Name):\" } -OnNodeClicked {
            Get-ChildItem $EventData.Id | ForEach-Object {
                New-UDTreeNode -Name $_.Name -Id $_.FullName -Leaf:$(-not $_.PSIsContainer)
            }
        }
    }
}

Create User Form

This example shows how to create a local user account.

New-UDDashboard -Title 'New User' -Content {
    New-UDForm -Content {
        New-UDTextbox -Id 'UserName' -Label "User Name"
        New-UDTextbox -Id 'Password' -Label 'Password' -Type 'password'
    } -OnSubmit {
        $Password = $EventData.Password | ConvertTo-SecureString -AsPlainText
        New-LocalUser -Name $EventData.UserName -Password $Password
        Show-UDToast "New user $($EventData.UserName) was created!"
    }
}

Clock

This example shows how to create a clock component in PowerShell Universal Dashboard.

New-UDDashboard -Title 'Clock' -Content {
    New-UDDynamic -Id 'clock' -Content {
        (Get-Date).ToString('T')
    } -AutoRefresh -AutoRefreshInterval 1
    
    New-UDButton -Text 'Toggle Clock' -OnClick {
        Set-UDElement -Id 'clock' -Properties @{
            autoRefresh = -not( (Get-UDElement -Id 'clock').AutoRefresh)
        }
    }
}

New-UDDynamic allows you to define a dynamic region. Pages themselves are dynamic in nature. This means that every time a page is loaded, it runs the PowerShell for that page. Sometimes, you may want to reload a section of a page rather than the whole page itself. This is when you will want to use dynamic regions.

Basic Dynamic Region

This dynamic region reloads when the button is clicked.

New-UDDashboard -Title "Hello, World!" -Content {
    New-UDDynamic -Id 'date' -Content {
        New-UDTypography -Text "$(Get-Date)"
    }

    New-UDButton -Text 'Reload Date' -OnClick { Sync-UDElement -Id 'date' }
}

Arguments List

An array of arguments may be passed to the dynamic region.

New-UDDynamic -Id 'dynamic_01' -Content {
                New-UDTypography -Text "This is an $($ArgumentList[0])
                 an $($ArgumentList[1]) in a UDDynamic"
                 } -ArgumentList @('example of', 'arguments list') 

Auto Refresh

Dynamic regions enable the ability to auto refresh components after a certain amount of time. The entire region's script block will be run when autorefreshing.

    New-UDDynamic -Id 'date' -Content {
        New-UDTypography -Text "$(Get-Date)" -Variant h3
        New-UDTypography -Text "$(Get-Random)" -Variant h3
    } -AutoRefresh -AutoRefreshInterval 1

Loading Component

Sometimes refreshing a dynamic component may take some time. For example, if you are querying another service's REST API or a data. Dynamic regions support configuration of the component that shows when the region is reloading. By default, nothing is shown. This can be any Universal Dashboard component.

    New-UDDynamic -Content {
        Start-Sleep -Seconds 3
        New-UDTypography -Text "Done!"
    } -LoadingComponent {
        New-UDProgress -Circular
    }

API

New-UDDynamic

You can define static HTML using New-UDHtml. This cmdlet does not create React components but rather allows you to define static HTML. Any valid HTML string is supported.

The following creates an unordered list.

API

The New-UDErrorBoundary component is used for isolating portions of a dashboard to contain components that may throw an error. Many Universal Dashboard components use the error boundary component internally.

If you'd like to isolate a portion of your dashboard to prevent the entire page from failing to load, you can use the following syntax.

If any error is thrown from the content, you will see an error such as thing.

API

Components in PowerShell Universal Dashboard are exposed as functions. You can combine built in components to produce your own custom components.

Example: People Picker

This example users a published folder of avatars.

A dashboard can consist of one or more pages. A page can have a particular name and URL. You can define a URL that accepts one or more variables in the URL to define a dynamic page.

Creating a new page

Within the dashboard editor, expand the Pages navigation menu and click New Page.

You can edit a page by clicking the link in the menu. The code editor will switch to the page's content.

To reference the page in your dashboard, use Get-UDPage.

Basic Page

A basic page can be defined using the New-UDPage cmdlet. You could navigate to this page by visiting the /dashboard URL of your dashboard.

Dashboard with Multiple Pages

Dashboards can have multiple pages and those pages can be defined by passing an array of UDPages to New-UDDashboard

You may want to organize your dashboard into multiple PS1 files. You can do this using pages.

Page with a Custom URL

A page can have a custom URL by using the -Url parameter. You could navigate to this page by visiting the /db URL of your dashboard.

Page with Variables in URL

You can define a page with variables in the URL to create pages that adapt based on that URL.

Query string parameters

Query string parameters are passed to pages and other endpoints as variables.

For example, if you visited a page with the following query string parameter: http://localhost:5000/dashboard/Page1?test=123

You would then have access to a $Test variable that contained the value 123.

Role-Based Access

Header

The following options are available for customizing the header.

Position

Use the -HeaderPosition parameter to adjust the behavior of the header.

• absolute\fixed - Remains at the top of the page, even when scrolling

• relative - Remains at the top of the page. Not visible when scrolling.

Colors

You can adjust the colors of the header by specifying the -HeaderColor and -HeaderBackgroundColor parameters. These colors will override the theme colors.

Navigation

Custom Navigation

Custom navigation can be defined with a list. List items can include children to create drop down sections in the navigation.

Dynamic Navigation

Dynamic navigation can be used to execute scripts during page load to determine which navigation components to show based on variables like the user, IP address or roles.

You can generate dynamic navigation by using the -LoadNavigation parameter. The value of the parameter should be a script block to execute when loading the navigation.

Layouts

The permanent layout creates a static navigation drawer on the left hand side of the page. It cannot be hidden by the user.

The temporary layout creates a navigation drawer that can be opened using a hamburger menu found in the top left corner. This is the default setting.

Horizontal Navigation

You can use New-UDAppBar with a blank page to create horizontal navigation.

Logo

You can display a logo in the navigation bar by using the -Logo parameter.

Now, when creating your page, you can specify the path to the logo.

The logo will display in the top left corner.

Header Content

You can define custom content to include in the header by using the -HeaderContent parameter.

Dynamic Page Title

Page titles are static by default, but you can override this behavior by using -LoadTitle. It will be called when the page is loaded. This is useful when defining pages in multilingual dashboards.

Static Pages

Static pages allow for better performance by not executing PowerShell to load the content of the page. This can be useful when displaying data that does not require dynamic PowerShell execution. The page content is constructed when the dashboard is started.

Static pages do not have access to user specific data. This includes variables such as:

• $Headers

• $User

• $Roles

You can still include dynamic regions within pages. These dynamic regions will have access to user data. Reloading the below example will update the date and time listed in the page.

API

Universal Dashboard is extensible and you can build custom JavaScript components and frameworks. This document will cover how to build custom components that integrate with the Universal Dashboard platform.

Technology Overview

Below is a list of some of the technologies used when building Universal Dashboard components. You will not need to be an expert to produce a component but should be aware of what to search when you encounter a problem.

React

Universal Dashboard's client-side application is built using the . React makes it easy to build components that update the DOM only when necessary and has a pretty robust ecosystem of users. It's one of the most popular JavaScript frameworks at the time of this writing.

Babel

is a transcompiler for JavaScript. It works well with React and allows you to use modern constructs while compiling for backwards compatibility of browsers. Universal Dashboard uses Babel for it's core component frameworks.

Webpack

is an asset bundler. It's extremely customizable and is responsible for turning your JSX files into a bundle that can then be distributed with Universal Dashboard components.

Structure

There are some basic parts to a Universal Dashboard component. You will need to understand the structure in order to successfully build your own.

PowerShell Module

Universal Dashboard custom components are PowerShell modules. They export functions that can be used to create the component when run within a dashboard. The PowerShell module is also responsible for registering the JavaScript assets with Universal Dashboard.

JavaScript Bundle

The JavaScript bundle is produced by the Webpack bundling process. It consists of one or more JS files that you will need to register with UD.

Example Component Module Structure

The most basic structure for a UD component module will include a single JavaScript file, a PSM1 file to export a function and register the JavaScript and a PSD1 module manifest.

Step-By-Step

This following section will take you step-by-step through the different aspects of building a UD component. This assumes you are running PowerShell Universal 1.2 or later and using the PowerShell Universal Dashboard v3 framework.

1. Installing Dependencies

You will need to install the following dependencies before creating your component.

2. Initialize the JavaScript Package

After installing Node, you will have access to the npm command. You will need to initialize the node package to start. This will create a package.json file in your directory.

3. Install JavaScript Packages

You will need several JavaScript packages to build your bundle. You will first want to install the dev dependencies. These are used to build your project.

Next, you'll want to install the universal-dashboard package along with any other packages you wish to use in your component. We are using React95 in this example. We will build a control based on that library.

4. Configure Babel

You will need to create a .babelrc file to configure Babel for React.

5. Configure Webpack

Webpack is extremely customizable and sometimes very hard to get right. Below is a basic webpack.config.js file you can use to configure Webpack. You can safely change the ud95 entry key name and library value to one that matches your library.

6. Component.jsx

Now you can build your first component. You will need to export a single function component from your component.jsx file. We suggest the use of functional React components rather than class-based React components. We need to wrap the component in withComponentFeatures to ensure the component has access to the Universal Dashboard platform features.

7. Index.js

Once your component is completed, you'll need to add it to an index.js file. The entry point for your library is the first place Webpack will look. It will discover all other components from import statements in your code. The index.js file is where you should register your components. You can use the registerComponent function to do so.

8. Bundle JavaScript

To bundle the JavaScript, run the following command to start webpack. This will output a file into the dist folder.

9. PowerShell Script

Now you will need to create a PowerShell script that registers and creates your component.

First, register the JavaScript with Universal Dashboard.

Next, create a function that returns a hashtable that defines which component we are creating and which props to set.

The type property of your hashtable needs to match with the first parameter of registerComponent that you called in your JavaScript.

10. InvokeBuild (optional)

We suggest the use of InvokeBuild to create a build script to run all the steps of packaging and staging your module. The below build script deletes the dist folder, runs an NPM install to install packages, runs an NPM build to bundle the JavaScript and then copies the PS module to the dist folder.

Props

Props are values that are either passed from the PowerShell hashtable provided by the user or by the Universal Dashboard withComponentsFeature high-order function.

Standard

The properties that you set in your hashtable in PowerShell will automatically be sent in as props to React component.

For example, if you set the text property of the hashtable like this.

Then you will have access to that prop in React.

Endpoints

Endpoints are special in the way they are registered and the way that they are passed as props to your component. You will need to call Register on the endpoint in PowerShell and pass in the Id and PSCmdlet variables.

Endpoints are created from ScriptBlocks and are executed when that event happens.

Universal Dashboard will automatically wire up the endpoint to a function within JavaScript. This means that you can use the props to call that endpoint.

Notice the props.onClick function call. This will automatically call the PowerShell script block on the server.

setState

The setState prop is used to set the state of the component. This ensures that the state is tracked and your component will work with Get-UDElement.

For example, with a text field, you'll want to call props.setState and pass in the new text value for the state.

children

The children prop is a standard React prop. If your component supports child items, such as a list or select box, you should use the standard props.children prop to ensure that the cmdlets Add-UDElement , Remove-UDElement and Clear-UDElement function correctly.

Publishing to the Marketplace

To publish to the Marketplace, you simply need to publish to the PowerShell Gallery but include the ud-component tag in your module manifest. The marketplace syncs with the Gallery every hour and your component will be enabled for anyone to find after that.

The New-UDElement cmdlet allows you to create custom React elements within your dashboard. Similar to New-UDHtml, you can define HTML elements using New-UDElement. Unlike, New-UDHtml, you can update elements, set auto refresh and take advantage of the React component system.

Create an Element

You need to specify the -Tag and -Content when creating an element. The below example creates a div tag.

You can nest components within each other to create HTML structures. For example, you could create an unordered list with the following example.

Setting Attributes

You can select attributes of an element (like HTML attributes) by using the -Attributes parameter. This parameter accepts a hashtable of attribute name and values. The below example creates red text.

You can wrap any component with New-UDElement and add an event handler.

Auto Refreshing Elements

You can define the -AutoRefresh, -RefreshInterval and -Endpoint parameters to create an element the refreshes on a certain interval. The below example creates an element that refreshes every second and displays the current time.

Setting Element Properties Dynamically

You can use the Set-UDElement cmdlet to set element properties and content dynamically. The following example sets the content of the element to the current time.

You can also set attributes by using the -Properties parameter of Set-UDElement. The following example sets the current time and changes the color to red.

Adding Child Elements

You can add child elements using Add-UDElement. The following example adds child list items to an unordered list.

Clearing Child Elements

You can clear the child elements of an element by using Clear-UDElement. The following example clears all the list items from an unordered list.

Forcing an Element to Reload

You can force an element to reload using Sync-UDElement. The following example causes the div to reload with the current date.

Removing an Element

You can remove an element by using Remove-UDElement.

API

The New-UDDateTime component is used for formatting dates and times within the client's browser. By using the client's browser, you can format the time based on the local time zone and locale settings for the user.

The date and time component uses DayJS. For a full list of custom formatting options, visit the DayJS documentation.

Basic Formatting

By default, the date and time will be formatted using the LLL localized formatting template.

New-UDDateTime -InputObject (Get-Date)

Resulting output: August 16, 2018 8:02 PM

Custom Formatting

You can specify custom formatting strings using the DayJS formatting template.

New-UDDateTime -InputObject (Get-Date) -Format 'DD/MM/YYYY'

Resulting output: 25/01/2019

Locale

You can specify the locale to display the date and time in.

New-UDDateTime -InputObject (Get-Date) -Locale 'es'

Resulting output: 13 de septiembre de 2022 7:30

API

New-UDDateTime

Chips are compact elements that represent an input, attribute, or action.

Chips allow users to enter information, make selections, filter content, or trigger actions.

While included here as a standalone component, the most common use will be in some form of input, so some of the behavior demonstrated here is not shown in context.

Basic Chips

 New-UDChip -Label 'Basic'

Chips with Icons

New-UDChip -Label 'Basic' -Icon (New-UDIcon -Icon 'user')

OnClick

Shows a toast when the chip is clicked.

New-UDChip -Label 'OnClick' -OnClick {
    Show-UDToast -Message 'Hello!'
}

OnDelete

New-UDChip -Label 'OnDelete' -OnClick {
    Show-UDToast -Message 'Goodbye!'
}

API

New-UDChip

Basic Badge

Examples of badges containing text, using primary and secondary colors. The badge is applied to its children.

  New-UDBadge -BadgeContent { 4 } -Children {
      New-UDIcon -Icon Envelope -Size 2x
  } -Color primary

Color

New-UDBadge -BadgeContent { 4 } -Children {
    New-UDIcon -Icon Envelope -Size 2x
} -Color secondary
New-UDBadge -BadgeContent { 4 } -Children {
    New-UDIcon -Icon Envelope -Size 2x
} -Color success

API

• New-UDBadge

Alerts provide a simple way to communicate information to a user.

Simple Alerts

Alerts have four different severities and can include text or other content.

New-UDAlert -Severity 'error' -Text 'This is an error alert — check it out!' 
New-UDAlert -Severity 'warning' -Text 'This is an warning alert — check it out!'
New-UDAlert -Severity 'info' -Text 'This is an error info — check it out!' 
New-UDAlert -Severity 'success' -Text 'This is an success alert — check it out!'

Advanced Alerts

Alerts can contain any component and also a title.

New-UDAlert -Severity 'error' -Content { New-UDHtml 'This is an error alert — <strong>check it out!</strong>' } -Title "Error"
New-UDAlert -Severity 'warning' -Content { New-UDHtml 'This is an warning alert — <strong>check it out!</strong>' } -Title "Warning"
New-UDAlert -Severity 'info' -Content { New-UDHtml 'This is an error info — <strong>check it out!</strong>' } -Title "Info"
New-UDAlert -Severity 'success' -Content { New-UDHtml 'This is an success alert — <strong>check it out!</strong>' } -Title "Success"

API

New-UDAlert

FontAwesome icons to include in your dashboard. Icon names are slightly different than those shown on the FontAwesome website. For example, if you want to use the network-wired icon, you would use the following string.

New-UDIcon -Icon 'NetworkWired'

Finding an Icon

We include FontAwesome v6 with PowerShell Universal. You can use Find-UDIcon to search through the list of included icons.

Find-UDIcon User

Icon

Create icons by specifying their names. You can use the icon reference below to find icons.

New-UDIcon -Icon 'AddressBook'

Size

Set the size of the icon. Valid values are: xs, sm, lg, 2x, 3x, 4x, 5x, 6x, 7x, 8x, 9x, 10x

    New-UDIcon -Icon 'AddressBook' -Size 'sm'
    New-UDIcon -Icon 'AddressBook' -Size 'lg'
    New-UDIcon -Icon 'AddressBook' -Size '5x'
    New-UDIcon -Icon 'AddressBook' -Size '10x'

Rotation

Rotate icons. The value represents the degrees of rotation.

New-UDIcon -Icon 'AddressBook' -Size '5x' -Rotation 90

Border

Add a border to your icon.

New-UDIcon -Icon 'AddressBook' -Size '5x' -Border

Style

Apply CSS styles to your icon.

New-UDIcon -Icon 'AddressBook' -Size '5x' -Style @{
    backgroundColor = "red"
}

Visually Search for Icons

New-UDTextbox -Id 'txtIconSearch' -Label 'Search' 
New-UDButton -Text 'Search' -OnClick {
    Sync-UDElement -Id 'icons'
}

New-UDElement -tag 'p' -Content {}

New-UDDynamic -Id 'icons' -Content {
    $IconSearch = (Get-UDElement -Id 'txtIconSearch').value
    if ($null -ne $IconSearch -and $IconSearch -ne '')
    {
        $Icons =$Icons = Find-UDIcon -Name $IconSearch
    }

    foreach($icon in $icons) {
        try{
            New-UDChip -Label $icon -Icon (New-UDIcon -Icon $icon)
        }
        catch{
            New-UDChip -Label "$icon Unknown" 
        }
    }
}

Complete Icon List

 https://github.com/FortAwesome/Font-Awesome/blob/6.x/metadata/icons.json

Custom Icons

You can use custom icon sets available on the PowerShell Universal Modules page. First, install the module and then use the icon with other components.

Install-Module Universal.Icons.Tabler

Within your dashboard, call the icon cmdlet.

New-UDButton -Icon (New-UDTablerIcon -Icon "Tb3DRotate")

API

New-UDIcon

The UDDataGrid component is an advanced version of the table that is useful for displaying large amounts of data. It supports many of the same features as the table but also provides complex filtering, row virtualization, multi-column sort and more.

Simple Data Grid

Data grids load their data via the -LoadRows event handler. You will need to return a hashtable that contains the row data and the total number of rows.

Columns are defined using hashtables.

New-UDDataGrid -LoadRows {
    $Data = @(
        @{ Name = 'Adam'; Number = Get-Random}
        @{ Name = 'Tom'; Number = Get-Random}
        @{ Name = 'Sarah'; Number = Get-Random}
    )
    @{
        rows = $Data 
        rowCount = $Data.Length
    }
} -Columns @(
    @{ field = "name"}
    @{ field = "number"}
) -AutoHeight

Columns

Columns are customizable using hashtables. You can find the supported properties below.

Rendering Custom Columns

You can render custom components in columns by specifying render within the column hashtable. You can access the current row's data by using the $EventData or $Row variable

In this example, the number is shown in the name column with a New-UDTypography component.

New-UDDataGrid -LoadRows {  
    $Rows = 1..100 | % {
        @{ Name = 'Adam'; Number = Get-Random}
    }
    @{
        rows = $Rows
        rowCount = $Rows.Length
    }
    
} -Columns @(
    @{ field = "name"; render = { New-UDTypography $EventData.number }}
    @{ field = "number"}
) -AutoHeight

Flexible Width Columns

Column fluidity or responsiveness can be achieved by setting the flex property of a column.

The flex property accepts a value between 0 and ∞. It works by dividing the remaining space in the grid among all flex columns in proportion to their flex value.

For example, consider a grid with a total width of 500px that has three columns: the first with width: 200; the second with flex: 1; and the third with flex: 0.5. The first column will be 200px wide, leaving 300px remaining. The column with flex: 1 is twice the size of flex: 0.5, which means that final sizes will be: 200px, 200px, 100px.

To set a minimum and maximum width for a flex column set the minWidth and the maxWidth property on the column.

New-UDDataGrid -LoadRows {  
    $Rows = 1..100 | % {
        @{ Name = 'Adam'; Number = "This column is a very long string. This column is a very long string. This column is a very long string. This column is a very long string. This column is a very long string. This column is a very long string."}
    }
    @{
        rows = $Rows
        rowCount = $Rows.Length
    }
    
} -Columns @(
    @{ field = "name"; render = { New-UDTypography $EventData.number }}
    @{ field = "number"; flex = 1.0}
) -AutoHeight

LoadRows

The -LoadRows parameter is used to return data for the data grid. Table state will be provided to the event handler as $EventData. You will find the following properties within the $EventData object.

Paging

To implement paging, you can access the page and pageSize properties of the $EventData variable.

New-UDDataGrid -LoadRows {  
    $Rows = 1..100 | % {
        @{ Name = 'Adam'; Number = Get-Random}
    } 
    @{
        rows = $Rows | Select-Object -First $EventData.pageSize -Skip ($EventData.page * $EventData.pageSize)
        rowCount = $Rows.Length
    }
    
} -Columns @(
    @{ field = "name"; }
    @{ field = "number"}
) -AutoHeight -Pagination

Filtering

The filter hashtable is included in the $EventData for the -LoadRows event handler when a filter is defined. The hashtable has a structure as follows.

@{
    items = @(
        @{ 
            columnField = "Name"
            overatorValue = "contains"
            value = "test"
        }
    )
    linkOperator = "and"
}

Items

The items property contains an array of columns, operators and values. You can use these to filter your data.

LinkOperator

The link operator field is used to specify the link between the filters. This can be and or or.

Sorting

The $EventData object will contain a Sort property when the user sorts the data grid. It contains properties for each column that is sorted. The properties will start as 0 and increment as more columns are sorted.

For example, you can access the first sorted column as follows.

$EventData.Sort.'0'.field

You will also receive the sort direction for each column.

Detailed Content

You can use the -LoadDetailedContent event handler to display additional information about the row you are expanding. Information about the current row is available in $EventData.row.

New-UDDataGrid -LoadRows {
    $Data = @(
        @{ Name = 'Adam'; Number = Get-Random }
        @{ Name = 'Tom'; Number = Get-Random }
        @{ Name = 'Sarah'; Number = Get-Random }
    )
    @{
        rows     = $Data 
        rowCount = $Data.Length
    }
} -Columns @(
    @{ field = "Name" }
    @{ field = "number" }
) -AutoHeight -LoadDetailContent {
    Show-UDToast $Body
    New-UDAlert -Text $EventData.row.Name
}

Editing

Tables provide editor support by specifying the -OnEdit event handler. The new row data will be provided as $EventData. You can chose to return updated row information (for example, adjusting something the user has entered) and return it from the event handler. If you do not return anything, the row will reflect what the user entered.

The $EventData has the following format.

@{
    newRow = @{}
    oldRow = @{}
}

Ensure that you provide the editable property to each column you wish for the user to edit.

New-UDDataGrid -LoadRows {
    $Data = @(
        @{ Name = 'Adam'; number = Get-Random }
        @{ Name = 'Tom'; number = Get-Random }
        @{ Name = 'Sarah'; number = Get-Random }
    )
    @{
        rows     = $Data 
        rowCount = $Data.Length
    }
} -Columns @(
    @{ field = "Name"; editable = $true }
    @{ field = "number" ; editable = $true }
) -AutoHeight -OnEdit {
    Show-UDToast "Editing $Body" 
}

Custom Export

To override the default export functionality, use the -OnExport event handler. $EventData will be an array of rows with their values. You should use Out-UDDataGridExport to return the data from -OnExport.

New-UDDataGrid -LoadRows {
    $Data = @(
        @{ Name = 'Adam'; Number = Get-Random}
        @{ Name = 'Tom'; Number = Get-Random}
        @{ Name = 'Sarah'; Number = Get-Random}
    )
    @{
        rows = $Data 
        rowCount = $Data.Length
    }
} -Columns @(
    @{ field = "name"}
    @{ field = "number"}
) -AutoHeight -OnExport {
    $Data = $EventData | Select-Object -Expand name 
    Out-UDDataGridExport -Data $Data -FileName 'export.txt' | Out-String
}

Example: Static Data

In this example, we generate an array of 10,000 records. We will create a new function, Out-UDDataGridData to manage the paging, sorting and filtering.

New-UDDashboard -Title 'PowerShell Universal' -Content {
     $Data =  1..10000 | % {
        @{ Name = 'Adam'; Number = Get-Random }
    } 
    New-UDDataGrid -LoadRows {  
      $Data | Out-UDDataGridData -Context $EventData
    } -Columns @(
        @{ field = "name"; render = { 
            New-UDButton -Icon (New-UDIcon -Icon User) -OnClick { Show-UDToast $EventData.Name } } 
        }
        @{ field = "number" }
    ) -AutoHeight -Pagination
}   

Example: SQL Data

In this example, we'll query the PowerShell Universal database with dbatools.

function Out-UDSQLDataGrid {
    param(
        [Parameter(Mandatory)]
        $Context,
        [Parameter(Mandatory)]
        [string]$Table,
        [Parameter(Mandatory)]
        [string]$SqlInstance,
        [Parameter(Mandatory)]
        [string]$Database
    )
    End {
        $simpleFilter = @()
        if($null -ne $Context.Filter.Items -and $Context.Filter.Items.Count -gt 0) {
            $linkOperator = $Context.Filter.linkOperator #The link operator is 'AND' or 'OR'. It will always be one or the other for all properties
            foreach ($item in $Context.Filter.Items) {         
                $simpleFilter += [PSCustomObject]@{
                    Property    = $item.columnField
                    Value       = $item.Value
                    Operator    = $item.operatorValue
                }
            }
        }

        if($null -ne $simpleFilter -and $simpleFilter.Count -gt 0) {
            $count = 1
            foreach($filter in $simpleFilter) {
                if ($count -gt 1) {
                    $SqlFilter += " $($linkOperator) "
                } else {
                    $SqlFilter += " WHERE "
                }
                switch ($filter.Operator) {
                    "contains" { $SqlFilter += " $($filter.Property) LIKE '%$($filter.Value)%' " }
                    "equals" { $SqlFilter += " $($filter.Property) = '$($filter.Value)' " }
                    "startsWith" { $SqlFilter += " $($filter.Property) LIKE '$($filter.Value)%' " }
                    "endsWith" { $SqlFilter += " $($filter.Property) LIKE '%$($filter.Value)' " }
                    "isAnyOf" {
                        $count = 1
                        foreach($val in $filter.Value){
                            if($count -gt 1) {
                                $list += ", '$val'"
                            } else {
                                $list += "'$val'"
                            }  
                            $count += 1
                        }
                        $SqlFilter += " $($filter.Property) IN ($($list)) "
                    }
                    "isempty" { $SqlFilter += " TRIM ($($filter.Property)) IS NULL " }
                    "isnotempty" { $SqlFilter += " TRIM ($($filter.Property)) IS NOT NULL " }
                    "notequals" { $SqlFilter += " $($filter.Property) != '$($filter.Value)' " }
                    "notcontains" { $SqlFilter += " $($filter.Property) NOT LIKE '%$($filter.Value)%' " }
                }
                $count += 1
            }
        } else {
            $SqlFilter = $null
        }
        $totalCount = (Invoke-DbaQuery -SqlInstance $SqlInstance -Database $Database -Query "SELECT COUNT(*) As Count FROM $Table $SqlFilter" -SqlParameters $SqlParameters).Count
        $sort = $Context.Sort.'0'
        if ($sort)
        {
            $sqlSort = "ORDER BY $($sort.field) $($sort.Sort) "
        } else {
            $sqlSort = "ORDER BY (SELECT NULL)"
        }
        $sqlPage = "OFFSET $($Context.Page * $Context.PageSize) ROWS FETCH NEXT $($Context.PageSize) ROWS ONLY;"
        if($null -ne $SqlFilter) {
            $Query = "SELECT * FROM $Table $sqlFilter $sqlSort $sqlPage"
        } else {
            $Query = "SELECT * FROM $Table $sqlSort $sqlPage"
        }
        $Rows = Invoke-DbaQuery -SqlInstance $SqlInstance -Database $Database -Query $Query -As PSObject -SqlParameters $SqlParameters
        @{
            rows     = [Array]$Rows
            rowCount = $TotalCount
        }
    }   
}

New-UDDashboard -Title 'PowerShell Universal' -Content {
    New-UDDataGrid -LoadRows {  
      Out-UDSqlDataGrid -Context $EventData -SqlInstance "(localdb)\MSSQLLocalDb" -Database "PSU" -Table "Job"
    } -Columns @(
        @{ field = "id"; }
        @{ field = "startTime"; }
        @{ field = "status"; render = {
            if ($EventData.Status -eq 2) {
                New-UDAlert -Severity 'Success' -Text 'Success'
            }

            if ($EventData.Status -eq 3) {
                New-UDAlert -Severity 'Error' -Text 'Failed'
            }
        } }
    ) -AutoHeight -Pagination
}