This page is part of archived documentation for openHAB 4.1. Go to the current stable version

# oh-button - Button

Button performing an action

oh-button header

# Usage / reference documents

# Configuration

# General

# text Text TEXT

Button label

# round Round BOOLEAN

Makes button round

# large Large BOOLEAN

Makes button large

# small Small BOOLEAN

Makes button small

# fill Fill BOOLEAN

Makes button filled with color

# raised Raised BOOLEAN

Makes button raised

# outline Outline BOOLEAN

Makes button outline

# active Active TEXT

Button is active (when part of a f7-segmented

# iconF7 Icon TEXT

Framework7 icon to display (Framework7 icon)

# iconMaterial Icon TEXT

Material design icon to display

# iconColor Icon Color TEXT

Not applicable to openHAB icons

# iconSize Icon Size INTEGER

Size of the icon in px

# tooltip Tooltip TEXT

Button tooltip text to show on button hover/press

# variable Variable TEXT

Name of the variable to set on input change

# variableKey Variable Key TEXT

Consider the variable value is an object and set the corresponding deep property within that object using a key syntax. Examples: user.name, user[0].address[1].street, [0], [0].label. The inner property and its parent hierarchy will be created if missing.

# clearVariable Clear Variable After Action BOOLEAN

Name of the variable to clear after performing the action

# clearVariableKey Clear Object Variable Property After Action BOOLEAN

Consider the variable value is an object and remove a corresponding deep property within that object using a key syntax. Examples: user.name, user[0].address[1].street, [0], [0].label. The property will be removed after performing the action.

# Action

Action to perform when the element is clicked

# action Action TEXT

Type of action to perform

Options:
navigate
Navigate to page
command
Send command
toggle
Toggle Item
options
Command options
rule
Run scene, script or rule
popup
Open popup
popover
Open popover
sheet
Open sheet
photos
Open photo browser
group
Group details
analyzer
Analyze item(s)
url
External URL
variable
Set Variable

# actionUrl Action URL TEXT url

URL to navigate to

# actionUrlSameWindow Open in same tab/window BOOLEAN

Open the URL in the same tab/window instead of a new one. This will exit the app.

# actionItem Action Item TEXT item

Item to perform the action on

# actionCommand Action Command TEXT

Command to send to the Item. If "Toogle Item" is selected as the action, only send the command when the state is different

# actionCommandAlt Action Toggle Command TEXT

Command to send to the Item when "Toggle Item" is selected as the action, and the Item's state is equal to the command above

# actionOptions Command Options TEXT

Comma-separated list of options; if omitted, retrieve the command options from the Item dynamically. Use value=label format to provide a label different than the option.

# actionRule Scene, Script or Rule TEXT rule

Scene, Script or Rule to run

# actionRuleContext Context TEXT script

Object representing the optional context to pass. Edit in YAML or provide a JSON object, e.g. { "param1": "value1", "param2": { "subkey1": "testing", "subkey2": 123 } }.

# actionPage Page TEXT page

Page to navigate to

# actionPageTransition Transition Effect TEXT

Options:
f7-circle
Circle
f7-cover
Cover
f7-cover-v
Cover from bottom
f7-dive
Dive
f7-fade
Fade
f7-flip
Flip
f7-parallax
Parallax
f7-push
Push

# actionModal Modal Page or Widget TEXT pagewidget

Page or widget to display in the modal

# actionModalConfig Modal component configuration TEXT props

Configuration (prop values) for the target modal page or widget

# actionPhotos Images to show TEXT

Array of URLs or objects representing the images. Auto-refresh is not supported.
Edit in YAML, e.g.

- item: ImageItem1
caption: Camera
or provide a JSON array, e.g.
[ "url1", { "item": "ImageItem1", "caption": "Camera" } ]
Objects are in the photos array format with an additional item property to specify an item to view.

# actionPhotoBrowserConfig Photo browser configuration TEXT

Configuration for the photo browser.
Edit in YAML or provide a JSON object, e.g.
{ "exposition": false, "type": "popup", "theme": "dark" }
See photo browser parameters (not all are supported).

# actionGroupPopupItem Group Popup Item TEXT item

Group Item whose members to show in a popup

# actionAnalyzerItems Item(s) to Analyze TEXT item

Start analyzing with the specified (set of) Item(s)

# actionAnalyzerChartType Chart Type TEXT

The initial analyzing period - dynamic or a predefined fixed period: day, week, month or year

Options:
(empty)
Dynamic
day
Day
isoWeek
Week (starting on Mondays)
month
Month
year
Year

# actionAnalyzerCoordSystem Initial Coordinate System TEXT

The initial coordinate system of the analyzer - time, aggregate or calendar (only time is supported for dynamic periods)

Options:
time
Time
aggregate
Aggregate
calendar
Calendar

# actionFeedback Action feedback TEXT

Shows a toast popup when the action has been executed. Can either be a text to show or a JSON object including some of the supported parameters

# actionVariable Variable TEXT

The variable name to set

# actionVariableValue Variable Value TEXT

The value to set the variable to

# actionVariableKey Variable Key TEXT

Consider the variable value is an object and set the corresponding deep property within that object using a key syntax. Examples: user.name, user[0].address[1].street, [0], [0].label. The inner property and its parent hierarchy will be created if missing.

# Tap Hold

Action performed when tapping and holding card (or calling contextual menu on desktop)

# taphold_action Action TEXT

Type of action to perform

Options:
navigate
Navigate to page
command
Send command
toggle
Toggle Item
options
Command options
rule
Run scene, script or rule
popup
Open popup
popover
Open popover
sheet
Open sheet
photos
Open photo browser
group
Group details
analyzer
Analyze item(s)
url
External URL
variable
Set Variable

# taphold_actionUrl Action URL TEXT url

URL to navigate to

# taphold_actionUrlSameWindow Open in same tab/window BOOLEAN

Open the URL in the same tab/window instead of a new one. This will exit the app.

# taphold_actionItem Action Item TEXT item

Item to perform the action on

# taphold_actionCommand Action Command TEXT

Command to send to the Item. If "Toogle Item" is selected as the action, only send the command when the state is different

# taphold_actionCommandAlt Action Toggle Command TEXT

Command to send to the Item when "Toggle Item" is selected as the action, and the Item's state is equal to the command above

# taphold_actionOptions Command Options TEXT

Comma-separated list of options; if omitted, retrieve the command options from the Item dynamically. Use value=label format to provide a label different than the option.

# taphold_actionRule Scene, Script or Rule TEXT rule

Scene, Script or Rule to run

# taphold_actionRuleContext Context TEXT script

Object representing the optional context to pass. Edit in YAML or provide a JSON object, e.g. { "param1": "value1", "param2": { "subkey1": "testing", "subkey2": 123 } }.

# taphold_actionPage Page TEXT page

Page to navigate to

# taphold_actionPageTransition Transition Effect TEXT

Options:
f7-circle
Circle
f7-cover
Cover
f7-cover-v
Cover from bottom
f7-dive
Dive
f7-fade
Fade
f7-flip
Flip
f7-parallax
Parallax
f7-push
Push

# taphold_actionModal Modal Page or Widget TEXT pagewidget

Page or widget to display in the modal

# taphold_actionModalConfig Modal component configuration TEXT props

Configuration (prop values) for the target modal page or widget

# taphold_actionPhotos Images to show TEXT

Array of URLs or objects representing the images. Auto-refresh is not supported.
Edit in YAML, e.g.

- item: ImageItem1
caption: Camera
or provide a JSON array, e.g.
[ "url1", { "item": "ImageItem1", "caption": "Camera" } ]
Objects are in the photos array format with an additional item property to specify an item to view.

# taphold_actionPhotoBrowserConfig Photo browser configuration TEXT

Configuration for the photo browser.
Edit in YAML or provide a JSON object, e.g.
{ "exposition": false, "type": "popup", "theme": "dark" }
See photo browser parameters (not all are supported).

# taphold_actionGroupPopupItem Group Popup Item TEXT item

Group Item whose members to show in a popup

# taphold_actionAnalyzerItems Item(s) to Analyze TEXT item

Start analyzing with the specified (set of) Item(s)

# taphold_actionAnalyzerChartType Chart Type TEXT

The initial analyzing period - dynamic or a predefined fixed period: day, week, month or year

Options:
(empty)
Dynamic
day
Day
isoWeek
Week (starting on Mondays)
month
Month
year
Year

# taphold_actionAnalyzerCoordSystem Initial Coordinate System TEXT

The initial coordinate system of the analyzer - time, aggregate or calendar (only time is supported for dynamic periods)

Options:
time
Time
aggregate
Aggregate
calendar
Calendar

# taphold_actionFeedback Action feedback TEXT

Shows a toast popup when the action has been executed. Can either be a text to show or a JSON object including some of the supported parameters

# taphold_actionVariable Variable TEXT

The variable name to set

# taphold_actionVariableValue Variable Value TEXT

The value to set the variable to

# taphold_actionVariableKey Variable Key TEXT

Consider the variable value is an object and set the corresponding deep property within that object using a key syntax. Examples: user.name, user[0].address[1].street, [0], [0].label. The inner property and its parent hierarchy will be created if missing.

# Inherited Properties

The configuration is passed to the underlying f7-button component from Framework7 v5. All compatible scalar properties (opens new window) (except functions) not listed above are available for use.

# Slots

# default

The contents of the button.

# Examples

# Header Image Source Code

This example code generates the button image used at the top of this page:

YAML
uid: oh-button
tags: []
timestamp: Feb 9, 2021, 5:42:56 PM
component: f7-card
config:
  title: oh-button
slots:
  default:
    - component: f7-block
      config:
        class: bog
        style:
          display: flex
          flex-wrap: wrap
          justify-content: space-between
          align-content: space-between
          height: 230px
          padding-bottom: 20px
      slots:
        default:
          - component: oh-button
            config:
              width: 400px
              text: Basic button
          - component: oh-button
            config:
              width: 400px
              text: Rounded + Outline
              round: true
              outline: true
          - component: oh-button
            config:
              text: Large
              outline: true
              large: true
              grid-colum: 3
              grid-row: 1
          - component: oh-button
            config:
              text: Small + Outline
              outline: true
              small: true
          - component: oh-button
            config:
              text: Filled
              fill: true
          - component: oh-button
            config:
              text: Raised
              fill: true
              raised: true
          - component: oh-button
            config:
              text: Outline
              outline: true
          - component: oh-button
            config:
              text: f7 icon
              iconF7: arrow_right_arrow_left_square_fill
              tooltip: Click to view f7 icons
              action: url
              actionUrl: https://framework7.io/icons/
          - component: oh-button
            config:
              text: Material icon
              iconMaterial: fingerprint
              tooltip: Click to view Material icons
              action: url
              actionUrl: https://material.io/resources/icons/
          - component: oh-button
            config:
              text: Icon color
              iconMaterial: power_settings_new
              iconColor: green
          - component: oh-button
            config:
              text: 40px icon, with custom button height to fit it!
              outline: true
              fill: true
              iconMaterial: report_problem
              iconSize: 40
              style:
                height: 80px
                width: 300px
                white-space: normal
          - component: oh-button
            config:
              text: Tooltip - hover over me
              tooltip: Don't Panic
          - component: oh-button
            config:
              text: Set variable 'myVariable'
              variable: myVariable
              action: variable
              actionVariable: myVariable
              actionVariableValue: 1
          - component: oh-button
            config:
              text: Clear variable 'myVariable'
              clearVariable: myVariable
              action: variable
              actionVariable: myVariable
          - component: f7-segmented
            slots:
              default:
                - component: oh-button
                  config:
                    text: Option 1
                    outline: true
                    style:
                      width: 200px
                - component: oh-button
                  config:
                    text: Option 2 (Active)
                    outline: true
                    active: true
                    style:
                      width: 200px
                - component: oh-button
                  config:
                    text: Option 3
                    outline: true
                    style:
                      width: 200px

# action: navigate

action navigate

action: navigate allows you to navigate to another page (Administration -> Settings -> Pages) within the openHAB application. The target page is specified with the name of the page in the actionPage property. For example to create a button to take users to the main overview (home) page, set actionPage: page:overview. The value after the page: is the page ID not the page Label.

YAML

























 
 



uid: oh-button-action-navigate
tags: []
timestamp: Feb 15, 2021, 8:32:44 PM
component: f7-card
config:
  title: "oh-button > action: navigate"
slots:
  default:
    - component: f7-block
      config:
        class: bog
        style:
          display: flex
          flex-wrap: wrap
          justify-content: space-between
          align-content: space-between
          padding: 20px
      slots:
        default:
          - component: oh-button
            config:
              width: 400px
              iconF7: house_fill
              text: Home Page
              outline: true
              action: navigate
              actionPage: page:overview
              style:
                width: 250px

# action: command

action command

action: command allows you to send a command actionCommand to an item, specified in the actionItem. This example shows how to send ON and OFF commands to an item e.g. a light, using two buttons.

YAML







































 
 
 
 






 
 
 
 



uid: oh-button-action-command
tags: []
props:
  parameters:
    - context: item
      description: Select the item to use with these buttons.
      label: Item
      name: item
      required: true
      type: TEXT
      groupName: general
  parameterGroups:
    - name: general
      label: Display options
timestamp: Feb 15, 2021, 9:21:10 PM
component: f7-card
config:
  title: "oh-button > action: command"
  footer: Set the properties to any item that accepts an ON/OFF commands
slots:
  default:
    - component: f7-block
      config:
        class: bog
        style:
          display: flex
          flex-wrap: wrap
          justify-content: space-between
          align-content: space-between
          padding: 20px
      slots:
        default:
          - component: f7-segmented
            slots:
              default:
                - component: oh-button
                  config:
                    text: On
                    outline: true
                    action: command
                    actionItem: =props.item
                    actionCommand: ON
                    active: "=(items[props.item].state === 'ON') ? true : false"
                    style:
                      width: 100px
                - component: oh-button
                  config:
                    text: Off
                    outline: true
                    action: command
                    actionItem: =props.item
                    actionCommand: OFF
                    active: "=(items[props.item].state === 'OFF') ? true : false"
                    style:
                      width: 100px

# action: toggle

action toggle

action: toggle is used to change any item that supports two states e.g. a lamp that is either ON or OFF or blinds that are OPEN or CLOSED. Use actionCommand and actionCommandAlt to specify the commands to switch between.

If you need the item to change to more than two states e.g. a dimmable light, see the previous example and specify a button for each of the dimming levels required e.g. 0%, 25%, 50% 75%, 100% or use actionOptions to select the required option.

YAML




































 
 
 
 



uid: oh-button-action-toggle
tags: []
props:
  parameters:
    - context: item
      description: Select the item to use with these buttons.
      label: Item
      name: item
      required: true
      type: TEXT
      groupName: general
  parameterGroups:
    - name: general
      label: Display options
timestamp: Feb 15, 2021, 9:55:56 PM
component: f7-card
config:
  title: "oh-button > action: toggle"
  footer: Set the properties to any item that accepts an ON/OFF commands
slots:
  default:
    - component: f7-block
      config:
        class: bog
        style:
          display: flex
          flex-wrap: wrap
          justify-content: space-between
          align-content: space-between
          padding: 20px
      slots:
        default:
          - component: oh-button
            config:
              text: Off
              outline: true
              action: toggle
              actionItem: =props.item
              actionCommand: ON
              actionCommandAlt: OFF
              style:
                width: 100px

# action: options

action options

action: options provides the ability to send a command from a list of options. Options are displayed at the bottom of the screen when the button is clicked. Options are specified either in the actionOptions property or if this is omitted from the Command Options metadata specified on the item.

YAML
uid: oh-button-action-options
tags: []
props:
  parameters:
    - context: item
      description: Select the item to use with these buttons.
      label: Item
      name: item
      required: true
      type: TEXT
      groupName: general
  parameterGroups:
    - name: general
      label: Display options
timestamp: Feb 15, 2021, 11:57:34 PM
component: f7-card
config:
  title: "oh-button > action: options"
  footer: Set the properties to any item that accepts percentage commands e.g. dimmable light
slots:
  default:
    - component: f7-block
      config:
        class: bog
        style:
          display: flex
          flex-wrap: wrap
          justify-content: left
          padding: 20px
      slots:
        default:
          - component: f7-segmented
            slots:
              default:
                - component: oh-button
                  config:
                    text: Dimming Level
                    outline: true
                    action: options
                    actionOptions: 0=Off, 25=25%, 50=50%, 75=75%, 100=Full
                    actionItem: =props.item
                    style:
                      width: 300px

# action: rule

action: rule is used with the actionRule property to run a rule (Administration > Settings > Rules).

YAML




 

































 
 



uid: oh-button-action-rule
tags: []
props:
  parameters:
    - context: rule
      description: Click the button to run a rule.
      label: Rule Name
      name: rule
      required: true
      type: TEXT
      groupName: general
  parameterGroups:
    - name: general
      label: Display options
timestamp: Feb 16, 2021, 12:10:45 AM
component: f7-card
config:
  title: "oh-button > action: rule"
  footer: Set the properties to a rule to run.
slots:
  default:
    - component: f7-block
      config:
        class: bog
        style:
          display: flex
          flex-wrap: wrap
          justify-content: left
          padding: 20px
      slots:
        default:
          - component: f7-segmented
            slots:
              default:
                - component: oh-button
                  config:
                    text: Run automation rule
                    fill: true
                    action: rule
                    actionRule: =props.rule
                    style:
                      width: 300px

# action: popup / action: popover / action: sheet

The popup, popover and sheet actions provide a way to display user interface pages in specific window formats. Typically these screens are used to display additional detail or access additional settings that have been omitted for brevity from the parent page.

Pages should normally be specifically designed for your chosen display method. The popover area favours organisation of widgets in columns, but the sheet window occupies the full width of the lower part of the screen and therefore a horizontal layout is preferable.

The example code simply displays a copy of your main 'Overview' page (as all users have this page) in each window style. As this page is rarely designed with this purpose in mind the design challenge is usually clear!

  • action: popup is used with the actionModal property to open a page as a modal popup window in the centre of the screen. Clicking on the Back button or anywhere else on the screen will close the popup window.
  • action: popover is used with the actionModal property to open a page as a modal popup window as a vertical rectangle to the left of the screen (over the menu area, if displayed).
  • action: sheet is used with the actionModal property to open a page as a modal popup windows as a horizontal rectangle across the bottom of the screen.
YAML
uid: oh-button-action-popup-popover-sheet
tags: []
timestamp: Feb 16, 2021, 1:01:08 AM
component: f7-card
config:
  title: "oh-button > action: popup | action: popover | action: sheet"
  footer: Set the properties to any item that accepts percentage commands e.g. dimmable light
slots:
  default:
    - component: f7-block
      config:
        class: bog
        style:
          display: flex
          justify-content: left
          padding: 20px
      slots:
        default:
          - component: oh-button
            config:
              text: Open PopUp
              outline: true
              action: popup
              actionModal: page:overview
              style:
                width: 300px
                margin-right: 10px
          - component: oh-button
            config:
              text: Open PopOver
              outline: true
              action: popover
              actionModal: page:overview
              style:
                width: 300px
                margin-right: 10px
          - component: oh-button
            config:
              text: Open Sheet
              outline: true
              action: sheet
              actionModal: page:overview
              style:
                width: 300px

# action: photos

action photos

action: photos allows you to open a Framework 7 (v5) Photo Browser object (opens new window). This component displays a collection of photos and video images. Photos can be zoomed and panned. Typical applications for this control include the display of security camera images or videos.

actionPhotos accepts a YAML or JSON object that specifies the URL or HTML and captions for your images and videos.

  actionPhotos:
    - url: http://openhabian:8080/static/photos/image1.jpg
      caption: Image 1
    - url: http://openhabian:8080/static/photos/image2.jpg
    - html: <video src="http://openhabian:8080/static/videos/video1.mp4"></video>
      caption: Garden Camera

The actionPhotoBrowserConfig accepts a YAML or JSON array that specifies the configuration properties for the Photo Browser object.

  actionPhotoBrowserConfig:
    exposition: false
    type: popup
    theme: dark
YAML

Amend the file names / URL to your image file names before testing! Nothing will be displayed if the image/video locations are not valid.

uid: oh-button-action-photos
tags: []
timestamp: Feb 16, 2021, 3:17:05 PM
component: f7-card
config:
  title: "oh-button > action: photos"
  footer: Click to open the Photo Browser dialogue
slots:
  default:
    - component: f7-block
      config:
        class: bog
        style:
          display: flex
          flex-wrap: wrap
          justify-content: space-between
          align-content: space-between
          padding: 20px
      slots:
        default:
          - component: oh-button
            config:
              text: Camera 1
              outline: true
              action: photos
              actionItem: =props.item
              actionPhotos:
                - url: http://openhabian:8080/static/photos/image1.jpg
                  caption: Image 1
                - url: http://openhabian:8080/static/photos/image2.jpg
                - html: <video src="http://openhabian:8080/static/videos/video1.mp4"></video>
                  caption: Garden Camera
              actionPhotoBrowserConfig:
                exposition: false
                type: popup
                theme: dark

# action: group

action-group

action: group opens a popup which displays the items that are members of the group specified by the actionGroupPopupItem.

YAML

Change actionGroupPopupItem property to a value that matches a group defined in your own configuration.

uid: oh-button-action-group
tags: []
timestamp: Feb 16, 2021, 4:20:16 PM
component: f7-card
config:
  title: "oh-button > action: group"
  footer: Click to show the items in the Lounge
slots:
  default:
    - component: f7-block
      config:
        class: bog
        style:
          display: flex
          flex-wrap: wrap
          justify-content: space-between
          align-content: space-between
          padding: 20px
      slots:
        default:
          - component: oh-button
            config:
              text: Lounge
              outline: true
              action: group
              actionGroupPopupItem: gLounge

# action: analyzer

action-analyzer

action: analyzer opens a popup which displays a graph based on the values of the items listed in actionAnalyzerItems. Multiple items can be specified in actionAnalyzerItems using the YAML list format i.e. [item1,item2,item3].

actionAnalyzerChartType specifies the initial period to analyze. If no value is specified initial period is dynamic. Periods can be adjusted after the graph is displayed, using the standard controls.

actionAnalyzerCoordSystem specifies the initial coordinate system of the analyzer. Only time is supported for dynamic periods.

Beware NULL values

If your graph does not display any data, check that none of items added to the graph are NULL. A single NULL item prevents all data from being displayed.

YAML

Change actionAnalyzerItems property to a value that matches an item defined in your own configuration.

uid: oh-button-action-analyzer
tags: []
timestamp: Feb 16, 2021, 5:37:45 PM
component: f7-card
config:
  title: "oh-button > action: analyzer"
  footer: Click to analyze ground floor HVAC temperatures
slots:
  default:
    - component: f7-block
      config:
        class: bog
        style:
          display: flex
          flex-wrap: wrap
          justify-content: space-between
          align-content: space-between
          padding: 20px
      slots:
        default:
          - component: oh-button
            config:
              text: HVAC Ground Floor
              fill: true
              action: analyzer
              actionAnalyzerItems: [ZWaveNode002StellaZThermostaticValve_Sensortemperature, ZWaveNode005StellaZThermostaticValve_Sensortemperature]

# action: url

action-url

action: url navigates to the web page specified in the actionUrl property. actionUrlSameWindow set to true to open in the same window, or false to open in a seperate window\tab.

YAML
uid: oh-button-action-url
tags: []
timestamp: Feb 16, 2021, 6:52:30 PM
component: f7-card
config:
  title: "oh-button > action: url"
  footer: Click to open the specified website
slots:
  default:
    - component: f7-block
      config:
        class: bog
        style:
          display: flex
          justify-content: left
          padding: 20px
      slots:
        default:
          - component: oh-button
            config:
              text: OpenHAB Community
              fill: true
              action: url
              actionUrl: https://community.openhab.org/
              actionUrlSameWindow: false
              style:
                width: 300px
                margin-right: 10px
          - component: oh-button
            config:
              text: Documentation (same window)
              fill: true
              action: url
              actionUrl: https://www.openhab.org/docs/
              actionUrlSameWindow: treu
              style:
                width: 300px
                margin-right: 10px

# action: variable

action: variable creates and/or sets the variable specified in actionVariable to the value specified in actionVariableValue. Variables are stored in the vars object and can be accessed by other objects using vars.[your variable name].

YAML
TBA

# Community Resources

UI Widget: Keypad

UI Widget: Keypad (opens new window) - using action: command and action: variable, this widget will allow users to enter a numerical PIN code (plus * and #) and send a command with the result to a predefined item when pressing the Send button.

Big Ol' Grid O' Buttons

BoGoB: Big Ol' Grid O' Buttons (opens new window) - using the oh-button and oh-repeater objects together with YAML arrays to create large grids of buttons (emulating remote control operation).