How to Use Dictionaries in Formulas

Dictionaries and Formulas

Dictionaries allow you to deploy applications to end-users (RUN users) in any language. You can reference dictionary keys from within dashboard widgets to create dynamic titles and button headers that will appear in the language of the users choice. You can also reference dictionaries in formulas. In this tutorial, I will show you how to do this and also why you might want to.

Sending Device Data

The first thing you need to do is to identify or create the device data for your widget. In my case, I have a temperature sensor that will send temperature data and metadata “status” and “color”

Creating the Widget

After creating a tile widget to display this devices data, the dashboard displays the following

Editing the Widget

Now click to edit your widget and navigate to the Formula and unit dropdown. Here, click to enable formula

The following is an example of the type of formula you can apply to your device variables.

Note: The VALUE references the most current value of your variable. Similaraly, the metadata field of a device can be referenced with METADATA.<key>

Creating a Dictionary

Now I will create a new dictionary and add two value, “ON” and “OFF.”

I will also add a French translation for my dictionary.

Referencing a Dictionary Within a Widget

Going back to the widget settings, I can set the formula to

equalText(metadata.status, “on”) ? “#IOTDICT.ON#” : "#IOTDICT.OFF#"

equalText(“x”,“y”) is a function of the MathJS library that returns true if the two strings being compared, in this case the field referenced by metadata.status and “on” and false otherwise. The formula is also framed as a ternary operation so that if equalText() returns true, the title will be set to whatever #IOTDICT.ON# refers to and if equalText() return false, the title will be set to whatever #IOTDICT.OFF# refers to.

Dictionary keys are referenced in the format #SLUG.KEY#. In this case the slug for the dictionary is IOTDICT and the key is ON

Now, because the value of the metadata field “status” is “on” given the package sent at the beginning of the tutorial, the function equalText(metadata.status, “on”) is equivalent to equalText( “on”, “on”) which returns true and thus sets the title to #IOTDICT.ON# which is equivalent to “Device is On”

Now, if this application was deployed with RUN and a user decided to switch their language preferences to french, the same message would display like the following (in an actual deployment the rest of the application would be configured with dictionaries to translate fully into French).