 [](https://codecov.io/gh/rweich/streamdeck-formbui
npm install @rweich/streamdeck-formbuilder!Build/Test
Helps to build forms, as described and styled in the Propertyinspector styling docs, for the propertyinspector to ease the settings handling between PI and plugin.
``shell`
yarn add @rweich/streamdeck-formbuilder
The styles (sdpi.css) from the official SDK
(which are used in the PISamples plugin), are loaded by default.
When using webpack, it's necessary to:
1. install the style-loader and css-loader packages:
`shell`
yarn add --dev style-loader css-loader
1. add both of them to the rules section of your webpack config:
`javascript`
{
test: /\.css$/i,
use: ['style-loader', 'css-loader'],
}
A quick example how to use the formbuilder in the propertyinspector.
:information_source: For a more complete implementation example, check the formbuilder-showcase streamdeck plugin.
`javascript
import { FormBuilder } from '@rweich/streamdeck-formbuilder';
const initialSettings = {}; // assumes that's whatever you get from the propertyinspector on the didReceiveSettings event
const defaultSettings = { valueOne: 'a default value', valueTwo: 'another default value' };
// create a FormBuilder instance with the values it should use initially
const builder = new FormBuilder({ ...defaultSettings, ...initialSettings });
// add an input field and bind its value to the valueOne-property of the settings
// the values of the elements will (initially) be set to whatever was passed to the FormBuilder above
builder.addElement('valueOne', builder.createInput());
builder.addElement('valueTwo', builder.createInput());
// build the form and append it to the propertyinspectors body element
builder.appendTo(document.body);
// add an eventlistener to send the new settings to the propertyinspector whenever they change
builder.on('change-settings', () => {
const newSettings = builder.getFormData(); // -> { valueOne: 'the new value', valueTwo: 'another new value' }
// now the new settings should be sent to the propertyinspector via the setSettings event
// ...
});
`
- Installation
- Setup webpack
- Example Usage
- Table of Contents
- FormBuilder API
- FormBuilder
- addElement
- addHtml
- addHtmlElement
- createDetails
- createDropdown
- createInput
- createRange
- Details API
- addSummary
- addHeadline
- addParagraph
- addElement
- Dropdown API
- addOption
- Input API
- setPlaceholder
- Range API
- enableMinMaxLabels
- setTickSteps
- shared Element API
- setLabel
- showOn
- Typescript
- Links
The main entry point is the FormBuilder class.
Pass the initial data for the form as parameter.
`javascript`
import { FormBuilder } from '@rweich/streamdeck-formbuilder';
const builder = new FormBuilder({ valueA: 'some initial data', valueB: 'more data' });
---
Form elements like inputs, dropdowns (or selects) can be added using the addElement method.
addElement(name: string, element: object): void
- name: the elements name. used as a key of the (resulting) object that holds all the form valueselement
- : one of the elements, created by the create* methods (e.g. createInput)
Example:
`javascript`
builder.addElement('valueA', builder.createInput());
---
Allows to add elements (like Details) that only show information and don't hold any form-related values.
addHtml(element: { getHtmlElement: () => HTMLElement }): void
- element: object, that exposes a getHtmlElement function to return a HTMLElement
Example:
`javascript`
builder.addHtml(builder.createDetails().addParagraph('some info-text'));
---
Allows to directly add any HTMLElement, only used for display purposes.
addHtmlElement(element: HTMLElement): void
- element: a plain HTMLElement, as created by document.createElement(...)
Example:
`javascript`
const element = document.createElement('div');
element.textContent = 'i show things';
builder.addHtmlElement(element);
---
> See Details API to get an overview how to use the Details object.
>
Creates a collapsible detail element to output informational text.
createDetails(): Details
Example:
`javascript`
builder.addHtml(builder.createDetails().addParagraph('example paragraph'));
---
> See Dropdown API to get an overview how to use the return value.
Creates a drowpdown / select element.
createDropdown(): Details
Example:
`javascript`
builder.addElement('count', builder.createDropdown().addOption('One', 'one').addOption('Two', 'two'));
---
> See Input API to get an overview how to use the return value.
Creates a text input element.
Example:
`javascript`
builder.addElement('username', builder.createInput());
---
> See Range API to get an overview how to use the return value.
Creates a range-input (or slider) element.
createRange(min: number, max: number, step: number = 1): Range
- min: The lowest value in the range of permitted valuesmax
- : The greatest value in the range of permitted valuesstep
- : The step attribute is a number that specifies the granularity that the value must adhere to.
Will make the slider snap to the steps.
Example:
`javascript`
builder.addElement('brightness', builder.createRange(1, 10));
The Details object, returned by createDetails, can be customized using the following methods.
Example:
`javascript`
builder.createDetails()
.addSummary('More Info')
.addHeadline('a headline')
.addParagraph('some text')
.addHeadline('another headline')
.addParagraph('more text');
Adds a summary to the details, which is displayed as the title (the clickable text that still shows when the details are collapsed).
addSummary(text: string): Details
---
Adds a headline to the details.
addHeadline(text: string): Details
---
Adds a paragraph with text to the details.
addParagraph(text: string): Details
---
Allows to add any html element to the details.
addElement(element: HTMLElement): Details
The Dropdown object, returned by createDropdown, can be customized using the following methods (including the ones from the shared API.
Example:
`javascript`
builder.createDropdown()
.setLabel('choose a color')
.addOption('the color red', 'red')
.addOption('the color green', 'green')
.addOption('the color blue', 'blue');
Adds one selectable option to the dropdown.
addOption(label: string, value: string): Dropdown
- label: The text to displayvalue
- : The value, that will be used internally when the option was selected
The Input object, returned by createInput, can be customized using the following methods (including the ones from the shared API.
Example:
`javascript`
builder.createInput()
.setLabel('a label')
.setPlaceholder('placeholder');
Sets the placeholder that will be displayed in the field when its empty
setPlaceholder(placeholder: string): Input
The Range object, returned by createRange, can be customized using the following methods (including the ones from the shared API.
Example:
`javascript`
builder.createRange(0, 100, 20)
.setLabel('choose a size')
.enableMinMaxLabels()
.enableTicks();
Show labels displaying the min-max values in front and behind the slider.
enableMinMaxLabels(): Range
---
Shows tick marks below the slider.
enableTicks(): Range
Elements, added by addElement share the following functions.
Sets the label that will be displayed alongside the form element.
setLabel(label: string): Input
---
Allows to show / hide the element based on another elements value.
The callback gets called on every change to any of the form elements.
Based on the return value of the callback the element will be shown (when true) or hidden (when false).
showOn(callback: () => boolean): Input
- callback: a function that returns true to show or false to hide the element
Example:
`javascript`
builder.createInput().showOn(() => builder.getFormData().color === 'red');
To get typings (mosty for allowed key-names) for addElement() and the return of getFormData(), add the type like this:
`typescript
import { FormBuilder } from '@rweich/streamdeck-formbuilder';
type Settings = {
valueA: string;
valueB: 'yes' | 'no';
}
const builder = new FormBuilder
``