=====Extending The User Interface with Custom Script Actions=====

You can extend the user interface of XTension in several useful ways for adding special actions or scripts for specific units or groups of units.

====Get Contextual Handlers====
Whenever a contextual menu is about to open, or a detailed unit controls window is about to open either in the app or on the web interface, a unit a handler in the Unit’s On script named “GetContextualHandlers” will be called. Based on the current state of the unit you can return a list of things you’d like to be presented. If the user selects one then the corresponding handler in your units On script will be run for you to take custom action. To add this handler to your units On script you can just type it in manually or you can use the “Insert” toolbar button to insert it with some comments of documentation and all ready to accept the rest of your code.

{{ :xtension_manual:flashtwicecontextual.png?direct&400|}}

The simplest example might be to just always return the same thing no matter what.

<code>

on getContextualHandlers()
  return {“Flash Twice”, “Flash 10 times”}
end getContextualHandlers

</code>

This will add 2 items to any contextual menu or detailed unit controls dialog as shown to the right. 

If these are selected XTension will try to run a handler with the same name in the selected Units On script. Since you can’t have spaces in a handler name in AppleScript any spaces will be removed before it tries to find a handler. So “Flash Twice” will run a handler called “FlashTwice” and “Flash 10 Times” will run a handler named “Flash10Times” so your resultant script might be something like:

<code>

on flashTwice()
    repeat 2 times
        toggle (thisUnit)
    end repeat
end flashTwice

on flash10Times()
    repeat 10 times
        toggle (thisUnit)
    end repeat
end flash10Times
    
</code>

In addition to triggering that from the user interface any other script can tell the unit to do it as well by telling the Unit directly like this:

<code>
tell xUnit “name of the unit with the handlers” to flash10Times()
</code>

====Flash Warning====
{{ :xtension_manual:huecolorloop.png?direct&300|}}
If you have some [[supported_hardware:hue|Phillips Hue]] or other color capable devices you may wish to be able to use them for signaling when something has happened. You could extend the interface of your hue bulb to flash a warning for a second and then return to the current normal setting. We’ll call this handler “Flash A Warning”

In the On script of the color capable device add the following script:

<code>

on getContextualHandlers()
  return {“Flash A Warning”}
end getContextualHandlers

on flashAWarning()
   brighten (thisUnit) to 100 rgb color “FF0000” for 4 * seconds
end flashWarning

</code>

You might wish to extend that further to support more of the Hue device features like the color looping. You can add any number of handlers and they will show up in the Detailed Unit Controls as shown to the right. To also add color looping to the bulb in question you can do the following:


<code>

on getContextualHandlers()
  return {“Flash A Warning”, “Begin Color Loop"}
end getContextualHandlers

on flashAWarning()
   brighten (thisUnit) to 100 rgb color “FF0000” for 4 * seconds
end flashWarning

on beginColorLoop()
    blink (thisUnit) rate “colorloop"
end beginColorLoop


</code>

===Also Works on the Web Interface===

{{ :xtension_manual:webcontextualhandlers.png?direct&300 |}}

The same interface running through the Web Interface would look like this. <del>As of this writing there is no contextual menu support on the web interface but the buttons will appear on the web version of the Detailed Unit Controls.</del> XTension version 9.4.3 brings full support for these menus to both the desktop web remote and the Mobile Web Remote.

\\

====Using Groups====

While that works great for individual or special units it’s also possible to add the same handlers to multiple units and add the code in only one place rather than repeatedly in each and every Unit’s On script. All events like these start in the Unit’s On script, and if the handler does not exist, or if you have not returned True from the handler, then the events will start to trickle up. Any Group that the Unit is a member of will also receive the event, but with thisUnit set to the name of the unit to which the event was originally sent so that you can use that to properly control the target unit.




====See Also====
See the tutorial for [[tutorials:addingBatteryChanged|adding a Battery Changed date]] field to a unit list.