Add documentation for Thing and Variable support with 0.2.x

content/developer-tools/custom-tiles/html.md

@@ -1,20 +1,23 @@
+---
+sidebarDepth: 2
+---
+
 # Custom Tiles - HTML Type
 
-## Overview
 Selecting the HTML type for a [Custom Tile](./) provides a script editor interface in which you can write standard HTML, JavaScript,
 and CSS to build Custom Tiles. The HTML option also provides the option to define Tile Settings which you can then
 access within your JavaScript.
 
-## Creating HTML Custom Tile
-Since this is using standard web technologies, you can use existing libraries and frameworks – Bootstrap, React,
+## Introduction 
+Because Custom Tiles use standard web technologies, you can use existing libraries and frameworks – Bootstrap, React,
 Vue, Angular, Tailwind, etc. Or you can use regular (vanilla) HTML and JS.
 
 <video width="80%" controls>
   <source src="../assets/custom_tile_html_ide_demo.mp4" type="video/mp4">
   Your browser does not support the video tag.
 </video> 
 
-### Settings
+## Settings
 You can define settings for the Custom Tile which get exposed as additional options within the main
 dashboard interface when you edit a tile. To use these within your scripts, you’ll want to use our [stio library](./stio-lib.md) as shown in the snippet below.
 
@@ -26,12 +29,62 @@ dashboard interface when you edit a tile. To use these within your scripts, you
     });
 </script>
 ```
-::: tip
+
+::: tip  
 There are a variety of functions such as `showToast()`, `showList()` and `showForm()` which are included in the stio library. 
-Check out the [stio library](./stio-lib.md) documentation for more details.
+Check out the [stio library](./stio-lib.md) documentation for more details.  
 :::
 
-### Preview
+There are both primitive setting types like String, Numeric, and Boolean as well as enriched setting types like Things and Variables. Primitive setting types have the value directly exposed on the setting key. Enriched setting types enable you to interact with resources like Things and Variables from the SharpTools platform to read values, listen for updates, and send commands.
+
+
+### Primitives
+* **String**: Enables the user to input free form text. 
+* **Numeric**: Enables the user to input numeric values. 
+* **Boolean**: Enables the user to check/uncheck the setting.
+
+
+### Things
+You can define a SharpTools Thing as a setting within your Custom Tile. If you define which capabilities the device must have, the list of things presented to the user when configuring the tile setting will be filtered to devices which match that capability set. This is helpful for ensuring that the device selected by the user will have the attributes and commands you expect for use in your custom code. 
+
+You can interact with the Thing using the [stio library](./stio-lib.md#things) to access attribute values, subscribe to attribute updates, and send device commands.
+
+<img src="../assets/settings/thing-setting-preview.jpeg" alt="Thing Setting Preview" class="zoomable-image" />
+
+::: details Capability Filter Details
+**Filters Match ALL**  
+Please note that if you include more than one capability filter, only devices which match all of the filters are displayed to the user.
+
+For example, if you include both `motionSensor` and `temperatureSensor` capabilities, the user must have a device which implements both of those capabilities. If you want access to a separate motion device and separate temperature device, you'll want to define each as their own setting.
+
+
+**Autocomplete + Custom Capabilities**  
+We've included a list of ~20 popular capabilities as autocompletion values. If you start typing a capability and it matches one of these, you'll be able to select it directly from the drop down.
+
+If you want to use a Custom Capability or a capability that otherwise doesn't exist in the autocompletion list, just type your custom capability and press Enter. Note that you must use the `camelCase` formatted ID of the capability.
+
+::: tip 
+💡 The [SmartThings capabilities documentation](https://developer.smartthings.com/docs/devices/capabilities/capabilities-reference) is a good reference point for capability identifiers even for other platforms we support like Homey and Home Assistant.  
+
+:::
+
+
+
+
+### Variables
+You can define a SharpTools Variable as a setting within your Custom Tile. You must select the specific type of variable to restrict the variable selection to.
+
+You can interact with the Variable using the [stio library](./stio-lib.md#variables) to access the variable value, subscribe to variable updates, and set/update the attribute value.
+
+<img src="../assets/settings/variable-setting-preview.jpeg" alt="Thing Setting Preview" class="zoomable-image" />
+
+
+
+
+
+
+
+## Preview
 When you use the ‘Preview’ button, it will render a copy of the tile below the script editor interface. If you have
 any Tile Settings defined, you’ll be prompted for which values you want to use for the settings (simulating what the
 tile would be like after the user adds the tile to their dashboard and configures it).
@@ -51,7 +104,8 @@ comfortable with the implementation details. SharpTools does not review and is n
 shared by other developers.
 :::
 
-### Update Imported Code
+## Update Imported Code
+Many developers will release updates and enhancements to existing Custom Tiles. These updates are *not* automatically pushed to your account. Instead, you retain control of if and when you would like to update your copy of the custom tile.
 1. Open your [Custom Tile developer tools](https://sharptools.io/developer/custom-tiles/)
 1. Select the custom tile that you imported previously
 1. Scroll down to the source code editor, tap the :gear: in the top-right corner of the code editor and select '**Update from Source**'  

content/developer-tools/custom-tiles/stio-lib.md

@@ -1,26 +1,116 @@
+---
+sidebarDepth: 2
+---
 # `stio` Library
 
 ## Installation / How to Use
 The stio library can be referenced from the CDN as a standard `<script>` tag in the HTML of your Custom Tile:
 
 ```html
