Building Custom Components

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.
This is an advanced topic and not required if you simply want to use Universal Dashboard. There are a lot of existing custom components available on the Universal Dashboard Marketplace.
Look at our blog post on how to get started with custom components for full end-to-end example.
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 framework. 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
​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
​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.
1
- UniversalDashboard.95
2
    - index.23adfdasf.js
3
    - UniversalDashboard.95.psd1
4
    - UniversalDashboard.95.psm1
Copied!
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.
For a full example of a component, click here.
1. Installing Dependencies
You will need to install the following dependencies before creating your component.
​NodeJS​
​InvokeBuild​
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.
1
npm init
Copied!
​Here is an example package.json that you can also use as a starting point.
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.
1
npm install @babel/core --save-dev
2
npm install @babel/plugin-proposal-class-properties --save-dev
3
npm install @babel/plugin-syntax-dynamic-import --save-dev
4
npm install @babel/polyfill --save-dev
5
npm install @babel/preset-env --save-dev
6
npm install @babel/preset-react --save-dev
7
npm install babel-loader --save-dev
8
npm install webpack --save-dev
9
npm install webpack-cli --save-dev
Copied!
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.
1
npm install universal-dashboard --save
2
npm install react95 --save
3
npm install styled-components --save
Copied!
4. Configure Babel
You will need to create a .babelrc file to configure Babel for React.
1
{
2
    "presets": ["@babel/preset-react"]
3
}
Copied!
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.
1
var path = require('path');
2
​
3
var BUILD_DIR = path.resolve(__dirname, 'dist');
4
​
5
module.exports = (env) => {
6
  const isDev = env == 'development' || env == 'isolated';
7
​
8
  return {
9
    entry: {
10
      'ud95' : __dirname + '/index.js'
11
    },
12
    output: {
13
      library: "UD95",
14
      libraryTarget: "var",
15
      path: BUILD_DIR,
16
      filename: isDev ? '[name].bundle.js' : '[name].[hash].bundle.js',
17
      sourceMapFilename: '[name].[hash].bundle.map',
18
      publicPath: "/"
19
    },
20
    module : {
21
      rules : [
22
        { test: /\.(js|jsx)$/, exclude: [/node_modules/, /public/], loader: 'babel-loader'}
23
      ]
24
    },
25
    externals: {
26
      UniversalDashboard: 'UniversalDashboard',
27
      'react': 'react',
28
      'react-dom': 'reactdom'
29
    },
30
    resolve: {
31
      extensions: ['.json', '.js', '.jsx']
32
    }
33
  };
34
}
Copied!
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.
1
import React from 'react';
2
import { withComponentFeatures } from 'universal-dashboard';
3
import { Button } from 'react95';
4
​
5
const UD95Button = props => {
6
​
7
    const p = {
8
        onClick: () => props.onClick()
9
    }
10
​
11
    return <Button {...p}>{props.text}</Button>
12
}
13
​
14
export default withComponentFeatures(UD95Button);
Copied!
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.
1
import { registerComponent } from 'universal-dashboard'
2
import UD95Button from './component';
3
​
4
registerComponent("ud95-button", UD95Button);
Copied!
8. Bundle JavaScript
To bundle the JavaScript, run the following command to start webpack. This will output a file into the dist folder.
1
npm run build
Copied!
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.
1
$JsFile = Get-ChildItem "$PSScriptRoot\ud95.*.js"
2
$AssetId = [UniversalDashboard.Services.AssetService]::Instance.RegisterAsset($JsFile.FullName)
Copied!
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.
1
function New-UD95Button {
2
    param(
3
        [Parameter()]
4
        [string]$Id = [Guid]::NewGuid(),
5
        [Parameter()]
6
        [string]$Text,
7
        [Parameter()]
8
        [Endpoint]$OnClick
9
    )
10
​
11
    if ($OnClick)
12
    {
13
        $OnClick.Register($Id, $PSCmdlet)
14
    }
15
​
16
    @{
17
        type = "ud95-button"
18
        isPlugin = $true 
19
        assetId = $AssetId
20
​
21
        id = $Id 
22
        text = $Text 
23
        onClick = $OnClick
24
    }
25
}
Copied!
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.
1
task Clean {
2
    Remove-Item "$PSScriptRoot\dist" -Recurse -Force
3
}
4
​
5
task NpmInstall {
6
    & {
7
        $ErrorActionPreference = 'SilentlyContinue'
8
​
9
        Push-Location $PSScriptRoot
10
        npm install
11
        Pop-Location
12
    }
13
}
14
​
15
task NpmBuild {
16
    & {
17
        $ErrorActionPreference = 'SilentlyContinue'
18
​
19
        Push-Location $PSScriptRoot
20
        npm run build
21
        Pop-Location
22
    }
23
}
24
​
25
task Stage {
26
    Copy-Item "$PSScriptRoot\UniversalDashboard.95.*" "$PSScriptRoot\dist"
27
}
28
​
29
task . Clean, NpmInstall, NpmBuild, Stage
Copied!
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.
1
function New-UDText {
2
    param(
3
        [Parameter()]
4
        [string]$Text
5
    )
6
​
7
    @{
8
        type = "text"
9
        isPlugin = $true
10
        assetId = $AssetId 
11
​
12
        text = $Text
13
    }
14
}
Copied!
Then you will have access to that prop in React.
1
import React from 'react';
2
import { withComponentFeatures } from 'universal-dashboard';
3
​
4
const UDText = props => {
5
    return <div>{props.text}</div>
6
}
7
​
8
export default withComponentFeatures(UDText);
Copied!
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.
1
function New-UD95Button {
2
    param(
3
        [Parameter()]
4
        [string]$Id = [Guid]::NewGuid(),
5
        [Parameter()]
6
        [string]$Text,
7
        [Parameter()]
8
        [Endpoint]$OnClick
9
    )
10
​
11
    if ($OnClick)
12
    {
13
        $OnClick.Register($Id, $PSCmdlet)
14
    }
15
​
16
    @{
17
        type = "ud95-button"
18
        isPlugin = $true 
19
        assetId = $AssetId
20
​
21
        id = $Id 
22
        text = $Text 
23
        onClick = $OnClick
24
    }
25
}
Copied!
Endpoints are created from ScriptBlocks and are executed when that event happens.
1
New-UD95Button -Text 'Hello' -OnClick {
2
    Show-UDToast -Message 'Test' 
3
}
Copied!
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.
1
import React from 'react';
2
import { withComponentFeatures } from 'universal-dashboard';
3
import { Button } from 'react95';
4
​
5
const UD95Button = props => {
6
​
7
    const p = {
8
        onClick: () => props.onClick()
9
    }
10
​
11
    return <Button {...p}>{props.text}</Button>
12
}
13
​
14
export default withComponentFeatures(UD95Button);
Copied!
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.
1
const UDTextField = (props) => {
2
    const onChange = (e) => {
3
        props.setState({value: e.target.value})
4
    }
5
​
6
    return <TextField  {...props} onChange={onChange} />
7
}
8
​
9
export default withComponentFeatures(UDTextField);
Copied!
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
The Universal Dashboard Marketplace is an aggregator of the PowerShell Gallery that lists Universal Dashboard components. The UD Marketplace automatically hooks into PowerShell Universal v1.3 or later where you can easily install additional components.
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.
HTML
Data Display
Last modified 1yr ago