User App UI Documentation

🛎️ Get Help Apps
1

Is there any documentation around the UI side of creating a User App?
For example:

dynamicPage(name: "mainPage") {
        section() {
            label(title: "Name", required: false)
            input(name: "devices", type: "capability.switch")
        }
}

Also, I'm just using a text editor. Is there a way to create a "Hubitat Project" in something like VS Code for intellisense?

https://docs.hubitat.com/index.php?title=App_Code

2

Sorry for the state of the documentation.

First of all, look at the Example Apps in our public repo: HubitatPublic/example-apps at master · hubitat/HubitatPublic · GitHub

That will show you some of the basics.

Here is a bit of a quick summary:

Apps render pages. 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 are intermixed of course along with computations. Use what are called dynamic pages for the best control of the UI; these are shown in the example apps.

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 parens omitted, with the name and type being implicit, like this:

input "my-element", "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 variable name), or with settings["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 "thisSthat" Settings 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 these:

  • "capability.capability-name" --> device wrapper object (see capability reference in the developer docs); this is the device selector means.
  • "text" --> String
  • "textarea" --> String (from a multi-line re-sizable text box, parameter rows:number-of-rows is optional, with 2 the default)
  • "number" --> Integer
  • "decimal" --> Double
  • "enum" --> List (this type requires List options: List my-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.

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.

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

My suggestion is to play around with it, play around with the example apps...

9 Likes