-<script src="https://cdn.sharptools.io/js/custom-tiles.js"></script>
+<script src="https://cdn.sharptools.io/js/custom-tiles/0.2.1/stio.js"></script>
 ```
 
+
+If you are updating an older Custom Tile to take advantage of new features, don't forget to update your `stio` library version!  
+
+::: details  
+Starting with release `0.2.x` of the stio library, we’ve implemented semantic versioning. Historically, the stio library was available at a generic URL:
+
+```text
+https://cdn.sharptools.io/js/custom-tiles.js
+```
+
+We will continue to update that generic library URL to point to the latest production version of the library. Since the files are served from a CDN with caching, browsers may hold onto the ‘old’ version of the library for a period of time.
+
+As such, we suggest pointing to the specific versioned instance of the library that is needed for your Custom Tile.
+:::
+
 ## .ready(callback)
 Once the stio library is initialized and the communication channel is ready, it will call the callback function
 that you provide.
 
 ``` js
 stio.ready(function(data){
-console.log('The user specified token is', data.settings.token)
+    console.log('The user specified token is', data.settings.token)
 });
 ```
 Note that the data object which is passed to your callback includes a property called 'settings' which is an object
 that contains the values of the various Tile Settings as they are configured by the user. If the tile is not configured 
 by the user, the values of the individual settings fields will be empty.
 
 
+Enriched settings types such as Things or Variables have additional properties and methods:
+
+### Variables
+The [variable setting type](./html.md#variables) is exposed to your Custom Tile code much text, numeric, or boolean input settings are with the `stio.ready()` callback:
+
+```javascript
+stio.ready(function(data){
+    var myString = data.settings.myString;
+});
+```
+
+Unlike the standard string, numeric, or boolean settings for a tile which expose the raw primitive values, the variable setting is exposed as an enriched object with several properties and methods
+
+**Properties**
+* **`value`**: the current value of the variable
+* **`timestamp`**: the timestamp of the value update of the variable
+* **`id`**: the user specified variable identifier (eg. `$myText` → `myText`)
+
+**Methods**
+* **`setValue(value)`**: update the value of the variable
+  * Make sure to match your input data type with the expected type of the variable
+   ```javascript
+   myBool.setValue(true)
+   myStr.setValue("Ready")
+   myNum.setValue(10)
+   ```
+   &nbsp;
+* **`onValue(callback)`**: the `callback` is called with the updated value anytime the variable value updates
+
+
+
+
+### Things
+The [Thing setting type](./html.md#things) is exposed to your Custom Tile code much like existing text, numeric, or boolean input settings are with the `stio.ready()` callback:
+
+```javascript
+stio.ready(function(data){
+    var myThing = data.settings.myThing;
+});
+```
+
+Unlike the standard string, numeric, or boolean tile settings which expose the raw primitive values, the Thing setting is exposed as an enriched object with several properties and methods
+
+
+**Properties**
+* **`attributes`**: an object containing each of the attributes where the key is the attribute name and the value is an `Attribute` object:
+   * **`value`**: the current value of the attribute
+   * **`timestamp`**: the current timestamp of the attribute value
+   * **`onValue(callback)`**: the `callback` is called with the updated value anytime the attribute value updates
+     * Returns an object with an **`off()`** method if you want to stop listening for updates
+* **`name`**: the device name
+* **`capabilities`**: an array of camelCase capabilities that the device reports that it has implemented (eg. `switch`, `switchLevel`, `colorControl`) 
+
+**Methods**
+* **`sendCommand(command, [argsArray])`**: send the specified command to the device with an optional array of arguments
+   ```javascript
+   myThing.sendCommand("on")
+   myThing.sendCommand("setLevel", [50])
+   ```
+   &nbsp;
+* **`subscribe(attribute)`**: send the request to the supporting smart-home hub to forward events from that device to SharpTools (and our Custom Tile)
+  * Note that you can also pass an array of attribute names if you want to subscribe to multiple attributes from the same thing: 
+  ```javascript
+  myThing.subscribe('switch')
+  myThing.subscribe(['switch', 'switchLevel'])
+  ```
+
+
+
+
+
+
 
 ## .showList(list) `<promise>`