Stream Deck's integrated HTML5 Property Inspector allows you to communicate with your plugin from Stream Deck software. We recommend using our integrated CSS and tools. Our PISamples plugin demonstrates all supported HTML elements in the Property Inspector.
General operation
Stream Deck's Property Inspector (PI) is an HTML5 view based on a standard Flexbox-Layout. We've included some layout and styling to get you started quickly. PI's main view is wrapped in a HTML-node with the class sdpi-wrapper.
<divclass="sdpi-wrapper"> ... your content goes here ...<div>
To make sure proper styling is applied to the wrapper's contents, you would link our included stylesheet in the <head> section of PI's HTML page. Alternatively, you can clone one of the included samples and start from there.
Standard elements of Stream Deck's PI consist of a label and a value, each of which can be identified by their respective classes: sdpi-item-label and sdpi-item-value. Since you can add multiple label/value pairs, each of these pairs are wrapped into an sdpi-item node. <div class="sdpi-item"> is basically all that's required. Add a type to the sdpi-item to use the included helper CSS.
A file-upload element with label, which opens a file-dialog and lets the user choose a file. It differs a bit from the regular fileselector, in that it allows you to pick up the full path of the selected file. (You will find a sample how to do this in the PISamples plugin.
A regular list element to show items to select from. Ordered, unordered lists and some other list-types are supported. (Btw: in the PISamples plugin, there's a short utility javascript, which already make the lists interactive/clickable... Click here for more info
Also table elements are supported, where each cell can contain a (clickable) value (in the PISamples plugin, you'll find a short utility javascript, which already make the table interactive/clickable... Click here for more info
The details element is a complete widget on it's own. It therefore occupies the full width of the PI's view by default. It can be used to create an interactive widget that the user can open and close. You can put any content into it.
The message element is similar to the detailselement. It doesn't show an disclosure-triangle, but you can add some notification icons to it. It can be used to create an interactive widget that the user can open and close. You can put any content into it.
Note that only 'flat' sdpi-item structures are supported. That means, sdpi-item within another sdpi-item is unsupported (some exceptions apply, see Group). Adding id attributes to your elements is recommended.
Textfield
<divclass="sdpi-item"> <divclass="sdpi-item-label">Name</div> <inputclass="sdpi-item-value"id="myname"value=""placeholder="Enter your name"></div><divclass="sdpi-item"> <divclass="sdpi-item-label">Email</div> <inputclass="sdpi-item-value"id="myemail"value=""placeholder="Enter your email-address"></div>
The required attribute
If you want to notify the user of a required value, you can simply add a required control, which shows a tiny exclamation mark, as long as there's no text in the field.
You can use the pattern attribute to specify a pattern to validate the IP-Address.
<div class="sdpi-item" id="your_name" title="This field lets you enter an IP-Adress. The little exclamation mark changes to a checkmark, if the condition is met (e.g. you entered an IP-address.).">
<divclass="sdpi-item-label">IP-Address</div> <input class="sdpi-item-value" id="myipaddress" value="" placeholder="e.g. 192.168.61.1" required pattern="\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}">
</div>
Here are some example patterns:
8 characters or more: pattern=".{6,}"
2-character country code (e.g. EN): pattern="[A-Za-z]{2}"
Pattern
Description
pattern="\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}"
IP-address
pattern=".{8,}"
8 characters or more
pattern="[A-Za-z]{2}"
2 character country code
pattern="[^'\x22]+"
no single or double quotes
pattern="(?=.*\d)(?=.*[a-z])(?=.*[A-Z]).{4,}"
at least 4 characters, 1 uppercase, 1 lowercase and 1 number
Textarea
If you need to enter some more text, you can easily add a textarea control, which allows for multi-line text.
You can add info-text to the bottom of the textarea by adding a label right after the textarea and giving the label a for attribute with the value of the textarea's id.
By default, the button's width takes the full available width. We included a couple of utility-classes in sdpi.css to restrict width of a button. E.g class max20 limits the width to approx 20% of the total width:
Creating a HTML5 checkboxes with a label is getting more involved because there's no themeable checkbox available in today's browsers and HTML renderers. Creating checkboxes generally works the same way:
Single Checkbox
A single checkbox doesn't require a separate value-container, so you can put the sdpi-item-value class right onto the input-element:
<divtype="checkbox"class="sdpi-item"> <divclass="sdpi-item-label">Check Me </div> <inputclass="sdpi-item-value"id="chk0"type="checkbox"value="left"> <labelfor="chk0"><span></span>left</label></div>
In order to let the PI know there are a group of checkboxes, you just put these checkboxes into a sdpi-item-value wrapper...
Please note the additional <span> element, which is used to override the browser's default checkbox. It remains empty and serves just as a placeholder. This is a common technique to allow drawing custom checkboxes, radio-buttons, etc.
Many checkboxes
If you need more than 2 or 3 checkboxes, alignment can get tricky and you end up with this:
We added a helper-node sdpi-item-child, which you can use to group checkboxes/radio-buttons and their labels for easier alignment. Please note the min100 class in the parent element sdpi-item-value min100, which means the subsequent sdpi-item-value elements will be at least 100px wide. You can add CSS or even inline-styles to override this behavior. Using the sdpi-item-child class to 'group' input and label, will produce a much nicer output:
Note: In the PISamples-plugin, a span of class clickable is intercepted, and the value of its 'range' element is set to the value specified in the 'value' attribute of the span element. If you leave out the value attribute from the span element, PI tries to use the value in the span text-node.
Range with datalist
Adding a datalist to a range produces steps. Pi's slider will snap to those steps.
To present some pre-defined color values, you can add a datalist to the color control. To make sure the list gets appended properly, set the list attribute of the input control to the id of the datalist. (in our example 'clrs')
You can present the user with a collection of pre-defined dates as well. Add a <datalist> node to the sdpi-item. To make sure the list gets appended properly, set the list attribute of the input control to the id of the datalist. (in our example 'events')
<divclass="sdpi-item"id="date"> <divclass="sdpi-item-label">Date</div> <inputclass="sdpi-item-value"id="myevents"type="date"value="yyyy-mm-dd"list="events"> <datalistid="events"> <optionlabel="Elgato Live Stream">2019-01-06</option> <optionlabel="Incredible event">2019-01-15</option> <optionlabel="Palo Alto LAN party">2019-02-05</option> <optionlabel="Something else">2019-12-31</option> </datalist></div>
Month
It is also possible to restrict the settable values to months:
You can present the user with a collection of pre-defined months. Add a <datalist> node to the sdpi-item. To make sure the list gets appended properly, set the list attribute of the input control to the id of the datalist. (in our example 'months')
<divclass="sdpi-item"id="month"> <divclass="sdpi-item-label">Month</div> <inputclass="sdpi-item-value"id="month"type="month"value="2019-01"list="months"> <datalistid="months"> <optionlabel="Neil on the moon">1967-07</option> <optionlabel="First month of this century">2000-01</option> <optionlabel="Last month of last century">1999-12</option> <optionlabel="Last month of 2019">2019-12</option> </datalist></div>
Week
It is also possible to restrict the settable values to weeks:
You can present the user with a collection of pre-defined weeks. Add a <datalist> node to the sdpi-item. To make sure the list gets appended properly, set the list attribute of the input control to the id of the datalist. (in our example 'weeks')
<divclass="sdpi-item"id="week"> <divclass="sdpi-item-label">Week</div> <inputclass="sdpi-item-value"id="longweek"type="week"value="2019-W02"list="weeks"> <datalistid="weeks"> <optionlabel="First week of 2019">2019-W01</option> <optionlabel="Second week of 2019">2019-W02</option> <optionlabel="24th week of 2019">2019-W24</option> <optionlabel="Last week of 2019">2019-W52</option> </datalist></div>
DateTime control
A combined datetime control allows to set both date and time based on the user's current time-zone:
Using a list control, you can present the user with a list of items. In our sample plugin, we show how you can make them interactive/clickable by adding a class to the list. Supported classes are:
Class
Description
no-select <optional>
List just shows scrollable items
single-select
List hilites the currently clicked/active item
multi-select
Allows selecting multiple items
For single-select and multi-select, a selected class is applied to the selected/clicked list-item, so it's easy to find its state. You can also pre-select an item by adding a class selected when constructing the list.
Using a table control, you can present the user with a table of values.
In our sample plugin, we show how you can easily make them interactive/clickable by adding a class to the table. Supported classes are:
Class
Description
no-select <optional>
Table just shows scrollable items
single-select
Table hilites the currently clicked/active item
multi-select
Allows selecting multiple items. (no modifier key required)
For single-select and multi-select, a selected class is applied to the selected/clicked table-item td, so it's easy to find its state. You can also pre-select an item by adding a class selected when constructing the table.
To add a file-selector to the PI, you can add a type of file and a class sdpi-item-value to the HTML. The integrated file-selector, unfortunately, returns a 'fakepath' as its value (and shows it in the label). You will need to write your own code for reading the contents of the file.
Here we add to label elements to the DOM, whose 'for'-attribute contains the reference to the ìnputelement (in the example aboveelgfilepicker`).
spdi-file-info will receive the file-name sdpi-file-label replaces the original 'Choose file...' button.
Clicking both elements will trigger and show the file-selector-dialog. To ensure proper styling, just group those elements in a sdpi-item-group and add a class file. The included sample code will fill the elements as needed. If you don't need to show the file name, you can just leave the sdpi-file-info out. Only the sdpi-file-label is required since it triggers the file dialog.
The file-selector returns an URLencoded absolute file path. (e.g. %2FUsers%2Fandy%2FDesktop%2Fmarina.png). To convert this back to a javascript string, you must decode this string first using decodeURIComponent.
Please note: Chromium adds (for security reasons) a 'fake' string C:\\fakepath\\, so you must strip this fakepath to get to the 'real' path, like so:
if (element.type ==='file') { result =decodeURIComponent(element.value.replace(/^C:\\fakepath\\/,''));}
The sdpi-file-info label needs to be manually populated with the previously selected file path once the PI is loaded.
Sometimes you will want to group some inputs or other elements together visually. For this case, there's a sdpi-item-group element, which groups arbitrary elements.
As with any other sdpi-item, a group can have a label. The main difference to a regular sdpi-item-label is that the group's label is left-aligned and can fill the whole space above a group (e.g. it can be a longer and more descriptive string).
The structure of a group is similar to a regular sdpi-item, with the exception, the group's value is the actual sdpi-item-group, which - in turn - contains any regular sdpi-item (just as shown above)
You can draw a horizontal line using HTML5's <hr> element. This draws a line from left to right over the full width of PI's viewable pane (minus some margin). This can be helpful to separate different inspector elements or groups.
<hr>
Heading
A heading lets you place a nice heading above (or below) an sdpi-item. It is meant as an optical separation between sdpi-items.
To add an heading, simply place a div with a class sdpi-heading outside an sdpi-item:
Like other controls, you can easily add multiple meters to the output.
Please note: Since Meter controls are meant 'read-only', you should give every meter node its own class of sdpi-item-value (especially if you want to later make them interactive - e.g. clickable individually).
Adding some labels to a meter requires grouping the meters in a separate child-node containing the left label, the meter, and the right label, which then will produce an output similar to this:
Note: For the progress element, you need to set the max attribute; otherwise, a value from 0..1 is assumed.
Multiple Progress Elements
Like other controls, you can add multiple progress elements to the output.
Please note: Since Progress controls are meant 'read-only', you should give every meter node its own class of sdpi-item-value (especially if you want to later make them interactive - e.g. clickable individually).
Adding some labels to a meter requires grouping the meters in a separate child-node containing the left label, the meter, and the right label, which then will produce an output similar to this:
Hint: Our included PISamples plugin shows how to make these (and other controls) clickable easily. Just take a look or copy the code from there.
Details
This element's content can be shown or collapsed (much like an accordion). It can contain a summary and/or additional text or HTML elements.
<details>
<summary>More Info</summary>
<p>Put some text here.</p>
<h4>Create Headlines</h4>
<p>Whatever you like</p>
</details>
A details element's default state is 'closed'. In this state, it only shows a disclosure triangle. Clicking the disclosure triangle will disclose the details of the element:
Details content
The details element is a kind of 'widget' on its own, in that it can contain arbitrary other HTML elements, which are disclosed as soon as the disclosure triangle is clicked.
Wrapped Details
You can wrap the details-item into a regular sdpi-item like so:
<div class="sdpi-item">
<div class="sdpi-item-label">Details</div>
<details class="sdpi-item-value">
<summary>Some Details here</summary>
<p>Here are some details.</p>
...
</details>
</div>
but it will also work on it's own:
<details>
<summary>More Info</summary>
<p>This is Stream Deck's Property Inspector.</p>
<p>To find out how things work, just open the 'index_pi.html' included in this plugin and compare to what's shown in Stream Deck</p>
<a href="#">More info...</a>
</details>
Unwrapped Details
You most likely want to show the user some information about your plugin (or its usage). Allowing the details element to flow across the full width of PI's view pane will give you some more space to present your information.
Message
The messageelement is similar to the details. It allows you to show a bolder message to your users:
Message icons
Depending on the significance of the message, you can also add an icon to the message by just appending a class to the message class:
<details class="message question">
<summary>This is some message</summary>
</details>
Supported icons types are:
Class
Description
info
caution
question
This element's content can get shown or collapsed. It can contain a summary and/or additional text or HTML elements.
Message content
A message element's default state is 'closed'. In this state, it only shows the message in summary. If the message element contains further information, you can click the summary to disclose this information.
<details class="message">
<summary>This is some message</summary>
<h4>Information:</h4>
<p>In this area you can type some information to your user.</p>
<a class="info" href="#">Click here</a>
</details>
Hint: If you add an anchor element to the HTML, you can add one of the supported icons here as well...
Tabs
If your property inspector contains lots of entries (or you want to add some structure), you can use the tabs element:
This code above will make the tabs interactive: - clicking on a tab will make it active - clicking on a tab will show the corresponding content - clicking on a tab will hide the content of all other tabs
To gain full interactivity from Property Inspector to the plugin, the Property Inspector must be able to send messages to the plugin.
Since the PI is just a regular webpage, you can include common scripting techniques to communicate from Property Inspector to Stream Deck to Plugin and vice versa.
Registration
Once the Property Inspector is instantiated (and thus its webpage is loaded), the Stream Deck application sends a connectElgatoStreamDeckSocket message to it, which contains various information needed to communicate between the Property Inspector and the Stream Deck software.
function connectElgatoStreamDeckSocket(inPort, inPropertyInspectorUUID, inRegisterEvent, inInfo, inActionInfo);
Please note that the Property Inspector is instantiated every time the user selects a key to configure.
Using the connectElgatoStreamDeckSocket's inPort parameter, you are now able to establish a proper Websocket-communication with Stream Deck software using a standard HTML5 WebSocket instance:
websocket = new WebSocket('ws://localhost:' + inPort);
Now the Property Inspector registers itself with Stream Deck software, like so:
websocket.onopen = function () {
var json = {
"event": inRegisterEvent,
"uuid": inPropertyInspectorUUID
};
websocket.send(JSON.stringify(json));
};
The Property Inspector will receive messages through the Websocket's onmessage event:
websocket.onmessage = function (evt) {
// do something with the messages
}
More details about this procedure is found here: Property Inspector registration
Sending Messages to a plugin
After the connection from the Property Inspector to the Stream Deck application is established, you can send messages to your plugin. The Stream Deck software expects a stringified JSON structure to be able to pass the message to the proper plugin:
const json = {
"action": "com.example.tutorial.action1",
"event": "sendToPlugin",
"context": <uniqueValue>, // as received from the 'connectElgatoStreamDeckSocket' event
"payload": {}
};
websocket.send(JSON.stringify(json));
The JSON's payload can be anything you like, as long as it is possible to send it as string through a websocket (Your plugin is responsible for handling the data).
You will find more details about the message and message format here: Property Inspector Events
PI lifecycle events
When the Property Inspector closes, standard HTML5 lifecycle events are sent. You can add a listener to these events, e.g. to signal your plugin, the PI is no longer available, and thereby you don't need to send further data to it. This is good practice to avoid unnecessary traffic on the websocket.
To subscribe to these events, you may install an event listener on the PI window. When you receive one of these events, you can signal your plugin; the PI will be closed.
Here are some examples (not you only need one of these):
beforeunload-event
window.addEventListener('beforeunload', function (e) {
e.preventDefault();
sendValueToPlugin('propertyInspectorWillDisappear', 'property_inspector');
// Don't set a returnValue to the event, otherwise Chromium with throw an error.
});
pagehide-event
/** the pagehide event is fired when the view disappears */
window.addEventListener('pagehide', function (event) {
sendValueToPlugin('propertyInspectorPagehide', 'property_inspector');
});
unload-event
/** the unload event is fired, when the PI will finally disappears */
window.addEventListener('unload', function (event) {
sendValueToPlugin('propertyInspectorDisconnected', 'property_inspector');
});
Sample Property Inspector
With these bits of information, we can create a working Property Inspector quickly.
First of all, we need an input control to enter some data. In this example, we use an HTML select to send some values to the plugin.
According to the documentation above, we add a select control to Property Inspector's sdpi-wrapper:
Note the sendValueToPlugin call on the select's onChange event (which is fired every time the value of the select changes). It adds two parameters:
the value of the event's target (in this case, the select)
and a custom identifier (which can be anything you like)
Parameter
Description
value
the value of the event's target (in this case the select)
identifier
a custom identifier (which can be anything you like). This value will get the key of our value, so the plugin's receiving function can identify what the value is supposed to do. Note in our example, we could simply pass the value with an arbitrary key because there's only one value sent, but as soon as there are more controls involved, the plugin needs to know which of the control's values is being sent. So it seems to be a good practice to use this strategy even for setups.
With this information, we are now able to write a function, which handles the reception of the onChange event and passes its value on to Stream Deck (and thereby to the plugin):
function sendValueToPlugin(value, param) {
// say the websocket connection is saved in the variable 'websocket'
if (websocket) {
// compile our JSON object.
const json = {
"action": "com.example.tutorial.action1",
"event": "sendToPlugin",
"context": <uniqueValue>, // as received from the 'connectElgatoStreamDeckSocket' callback
"payload": {
// here we can use ES6 object-literals to use the 'param' parameter as a JSON key. In our example this resolves to {'myIdentifier': <value>}
[param] : value;
}
};
// send the json object to the plugin
// please remember to 'stringify' the object first, since the websocket
// just sends plain strings.
websocket.send(JSON.stringify(json));
}
}
Putting the above HTML/Javascript together already makes up a nice and functional Property Inspector.
One missing part is the included styling contained in sdpi.css which is included in the samples and can quickly be added to the HTML's <head> section:
Now we have all needed elements set, to try out our first custom Property Inspector. Here's the complete HTML:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<title>com.elgato.sample PI</title>
<link rel="stylesheet" href="sdpi.css">
</head>
<body>
<div class="sdpi-wrapper">
<div type="select" class="sdpi-item">
<div class="sdpi-item-label">Change Value</div>
<select class="sdpi-item-value" onchange="sendValueToPlugin(event.target.value, 'myIdentifier')">
<option selected value="0">0</option>
<option value="1">1</option>
<option value="2">2</option>
<option value="3">3</option>
<option value="4">4</option>
<option value="5">5</option>
<option value="6">6</option>
<option value="7">7</option>
<option value="8">8</option>
<option value="9">9</option>
</select>
</div>
</div>
<script>
// this is our global websocket, used to communicate from/to Stream Deck software
// and some info about our plugin, as sent by Stream Deck software
var websocket = null,
uuid = null,
actionInfo = {};
function connectElgatoStreamDeckSocket(inPort, inUUID, inRegisterEvent, inInfo, inActionInfo) {
uuid = inUUID;
// please note: the incoming arguments are of type STRING, so
// in case of the inActionInfo, we must parse it into JSON first
actionInfo = JSON.parse(inActionInfo); // cache the info
websocket = new WebSocket('ws://localhost:' + inPort);
// if connection was established, the websocket sends
// an 'onopen' event, where we need to register our PI
websocket.onopen = function () {
var json = {
event: inRegisterEvent,
uuid: inUUID
};
// register property inspector to Stream Deck
websocket.send(JSON.stringify(json));
}
}
// our method to pass values to the plugin
function sendValueToPlugin(value, param) {
if (websocket) {
const json = {
"action": actionInfo['action'],
"event": "sendToPlugin",
"context": uuid,
"payload": {
[param] : value
}
};
websocket.send(JSON.stringify(json));
}
}
</script>
</body>
</html>
Debugging
To debug your Property Inspector, you can use Chrome's developer tools. By default, you will find the remote-debugger at http://localhost:23654/.
For more information on how to activate debugging, please follow the 'debugging' section in Getting Started.
Once activated, our freshly created Property Inspector will look something like this:
