universal-dashboard

Library for creating custom Universal Dashboard components.

Usage no npm install needed!

<script type="module">
  import universalDashboard from 'https://cdn.skypack.dev/universal-dashboard';
</script>

README

Universal Dashboard

Universal Dashboard is a platform for building web-based tools with PowerShell.

More Information about Universal Dashboard

About this Package

This package is used to create custom Universal Dashboard components. It provides features to make it easier to create components the integrate with Universal Dashboard. This package requires Universal Dashboard v3 or later running in PowerShell Universal.

How to use this package

In your source directory, install this package using the following command.

npm install universal-dashboard

This package exports a couple functions. The first is withComponentFeatures.

This function is used to inject the Universal Dashboard features are props to your control.

import { withComponentFeatures } from 'universal-dashboard'

This high-order function can be used with your component like this.

const MyComponent = () => {
    return <div />
}

export withComponentFeatures(MyComponent);

Available Props

The following are the props that are injected into your component.

render (function)

This function is used to render other Universal Dashboard components. This might be handy if you support child components for your component.

const MyComponent = props => {
    return props.children.map(x => props.render(x))
}

export withComponentFeatures(MyComponent);

setState (function)

setState is used to bubble state up into a parent scope that can then be used with Get-UDElement. When you call setState, the state values will be passed back in as props and the state will be stored for you. Any calls to Get-UDElement will return that state.

const MyComponent = props => {
    return <input type="text" onChange={x => props.setState(x.target.value)}>
}

export withComponentFeatures(MyComponent);

Other Props

Other functions will be injected for event handlers automatically. This means that any Endpoints you define in your component's PowerShell function will be available automatically as functions in your component.

Here's an example of the PowerShell script for the component.

function New-UDCoolButton {
    param(
        [Parameter()]
        [string]$Id = [Guid]::NewGuid(),
        [Parameter()]
        [Endpoint]$OnClick
    )

    $OnClick.Register($Id, $PSCmdlet)

    @{
        type = "coolbutton",
        isPlugin = $true,
        assetId = $AssetId
        id = $id 
        onClick = $OnClick
    }
}

Here's an example of the JavaScript for the component.

const MyComponent = props => {
    return <button onClick={x => props.onClick()}>
}

export withComponentFeatures(MyComponent);

Registering a Component

To register your component with Universal Dashboard, you'll need to use the registerComponent function. Pass the ID and the function for your component.

import MyComponent from './MyComponent.jsx'
import { registerComponent } from 'universal-dashboard'

registerComponent('my-component', MyComponent);

You should use this ID as the type parameter in your PowerShell hashtable.

function New-UDMyComponent {
    @{
        type = "my-component",
        isPlugin = $true,
        assetId = $AssetId
    }
}