Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/barraider/streamdeck-easypi
Javascript library to simplify the communication between the Stream Deck's Property Inspector and the plugin
https://github.com/barraider/streamdeck-easypi
Last synced: 5 days ago
JSON representation
Javascript library to simplify the communication between the Stream Deck's Property Inspector and the plugin
- Host: GitHub
- URL: https://github.com/barraider/streamdeck-easypi
- Owner: BarRaider
- Created: 2019-03-09T21:03:12.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2024-12-11T16:52:21.000Z (13 days ago)
- Last Synced: 2024-12-11T17:39:14.224Z (13 days ago)
- Language: CSS
- Size: 68.4 KB
- Stars: 53
- Watchers: 7
- Forks: 10
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# StreamDeck EasyPI
This library is meant to simplify the communication between the Property Inspector and your plugin.
By sticking to a few guidelines, the library will own setting and getting the various settings for your plugin.
## Help / Support
Make sure to star this repository or follow my [twitter](https://twitter.com/realBarRaider) to get notified when it changes.
**Questions, Suggestions, and Support via [Discord](http://discord.barraider.com)**
## New in v1.4
- Updated styles to match Elgato's
## New in v1.3
- Introducing rangedTooltip.js - Instructions how to use it in the ***Ranged Tooltip*** section below
## How to use:
Use the following tags in your Property Inspector HTML file to use the latest version:
- Core (sdtools.common.js):
```
```
- Core CSS (sdpi.css):
```
```
- Range Tooltips (see usage examples below):
```
```
## Tutorial
### Common Use-case
This section is relevant for the majority of controls. There are a few different controls (such as the CheckBox or FilePicker) that require additional steps, as indicated below.
Example1:
```
```
Example2:
```
1 Second
15 Seconds
30 Seconds
```
There are three things needed for the library to work correctly (as demonstrated in the example above):
1. Each property must have an ***id*** field. The id must be identical to the name of the property in the payload. In the example above, the library will pass two settings, one named ***lastName*** and one named ***refreshSeconds***. The library will also look for those names to populate the values when new data is received.
2. The property must also have a class called ***sdProperty***. The control can have additional classes too, but this one must be there.
3. Add an ***oninput="setSettings()"*** section to the control, to ensure settings are saved as soon as a user changes input.
### CheckBox
To get data to and from checkboxes add an additional class named **sdCheckbox** _in addition_ to the sdProperty indicated above.
```
```
### FilePicker
To support filepickers, as recommended in the SDK follow the following guidelines:
```
No file...
```
1. On the input element, add an additional class named **sdFile** _in addition_ to the sdProperty indicated above.
2. Add a label, as indicated above. Make sure the Id of the label has a ***Filename*** suffix (If the input is called userImage than the label is named userImageFilename)
### Dropdown lists
EasyPI supports passing a dynamic list to be shown in a dropdown. In addition, you can choose the name of the field that will hold value selected by the user.
To support dynamic dropdown lists, follow the following guidelines:
```
```
1. On the select element, add an additional class named **sdList** _in addition_ to the sdProperty indicated above.
2. Add an attribute named **sdListTextProperty** which is the name of the *property* for each item in the list that holds the text you want to show in the dropdown
3. Add an attribute named **sdListValueProperty** which is the name of the *property* for each item in the list that holds the value you want to return when an item is selected
4. Add an attribute named **sdValueField** which is the name of a property in the payload which will be used to both retreive the selected value and store it back if the user chooses another option in the dropdown.
#### Example of how this would look on the backend side:
```
[JsonProperty(PropertyName = "sounds")]
public List Sounds { get; set; }
[JsonProperty(PropertyName = "soundTitle")]
public string SoundTitle { get; set; }
```
and `SoundData` would look like this:
```
class SoundData
{
[JsonProperty(PropertyName = "soundName")]
public string SoundName { get; set; }
[JsonProperty(PropertyName = "soundIndex")]
public int SoundIndex { get; set; }
}
```
### HTML Elements
EasyPI supports passing HTML to be shown in the InnerHTML property of an element in the Property Inspector.
To support HTML elements, follow the following guidelines:
```
```
1. On the div/span element, add an additional class named **sdHTML** _in addition_ to the sdProperty indicated above.
## Events
The library currently sends out two events
### websocketCreate
This event will be triggered as soon as a websocket is created with the StreamDeck.
Subscribe by using:
```
document.addEventListener('websocketCreate', function () {
console.log("Websocket created!");
...
});
```
You can also subscribe to the websocket events as part of this event:
```
document.addEventListener('websocketCreate', function () {
websocket.addEventListener('message', function (event) {
console.log("Got message event!");
});
});
```
### settingsUpdated
This even will be triggered when a new payload of settings is sent from the PI to the Plugin itself.
Subscribe by using:
```
document.addEventListener('settingsUpdated', function (event) {
console.log("Got settingsUpdated event!");
});
```
### Ranged Tooltip
The rangedTooltip.js library allows you to see a tooltip of the current value when modifying a range element.
To use:
1. Add `` and `` to the section
2. Create a div of `type="range"` and give it the `sdShowTooltip` class (as shown below). The example below will create a range of 1-200
```
Speed
1
200
100
```
3. For the actual range add the `class="sdProperty"` and the `data-suffix`. You can use `data-suffix` to decide what to show after the number (such as %, 'ms', etc.)
4. Add the following line somewhere in your HTML file:
```
```