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

Example: People Picker

The below example creates a New-UDPeoplePicker component from existing UD components. You can use the New-UDPeoplePicker component in your dashboards. This function can either be defined within your dashboard directly or within a Module.

This example users a published folder of avatars.

function Get-User {
    1..100 | ForEach-Object {
        [PSCustomObject]@{
            UserName = "User$_"
            First = "Bill"
            Last = $_
            Avatar = (Get-ChildItem "$Repository\Avatars" | Get-Random).Name
        }
    }
}

function New-UDPeoplePicker {
   $Session:Users = [System.Collections.Generic.List[object]]::new()

    New-UDAutocomplete -OnLoadOptions {
        Get-User | Where-Object { $_.UserName -like "*$UserName*" } | Select-Object -First 5 -ExpandProperty 'UserName' | ConvertTo-Json 
    } -OnChange {
        $Session:Users.Add((Get-User | Where-Object { $_.UserName -eq $EventData })) | Out-Null
        Sync-UDElement -Id 'users'
    }

    New-UDDynamic -Id 'users' -Content {
        New-UDList -Children {
            $Session:Users | ForEach-Object {
                New-UDListItem -Label $_.UserName -SubTitle "$($_.First) $($_.Last)" -AvatarType 'Avatar' -SecondaryAction {
                    $UserName = $_.UserName
                    New-UDIconButton -Icon (New-UDIcon -Icon 'Trash') -OnClick {
                        $RemoveUser = $Session:Users | Where-Object { $_.UserName -eq $UserName }
                        $Session:Users.Remove($RemoveUser) 
                        Sync-UDElement -Id 'users'
                    }
                } -Source "/avatars/$($_.Avatar)"

            }    
        }
    }
}

New-UDDashboard -Title 'PowerShell Universal' -Content {
    New-UDPeoplePicker
}

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.