App Overview

Apps on Hubitat Elevation are the means by which users configure automations. Hubitat comes with several built-in apps (e.g., Room Lighting, Button Controller, Notifications, and more), but it is also possible to write user apps (also known as custom apps) by adding code under Apps Code.

These apps are written in Groovy 2.4 and run inside the Hubitat Elevation app execution environment. This environment is a sandbox that provides Hubitat-specific methods for convenience (see more in the other Developer guides for apps, drivers, and common methods) and security (e.g., apps can only run commands on devices the user has selected in the app, and a reasonable subset of Groovy/Java classes is allowed while others, like System methods, are not).

A special type of app sometimes called an integration app or service manager can be used to handle LAN, cloud, or other device integrations to either make handling communications with these devices easier for the developer or make setup and management easier for the user. This document focus primarily on apps intended to create automations.

User Interface

The user interface of an app is defined inside preferences, which can consist of one or more pages or dynamicPages (or for single-page apps, the page can be omitted entirely and the inputs, etc. provided directly inside preferences, though this provides less control over the UI). Within those pages there are means to get an input from a user, and means to present text and others items to the user. These can be intermixed along with computations in dynamic pages, which provide the most control of the UI; these are shown in the example apps.

Input Method

For inputs into apps from the UI the method is called input(). It has this format:

input(String name: element-name, String type: element-type, String title: element-title, ... additional options)

These can be abbreviated and the parentheses omitted, with the name and type being implicit, like this:

input "my-name", "my-type", title: "My Input"

Each input creates a setting with the name specified in the input. These can be accessed in the app directly with the name (as if it were a field/variable name), or with settings["my-name"]. Some care must be used therefore with input names, so as not to conflict with variable names. It can be useful to construct input names (and corresponding setting keys) with G-strings, such as "this$that". Thesettings object is a Map with key being the input name, and value being the input value from the user. Settings names accessed by the input name directly have scope across the entire app.

Input types include:

• capability.capability-name:  device wrapper object (see capability reference in the developer docs); this provides a way for the user to select a device of the specified capability
• text: String
• textarea:  String (from a multi-line re-sizable text box; parameter rows is optional, for number of rows, with 2 the default)
• number: Integer
• decimal: Double
• enum: List (this type requires a parameter options of type List with the options); this is a pull-down menu.
• bool: Boolean; this is an on/off slider.
• time: dateTime String (formatted "yyyy-MM-dd'T'HH:mm:ss.sssXX"); this pulls up a time picker.
• date: date String; this pulls up a date picker.
• color: color Map; this pulls up a color picker.
• button: renders a UI button with the title in the button; generates a callback to a method defined in the app called appButtonHandler(String button-name), which is passed the String name of the input when the UI button is pressed, which also causes a page refresh. As a callback, the appButtonHandler method is not called within the page where the button is rendered, so it cannot render anything itself, but can only set state to be dealt with by the page method upon its refresh.

It is possible to put HTML tags into input titles. The options of an enum can be a List of Maps, where the key of the map element is returned while the String value is displayed in the pull down menu. For capability and enum inputs an optional parameter of multiple: true is allowed, such that a List is returned instead of a single element. A defaultValue: value can be specified for an input, however this value will not be assigned to the corresponding setting until the page is refreshed.

There is rudimentary formatting available for inputs, including width:number, where the width can be 1 to 12, with 12 being the full width for a desktop screen, and 4 for a mobile device screen, newLine: true, newLineAfter: true, style: "style-descriptor". The submitOnChange: true causes the page to be refreshed upon completion of the input by the user. This is the normal way to use inputs, and allows for the progression of the UI as the user interacts with the app. Optional required:true forces an input to be completed before leaving the page.

Paragraph

For output, the method is paragraph String paragraph-text. This may include HTML to create tables, or other presentation elements. It is possible to use limited JavaScript in the paragraph text.

href

It possible to bring up additional pages using href, and it is possible to pass parameters to such a page.

Examples

Some examples can be found in the the HubitatPublic GitHub repository: https://github.com/hubitat/HubitatPublic/tree/master/example-apps