327
edits
Changes
no edit summary
== Introduction ==
== Introduction ==
Action blocks allow you to group related actions together that can then be called from elsewhere as a single action.
== Output Parameters ==
The action blocks feature can be accessed from the "Action Blocks" home screen tile. Pressing this will take you to a list of currently defined action blocks (or an empty list if you haven't defined any yet). From this list you can press the + button to add a new action block.
Each action block must be given a unique name and contain at least one action. A description is optional and you can also specify input and/or output parameters if you desire.
== When to Use ==
The main reason to use action blocks is to minimize duplicated blocks of action throughout your macros. In some cases you may have common repeated functionality spread throughout multiple macros, for example you may set the brightness low and volume to zero at night time (using day/time trigger) in one macro. You may also wish to do the same elsewhere in another macro (for example using a location trigger when you are at the cinema). By grouping these actions into an action block you can call just a single action to invoke the action block. If you later decide to tweak these settings then you can just update the action block and avoid updating the settings in multiple places.
== Input and Output Parameters ==
For more advanced use cases, action blocks allow you the option to pass in input parameters and return output parameters. In this way an action block may be used in a similar way to a function in computer programming.
For example suppose you wanted to convert from Celsius to Fahrenheit from within multiple macros. You could create an action block to do this that will take in an input parameter in Celsius and return an output parameter in Fahrenheit. The input parameters are available as local variables anywhere it makes sense to read a value. For example you can access the local variable in a pop up message, or in an expression when setting another variable value. The output variables are available as local variables anywhere it makes sense to set the value. For example in the set variable action you can assign to any output parameter.
Each input parameter will specify a default value and this value will be set in the case where you run a local test of the action block. Likewise all output parameters define a default value. In the case that the action block doesn't set an explicit value on an output parameter, it's default value will be returned.
When calling the action block you can specify what values will be passed in as input parameters and assign variables (either local or global) to capture the returned output parameters. You can also ignore any or all return parameters if you desire.