diff --git a/.vuepress/docs-sidebar.js b/.vuepress/docs-sidebar.js index 3cc597a49e..e40633ae8c 100644 --- a/.vuepress/docs-sidebar.js +++ b/.vuepress/docs-sidebar.js @@ -152,9 +152,16 @@ module.exports = [ children: [ 'ui/', 'ui/sitemaps', - { title: 'Pages', + { title: 'Page Types', children: [ - 'ui/layout-pages', + { title: 'Layout Pages', + collapsable: true, + path: '/docs/ui/layout-pages', + children: [ + ['/docs/ui/layout-pages-responsive', 'Responsive Layouts'], + ['/docs/ui/layout-pages-fixed', 'Fixed Layouts'] + ] + }, 'ui/map-pages', 'ui/floorplan-pages', 'ui/tabbed-pages', diff --git a/images/addons/wolfsmartset.png b/images/addons/wolfsmartset.png new file mode 100644 index 0000000000..69611d5e63 Binary files /dev/null and b/images/addons/wolfsmartset.png differ diff --git a/tutorials/getting_started/pages_intro.md b/tutorials/getting_started/pages_intro.md index ecf2ebdcbc..889454060e 100644 --- a/tutorials/getting_started/pages_intro.md +++ b/tutorials/getting_started/pages_intro.md @@ -42,18 +42,18 @@ These are most of the parts of openHAB that you have been interacting with thus Notice the new Settings and Developer Tools menus are accessible to administrators. -## Other User Interfaces +## Pages and Other User Interfaces Every openHAB deployment is unique. -Consequently every administrator of an openHAB instance will need to create a custom interface for the users of their bespoke home automation system. +Consequently, every administrator of an openHAB instance will need to create a custom interface for the users of their bespoke home automation system. openHAB provides a number of options to support this in addition to MainUI Pages. Interface | Purpose | How the UI is Defined | Notes -|-|-|- +[Pages]({{base}}/ui/index.html) | Built into MainUI. Allows for a rich set of options to present your home automation. | Can be built automatically through the semantic model as well as customized which includes [Layout Pages]({{base}}/ui/layout-pages.html), [Map Pages]({{base}}/ui/map-pages.html), [Floorplan Pages]({{base}}/ui/floorplan-pages.html), [Tabbed Pages]({{base}}/ui/tabbed-pages.html) and [Chart Pages]({{base}}/ui/chart-pages.html). [Sitemaps]({{base}}/ui/sitemaps.html) | A simple declaritive way to define a simple user interface | Created using .sitemap files or through MainUI. | Used by BasicUI and the phone apps by default. [HABPanel]({{base}}/ui/habpanel/habpanel.html) | UI designed for fixed wall mounted tablets and similar touch screen displays using a blocks interface (e.g. the Windows 10 start menu) with a lot of customization options. | Built graphically though the browser. A number of custom widgets are defined and installable. [HABot]({{base}}/ui/habot/) | Provides a basic chatbot interface to interact with your home automation through natural langauge. | Requires the configuration of the semantic model. -[Pages]({{base}}/ui/index.html) | Built into MainUI. Allows for a rich set of options to present your home automation. | Can be built automatically through the semantic model as well as customized. Once installed, any non-Pages UI can be accessed in the "Other Apps" menu that pops up when clicking on the square icon in the upper right corner of the MainUI Overview page (the first page you see when first accessing openHAB). diff --git a/ui/images/configure-canvas.png b/ui/images/configure-canvas.png new file mode 100644 index 0000000000..3354d50cf1 Binary files /dev/null and b/ui/images/configure-canvas.png differ diff --git a/ui/images/configure-grid.png b/ui/images/configure-grid.png new file mode 100644 index 0000000000..4a213e3b0b Binary files /dev/null and b/ui/images/configure-grid.png differ diff --git a/ui/images/fixed-layout-sample.png b/ui/images/fixed-layout-sample.png new file mode 100644 index 0000000000..cc00ac96ef Binary files /dev/null and b/ui/images/fixed-layout-sample.png differ diff --git a/ui/images/interactive-bulb-off.png b/ui/images/interactive-bulb-off.png new file mode 100644 index 0000000000..650dbf2e11 Binary files /dev/null and b/ui/images/interactive-bulb-off.png differ diff --git a/ui/images/interactive-bulb-on.png b/ui/images/interactive-bulb-on.png new file mode 100644 index 0000000000..8f7b2562b6 Binary files /dev/null and b/ui/images/interactive-bulb-on.png differ diff --git a/ui/images/interactive-element-action.png b/ui/images/interactive-element-action.png new file mode 100644 index 0000000000..b30df2f3b2 Binary files /dev/null and b/ui/images/interactive-element-action.png differ diff --git a/ui/images/interactive-element-add-openhab.png b/ui/images/interactive-element-add-openhab.png new file mode 100644 index 0000000000..b749e8019a Binary files /dev/null and b/ui/images/interactive-element-add-openhab.png differ diff --git a/ui/images/interactive-element-minimum-opacity.png b/ui/images/interactive-element-minimum-opacity.png new file mode 100644 index 0000000000..12ea6c5371 Binary files /dev/null and b/ui/images/interactive-element-minimum-opacity.png differ diff --git a/ui/images/interactive-element-rollershutter-window-config.png b/ui/images/interactive-element-rollershutter-window-config.png new file mode 100644 index 0000000000..e4da5acce7 Binary files /dev/null and b/ui/images/interactive-element-rollershutter-window-config.png differ diff --git a/ui/images/interactive-element-rollershutter-window.png b/ui/images/interactive-element-rollershutter-window.png new file mode 100644 index 0000000000..e4f676af03 Binary files /dev/null and b/ui/images/interactive-element-rollershutter-window.png differ diff --git a/ui/images/interactive-element-text.png b/ui/images/interactive-element-text.png new file mode 100644 index 0000000000..fe3cb70e6b Binary files /dev/null and b/ui/images/interactive-element-text.png differ diff --git a/ui/images/interactive-elements-svg.png b/ui/images/interactive-elements-svg.png new file mode 100644 index 0000000000..6b48760f7f Binary files /dev/null and b/ui/images/interactive-elements-svg.png differ diff --git a/ui/images/interactive-room.png b/ui/images/interactive-room.png new file mode 100644 index 0000000000..359a3b6413 Binary files /dev/null and b/ui/images/interactive-room.png differ diff --git a/ui/images/interactive-style.png b/ui/images/interactive-style.png new file mode 100644 index 0000000000..31be830c9e Binary files /dev/null and b/ui/images/interactive-style.png differ diff --git a/ui/index.md b/ui/index.md index 9331e66a0f..043e9bbdba 100644 --- a/ui/index.md +++ b/ui/index.md @@ -14,12 +14,21 @@ To do that, openHAB puts different options at your disposal; they are commonly r Several types of pages are available: +- [Home Page](index.html#the-home-page) +- [Sitemaps](index.html#sitemaps) +- [Layout Pages](index.html#layout-pages) + - [Responsive Layouts](./layout-pages-responsive.md) + - [Fixed Grid Layouts](./layout-pages-fixed.md) +- [Maps & Floorplans](index.html#maps-floorplans) +- [Charts](index.html#charts) + - [Tabbed Pages](index.html#tabbed-pages) + ### The Home Page The main's UI **home page** consists of 4 tabs: - an overview which you can customize entirely from scratch; -- 3 tabs representing a generated view of your model oriented by **Location**, **Equipment** and **Properties**. +- 3 tabs representing an _automatically generated view_ of your model oriented by **Location**, **Equipment** and **Properties**. In these 3 model-oriented tabs, expandable cards will appear **automatically** as you build your model, allowing you to get different perspectives on your home. For instance, you may want to see everything in a particular location, or everything pertaining to a certain class of equipment, like heating, or see a consolidated view of all items related to a certain property like temperature or humidity. diff --git a/ui/layout-pages-fixed.md b/ui/layout-pages-fixed.md new file mode 100644 index 0000000000..7124d2e7ab --- /dev/null +++ b/ui/layout-pages-fixed.md @@ -0,0 +1,377 @@ +--- +title: Fixed Layout Pages +--- + +## Fixed Layouts + +![fixed-layout-sample.png](images/fixed-layout-sample.png) + +Fixed layouts allow you to position and size widgets freely, either on a grid with **Fixed Grid** layout, or in a completely free way with **Fixed Canvas** layouts (with **Fixed Canvas**, you are still able to temporarily switch on a grid if you want to snap some widgets). + +The main idea is to create a layout on which you can freely place [widgets](/ui/building-pages.html#building-pages-components-widgets) which provide the interaction with your home automation system. + +You can even make the **background image interactive** and use it as multi-widget to control and trigger actions like you can do with widgets. + +## Getting Started + +The first thing to do when creating a Fixed Layout is to define your screen size. In most cases this should be the **CSS Resolution** of the device you're creating this layout for. + +::: tip Note + +For most modern tablets, mobile phones and some other screens the **CSS resolution** is different from the **physical pixel resolution** (sometimes referred to as _Retina_ displays). +The user interface tries to help you to determine the CSS resolution by showing the currently detected value as _Current Screen_ rate at the top of the virtual screen area. + +::: + +### Fixed Grid Layouts + +To define your screen size open the ![configure-grid.png](images/configure-grid.png) menu and click **Configure Grid Layout**. + +The layout editor shows a gray surface as the _virtual screen area_, which represents your defined screen. +You can now place widgets on that screen by clicking the **Add Widget** button. +Just like with responsive layouts a placeholder will appear, allowing you to choose widgets from the library. + +Additionally, you can move the widget within the virtual screen area by dragging its upper left corner at the arrow icon shown. +You can also resize the widget by grabbing the handle in the bottom right corner. + +Positioning and resizing will snap to the underlying invisible grid. +The size of that grid can be adjusted by configuring the number of columns in the layout configuration. +The number of rows gets automatically aligned to create the most square-like grid. + +The gear icon in the top right corner of each widget allows you to configure or remove a widget. + +#### Configuration + +The following parameters can be adjusted for a Fixed Grid Layout: + +##### Layout Settings + +_Number of Columns:_ +Number of grid columns across the page. Defaults to 16. +Limited to a minimum widget width of 50px (calculated from screen width, margin and number of columns) + +_Margin:_ +Margin between items and to screen edge in CSS pixels. Defaults to 10. + +##### Screen Settings + +_Screen Width:_ +Screen width in CSS pixels. Defaults to 1280. + +_Screen Height:_ +Screen height in CSS pixels. Defaults to 720. + +_Scaling:_ +Enabling this scales the defined screen to the width available in the browser window. +All widgets are resized accordingly, with the margin staying fixed. +While this works well in many cases, it can lead to unpredictable styling issues, especially on large divergence from the defined screen width. +Defaults to false. + +##### Appearance + +_Hide Navigation Bar:_ +When enabled the navigation bar on top of a page does not get displayed on this page. +In conjunction with hiding the sidebar via its pin icon, this can be used for full screen display, e.g. in a fullscreen browser or when used as Home Screen App on iOS. +Defaults to false. + +_Hide Sidebar Icon:_ +With the navigation bar hidden, an icon is displayed on the top left corner when the sidebar is closed. +Enabling this hides the icon. Defaults to false. + +_Show Fullscreen Icon:_ +Show a fullscreen icon on the top right corner to enter browser fullscreen mode. +Defaults to false. + +### Fixed Canvas Layouts + +To define your screen size open the canvas menu ![configure-canvas.png](images/configure-canvas.png) and click **Configure Canvas Layout**. + +The layout editor shows a gray surface as the _virtual screen area_, which represents your defined screen. +You can now place widgets on that screen by clicking the **Add Widget** button. +Just like with responsive layouts a placeholder will appear, allowing you to choose widgets from the library. + +Additionally, you can move the widget within the virtual screen area by dragging its upper left corner at the arrow icon shown. +You can also resize the widget by grabbing the handles. +Depending on the widget, you may also toggle the **Autosize** option in the widget options available from the gear icon on the top right corner of each widget to have the widget take its natural size. + +If you toggle the grid using the grid button, positioning and resizing will snap to the grid but untouched widgets will remain at their current size and position. +The pitch of that grid can be adjusted in the layout configuration. + +The gear icon in the top right corner of each widget allows you to configure or remove a widget. + +#### Configuration + +The following parameters can be adjusted for a Fixed Canvas Layout: + +##### Layout Settings + +_Grid size:_ +Pitch of the grid when the editor grid button is enabled, in CSS pixels, to snap the content. + +##### Screen Settings + +_Screen Width:_ +Screen width in CSS pixels. Defaults to 1280. + +_Screen Height:_ +Screen height in CSS pixels. Defaults to 720. + +_Scaling:_ +Enabling this scales the defined screen to the width available in the browser window. All widgets are resized accordingly. +While this works well in many cases, it can lead to unpredictable styling issues, especially on large divergence from the defined screen width. +Defaults to false. + +_Image URL:_ +URL of the image to display in the background. The image is stretched to fit the screen size, while preserving its aspect ratio. +If you want to achieve a different placement, adding margins to the image in an image editor will be necessary. + +This setting is in particular in important if you want to make your background image interactive, in which case it has to be of type SVG. +See below for more information on [interactive backgrounds](layout-pages-fixed.html#interactive-backgrounds). + +_Image Source Set:_ +The setting is passed to the [`srcset`](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images) attribute of the image element, allowing to specify different images to be used depending on the actual resolution of the device, for example is the layout will be used both on a so called 'retina' and non-'retina' tablet. + +##### Widget Settings + +Specific widget settings are available through the gear popup menu displayed on each widget in the layout. +It provides access to the settings related to the type of the widget (**Widget Settings**) and to settings specific to the usage of this widget within a canvas. + +##### Container Settings + +_Preserve classic style:_ +Enabling this option preserves the widget style definition as in other layout pages (responsive, fixed grid). +Usually, this means preserving the background of the widget. + +_Shadow:_ +Applies a shadow to the widget inner outline. + +_Bring to Front_, _Mode Up_, _Move Down_, _Send to Back_: +Change the drawing order of several overlapping widgets. + +## Interactive SVG Backgrounds + +When using a Fixed Canvas Layout, you can make background images interactive. + +This allows designs similar like floor plans but with a much more intuitive way to interact with your house, room or even furniture. + +Note that it does not intent to replace widgets - widgets can still be additionally placed on top of the background image. +Both **interactive backgrounds and widgets together allow endless possibilities** to create a unique user interface. + +The below image depicts a few examples that can be achieved with interactive backgrounds which are completely done without using widgets. + +![interactive-room.png](images/interactive-room.png) + +- The sofa can be directly clicked to control something that is related to the sofa. +- The green bar around the desk is not only a clickable LED-Strip but also reflects the color that is currently selected. +- The light bulb in the middle is filled by the color that is configured for the State ON of the light. +- The light at the right is using a "glow" effect to indicate that it is currently switched on. +This glow effect is modelled in the SVG and is just enabled disabled by the item state. +- The door is depicted with red gradient designed in the SVG and the gradient is shown when the door is open (the same would happen for the windows on the top). +- The astronaut with the megaphone has an animation that fades in and out when the state is ON. +- The horizontal button below the green light is an animated button completely modelled in the SVG and controlled by openHAB. + +### Embedding SVG Images + +This feature requires the image to be of type SVG. +Note that this approach requires a bit more of a technical background as you need to [prepare the SVG](#preparing-the-svg-image). + +Additionally, the following settings are important: + +- **Embed SVG**: Only when enabled, the SVG image is embedded in the page as "real" HTML elements, allowing to interact with it (normally an SVG would only be referenced by an IMG tag). +By default, this is switched off and therefore needs to be enabled. + +- **Embed SVG Flashing in Run-Mode**: It is possible within the editor to flash the elements of the SVG image that have been previously marked as interactive through the attribute 'openhab' (see below). +This setting will also flash the elements in run-mode guiding the user getting by knowing which part of the image is clickable or not. +By default, this is switched off. + +### Preparing the SVG Image + +SVG images are basically XML files, and can be edited with any text editor. +It is recommended to use a dedicated SVG editor like [Inkscape](https://inkscape.org/) to manipulate the SVG image because it does not only provide a user interface to draw the image but also to see and view the XML "behind" the SVG itself. + +**Example:** + +Let's create a very simple SVG with Inkscape which we will embed in a Fixed Canvas Layout. + +- Create a new SVG and draw three rectangles like the following and save the file as `background.svg` + - Copy the file into the `conf/html` folder of your openHAB installation. + +![interactive-elements-svg.png](images/interactive-elements-svg.png) + +- Add "/static/background.svg" in the Image URL field of the Fixed Canvas Layout configuration, and you will see the SVG image in the background of the layout editor. +- Save the page. +- Open the XML-Editor in Inkscape (Edit -> XML Editor) and you can see something like the following (note that you will see the same if you open the SVG directly with a text editor): + +```xml + + + + + + + + +``` + +You can see several elements that represent the rectangles we have drawn. +To make the SVG interactive, you need to add a special attribute to the elements you want to be clickable and therefore interactive. +This attribute is called `openhab` and can be set to any value, but it is recommended to use a meaningful value like "true". + +Let's add this attribute to the first rectangle either via Inkscape or directly within the file, then save the image and reload the page: + +![interactive-element-add-openhab.png](images/interactive-element-add-openhab.png) + +```xml + +``` + +Note that you have added the `openhab="true"` attribute to the first ``angle and not to a group `` (which we talk about below) + +- Make sure that the `Embed SVG` option is enabled in the Fixed Canvas Layout configuration. +- Stay in Edit-Mode of the page +- On the right between the "Grid" icon and the "Configure Layout" icon, you can see a new icon with a flash which allows you to flash the interactive elements. +When you click on it, the first rectangle should flash which indicates that has become an interactive element for openHAB. +- There are two different colors when the element flashes: + - Red: The element is defined as an interactive element but is not yet configured. + - Green: The element is defined as an interactive element and is already configured. +- Click on it and a dialog, which is similar to configurations of a normal widget except that it has some additional settings, will appear. +- Later, after configuration, you can go to Run-Mode and try out your configuration. + +### Configuration of an interactive element + +The dialog has many options that allow you to configure the interactive element. +Usually you will first configure the Action and the Action Item like in a normal widget. + +![interactive-element-action.png](images/interactive-element-action.png) + +Many special options though will only be available when you click on "Show Advanced". + +- **State Items**: Define the item that is used to retrieve the state of the element to reflect the state. +Reflecting the state can be either applying a color or using the opacity of that svg element. +The reason why you can choose several states is that in some cases you might want use expressions. +In this case you need to select all items that you use in this expression (see below for an example). + +- **Use State Proxy Element**: Often you have more complex elements that are made of a group (a `` element in the SVG) that do not either allow to be directly filled with a color or where you explictly want to use a specific element in that group to reflect the state. +A good example is the following bulb. +The left image shows the bulb in the OFF state and the right image shows the bulb in the ON state. +In this case we do apply a color based on the state but enable / disable a proxy element in that group that makes up the bulb object. + + ![interactive-bulb-off.png](images/interactive-bulb-off.png) ![interactive-bulb-on.png](images/interactive-bulb-on.png) + +The way this can be achieved by indication a proxy element, an element that is part of that group. +Similarly like the main element is marked with an `openhab` attribute, the proxy element is marked with a special attribte, the `flash` attribute. +In this case the proxy element is made _visible_ or _invisible_ depending on the state of the item. +It is also used when flashing the interactive elements with the flash icon, hence the name "flash" attribute. + +```xml + <-- simplified elements from the bulb group --> + + + ... + more elements in the group + +``` + +Tip: Search for nice SVG objects and import into your SVG background file + +- **State ON Color / OFF Color**: Define the color that should be applied when the state is ON or OFF. +An expression can be used here as well which is especially useful when, e.g. you want to apply the color of a light to that element. +Here is an example of an expression that uses the color state of a light item to apply the color to the element: + +```yaml +=(items.AZ_Govee_Light_Strip_Power.state==='ON') ? items.AZ_Govee_Schreibtisch_Light_Strip_Color.state: '#aaaaaa' +``` + +Keep in mind that in this case, the _AZ_Govee_Light_Strip_Power_ and the _AZ_Govee_Schreibtisch_Light_Strip_Color_ both need to be selected in State Items. + +- **Use State as Opacity**: If this option is enabled, the state of the item will be used to set the opacity of the element. +This is in particular helpful if the element should become more transparent depending on State Percentage or ON/FF of an item. +- **Invert State Opacity**: If this option is enabled, the opacity will be inverted. + +An example could be the closing state of a rollershutter that makes a window element more and more (in)transparent. +The blue bar that depicts the window will become less and less transperent the more the rollershutter is closed and will finally look like the wall when the rollershutter is completely closed. + + ![interactive-element-rollershutter-window.png](images/interactive-element-rollershutter-window.png) + +The following configuration uses the inversion of the percentage state value as 100 should become 0 and vice versa. + + ![interactive-element-rollershutter-window-config.png](images/interactive-element-rollershutter-window-config.png) + +- **Minimum Opacity applied**: If you want the minimum not to be 0, you can set it which makes sure the element will not be completely hidden but still be partially visible. +An example could be to show the presence/absence of people like shown below where the minimum has been set to 0.2. +In this case the opacity is derived from the ON/OFF state of the openHAB presence item state where 1 equals 100% and 0 equals 20% instead of 0%. + + ![interactive-element-minimum-opacity.png](images/interactive-element-minimum-opacity.png) + +#### Show State information as Text + +If you want to display the state value as text, create a text element within the SVG (which is a ``), mark it as openhab=true and select the State Item. +The value of that State Item will then be written to the text element: + +![interactive-element-text.png](images/interactive-element-text.png) + +- **Use displayState as Text**: Sometimes you want to apply the formatted display state instead of the raw state. + This is especially useful when you want to display the state of a temperature item in a more human-readable way. + +#### Using styles and SVG animations + +This is the most sophisticated part of the interactive SVG backgrounds which allows very interesting designs. + +- **"Set Style Class based on ON" / OFF State**: These properties allow you to apply CSS classes to an element when the state is ON or OFF. + +In general, any style class that is defined in the CSS of the page can be applied to the SVG element. +CSS classes can be used to apply colors, animations, or any other style that is possible with CSS. +They can be added to SVG text file in the same way it is added to HTML files. + +**Animations**: + +Here is a simple example that works with the above astronaut to create a fading in/out animation: + +![interactive-style.png](images/interactive-style.png) + +The above setting for _Set Style Class based on ON_ will apply the class `animate` to the element with the id 'astro_animate'. + +This can be achieved by adding the following style to the CSS of the page to implement an "animation" of the opacity. + +```css += 480px | Smartphones in landscape mode | +| `small` | >= 568px | Smaller tablets (Nexus 7...) in portrait mode | +| `medium` | >= 768px | Most tablets in portrait mode | +| `large` | >= 1024px | Smaller/regular tablets (iPad, iPad Mini...) in landscape mode* | +| `xlarge` | >= 1200px | High-end tablets (iPad Pro...), desktops | + +* Note that the sidebar will potentially be displayed and has a width of 260px + +If you don't specify any width or breakpoints, the column will spread evenly on the row, without wrapping. +This is fine for a couple of columns and simple widgets only, since on a small smartphone screen, you will rapidly get out of room. +That's why you may find yourself wanting to let a column be 100% by default, so that it occupies the entire screen, and then reduce the width for `medium` or `large` breakpoints. + +For example, given this set of rows & cols: + +```yaml +config: + label: Overview +blocks: + - component: oh-block + config: {} + slots: + default: + - component: oh-grid-row + config: {} + slots: + default: + - component: oh-grid-col + config: + width: "100" + small: "50" + medium: "33" + slots: + default: [] + - component: oh-grid-col + config: + width: "100" + small: "50" + medium: "33" + slots: + default: [] + - component: oh-grid-col + config: + width: "100" + medium: "33" + slots: + default: [] +``` + +This is how the layout will adapt depending on the width of the screen: + +![Responsive Layout](./images/responsive2.gif) + +### How to Build a Responsive Layout Page + +#### Defining the Layout + +When you create a new Responsive Layout Page, you'll notice the 2 buttons **Add Block** and **Add Masonry**. +Clicking either will add the respective container to the page. +If you have multiple blocks, you can use the black context button (or the Code view) to reorder them with the Move Up/Move Down menu options. +You can also copy it and paste it as another block after they've been designed, if you wish to have multiple similar blocks. +You can also give a title to the block which will be displayed above it. + +Blocks are also good candidates to use the conditional visibility features on, with the `visible` and `visibleTo` properties. +You can restrict what's displayed on the page based on an expression, or who is currently viewing the page. +In Design mode, _you will not be able to see the effect of these properties_, notably `visible`, but in Run mode they will be taken into account. + +Under blocks, as explained above, you can have a mix of cells or rows. +The 2 buttons **Add Row** and **Add Cells** will let you add more of them. +They will be added at the end of the block, but as for the blocks themselves, you can reorder them, or duplicate them, using the context menus or the YAML. + +In Design mode, rows will feature an additional step before you can actually add widgets: adding columns: the **Add Column** serves this purpose. + +#### Adding Widgets + +Big gray placeholders with a "+" sign will appear where you can add Widgets. + +Depending on the type of containers, different widgets from the Standard library will be offered in the menu, as well as widgets from your personal library. + +You will also get an additional option: **Add from Model...**. +This option will display your semantic model, and let you pick one or several items, then add them in the container. +The Widget that will be added will be the _default widget_ for the item for that type of container which can be controlled with metadata: + +- for columns or masonry, the _default standalone widget_; +- for items inside list cards, the _default list item widget_; +- for cell containers, the _default cell widget_. + +![Add from Model](./images/add_from_model.png) + +::: tip REMARK + +The widget that will be put on the page is a _copy_ of the current widget as defined in metadata at the time of the addition; if you change this definition for an item, widgets that were already put on a page with the **Add from Model...** feature will **NOT** be updated. + +::: diff --git a/ui/layout-pages.md b/ui/layout-pages.md index a99ee33750..b5285ea5ad 100644 --- a/ui/layout-pages.md +++ b/ui/layout-pages.md @@ -5,285 +5,33 @@ title: Layout Pages # Layout Pages Layout Pages are used in the main web user interface to display widgets in an organized manner. -You can choose between two different basic types of layouts: -- Responsive Layouts +[[toc]] -Responsive Layouts are the main layouts in openHAB and recommended for most uses. They automatically adjust to the device's screen and thus can be used as general interface from all devices. +## Responsive Layouts + +Responsive Layouts work well on mobile devices that need to adapt to different screen sizes. +Fixed Grid Layouts are more suitable for wall-mounted tablets or other devices with a fixed screen size. +In particular, Fixed Grid Layouts are suited as an alternative for [floor plan pages](floorplan-pages.md) and even support an interactive background image that can act similar like widgets. + +**Responsive Layouts** are the main layouts in openHAB and recommended for most uses. They automatically adjust to the device's screen and thus can be used as general interface from all devices. Within Responsive Layouts you can choose among several types of arrangements, based on whether you want to control the layout completely, or let the container decide where to place the widgets. ![Responsive Layout Page Example](./images/responsive_layout_example.png) -- Fixed Grid Layouts +## Fixed Grid Layouts -Fixed Grid Layouts allow you to create a Layout Page where elements have predefined positions and sizes. They are used to design a panel-like page for a specific screen size and are most suitable for static interfaces like wall mounted tablets. +Fixed Grid Layouts allow you to create a Layout Page where elements have _predefined positions and sizes_. They are used to design a panel-like page for a specific screen size and are most suitable for static interfaces like wall mounted tablets. +## Creating a Layout Page + When you first create a layout you are asked which type of layout you want to create. Note that the type cannot be changed afterwards. ![Choose Layout](./images/choose_layout.png) -## Responsive Layout Pages - -### Anatomy of a Responsive Layout Page - -A Responsive Layout page can host one or multiple **blocks**, optionally followed by a **masonry** layout. - -In every block there could be an arbitrary set of **rows** or **cells** containers. - -In a cell container, you may add widgets from the standard cell widget library (or personal widgets, provided they're based on a `oh-cell` widget or derivative). - -In a row, you may add **columns** which will spread across the row, possibly wrapping their contents to another row (but still within the same `oh-grid-row`). -Each column can host one widget from the standard standalone widget library, or a personal one. - -The masonry container will decide how many columns it has based on the screen width, and will try to arrange the widgets automatically to form a compact layout. - -### Designing Responsive Layout Pages - -When you're designing a responsive layout page, it's important to remember how this page will be used. -Sometimes, it will be on a phone, and other times on a bigger screen. - -With that in mind, it is advisable to build the page for the narrow screens first, and then make sure it expands gracefully to the wider ones, instead of thinking the other way around. If you plan to share the UI you built, you can expect them to access it with mobile devices rather than desktop computers. - -For cells and masonry, you don't have to worry about it, it will be handled for you. However, when you choose to keep control of the layout by making use of rows and columns, you need to take extra care about the responsive breakpoints. - -These are controlled using the parameters on the column (`oh-grid-col`) components - you can configure them in the Design tab with the _Column Options_ menu entries, or in YAML with the Code tab or a "Edit YAML" options on a parent component. - -![Column Options](./images/responsive1.png) - -Using code, you can quickly duplicate the breakpoints for similar columns. - -The breakpoints work like this: the `width` property of the column is the default width that will be applied for the smallest screen, then `xsmall`, `small`, `medium`, `large`, `xlarge` width will apply on wider screens appropriately: - -| Property | Minimum screen width | Examples of devices | -|----------|----------------------|---------------------| -| `width` | No minimum, default | All devices including phones | -| `xsmall` | >= 480px | Smartphones in landscape mode | -| `small` | >= 568px | Smaller tablets (Nexus 7...) in portrait mode | -| `medium` | >= 768px | Most tablets in portrait mode | -| `large` | >= 1024px | Smaller/regular tablets (iPad, iPad Mini...) in landscape mode* | -| `xlarge` | >= 1200px | High-end tablets (iPad Pro...), desktops | - -* Note that the sidebar will potentially be displayed and has a width of 260px - -If you don't specify any width or breakpoints, the column will spread evenly on the row, without wrapping. -This is fine for a couple of columns and simple widgets only, since on a small smartphone screen, you will rapidly get out of room. -That's why you may find yourself wanting to let a column be 100% by default, so that it occupies the entire screen, and then reduce the width for `medium` or `large` breakpoints. - -For example, given this set of rows & cols: - -```yaml -config: - label: Overview -blocks: - - component: oh-block - config: {} - slots: - default: - - component: oh-grid-row - config: {} - slots: - default: - - component: oh-grid-col - config: - width: "100" - small: "50" - medium: "33" - slots: - default: [] - - component: oh-grid-col - config: - width: "100" - small: "50" - medium: "33" - slots: - default: [] - - component: oh-grid-col - config: - width: "100" - medium: "33" - slots: - default: [] -``` - -This is how the layout will adapt depending on the width of the screen: - -![Responsive Layout](./images/responsive2.gif) - -### How to Build a Responsive Layout Page - -#### Defining the Layout - -When you create a new Responsive Layout Page, you'll notice the 2 buttons **Add Block** and **Add Masonry**. -Clicking either will add the respective container to the page. -If you have multiple blocks, you can use the black context button (or the Code view) to reorder them with the Move Up/Move Down menu options. -You can also copy it and paste it as another block after they've been designed, if you wish to have multiple similar blocks. -You can also give a title to the block which will be displayed above it. - -Blocks are also good candidates to use the conditional visibility features on, with the `visible` and `visibleTo` properties. -You can restrict what's displayed on the page based on an expression, or who is currently viewing the page. -In Design mode, _you will not be able to see the effect of these properties_, notably `visible`, but in Run mode they will be taken into account. - -Under blocks, as explained above, you can have a mix of cells or rows. -The 2 buttons **Add Row** and **Add Cells** will let you add more of them. -They will be added at the end of the block, but as for the blocks themselves, you can reorder them, or duplicate them, using the context menus or the YAML. - -In Design mode, rows will feature an additional step before you can actually add widgets: adding columns: the **Add Column** serves this purpose. - -#### Adding Widgets - -Big gray placeholders with a "+" sign will appear where you can add Widgets. - -Depending on the type of containers, different widgets from the Standard library will be offered in the menu, as well as widgets from your personal library. - -You will also get an additional option: **Add from Model...**. -This option will display your semantic model, and let you pick one or several items, then add them in the container. -The Widget that will be added will be the _default widget_ for the item for that type of container which can be controlled with metadata: - -- for columns or masonry, the _default standalone widget_; -- for items inside list cards, the _default list item widget_; -- for cell containers, the _default cell widget_. - -![Add from Model](./images/add_from_model.png) - -::: tip REMARK - -The widget that will be put on the page is a _copy_ of the current widget as defined in metadata at the time of the addition; if you change this definition for an item, widgets that were already put on a page with the **Add from Model...** feature will **NOT** be updated. - -::: - -## Fixed Layouts - -Fixed layouts allow you to position and size widgets freely, either on a grid with **Fixed Grid** layout, or in a completely free way with **Fixed Canvas** layouts (with **Fixed Canvas**, you are still able to temporarily switch on a grid if you want to snap some widgets). - -The first thing to do when creating a Fixed Layout is to define your screen size. In most cases this should be the **CSS Resolution** of the device you're creating this layout for. - -::: tip Note - -For most modern tablets, mobile phones and some other screens the **CSS resolution** is different from the **physical pixel resolution** (sometimes referred to as _Retina_ displays). -The user interface tries to help you determining the CSS resolution by showing the currently detected value as _Current Screen_ rate at the top of the virtual screen area. - -::: - -### Fixed Grid Layouts - -To define your screen size open the '#' menu and click **Configure Grid Layout**. - -The layout editor shows a gray surface as the _virtual screen area_, which represents your defined screen. -You can now place widgets on that screen by clicking the **Add Widget** button. -Just like with responsive layouts a placeholder will appear, allowing you to choose widgets from the library. - -Additionally, you can move the widget within the virtual screen area by dragging its upper left corner at the arrow icon shown. -You can also resize the widget by grabbing the handle at the bottom right corner. - -Positioning and resizing will snap to the underlying invisible grid. -The size of that grid can be adjusted by configuring the number of columns in the layout configuration. -The number of rows gets automatically aligned to create the most square-like grid. - -The gear icon on the top right corner of each widget allows you to configure or remove a widget. - -#### Configuration - -The following parameters can be adjusted for a Fixed Grid Layout: - -##### Layout Settings - -_Number of Columns:_ -Number of grid columns across the page. Defaults to 16. -Limited to a minimum widget width of 50px (calculated from screen width, margin and number of columns) - -_Margin:_ -Margin between items and to screen edge in CSS pixels. Defaults to 10. - -##### Screen Settings - -_Screen Width:_ -Screen width in CSS pixels. Defaults to 1280. - -_Screen Height:_ -Screen height in CSS pixels. Defaults to 720. - -_Scaling:_ -Enabling this scales the defined screen to the width available in the browser window. -All widgets are resized accordingly, with the margin staying fixed. -While this works well in many cases, it can lead to unpredictable styling issues, especially on large divergence from the defined screen width. -Defaults to false. - -##### Appearance - -_Hide Navigation Bar:_ -When enabled the navigation bar on top of a page does not get displayed on this page. -In conjunction with hiding the sidebar via its pin icon, this can be used for full screen display, e.g. in a fullscreen browser or when used as Home Screen App on iOS. -Defaults to false. - -_Hide Sidebar Icon:_ -With the navigation bar hidden, an icon is displayed on the top left corner when the sidebar is closed. -Enabling this hides the icon. Defaults to false. - -_Show Fullscreen Icon:_ -Show a fullscreen icon on the top right corner to enter browser fullscreen mode. -Defaults to false. - -### Fixed Canvas Layouts - -To define your screen size open the canvas menu and click **Configure Canvas Layout**. - -The layout editor shows a gray surface as the _virtual screen area_, which represents your defined screen. -You can now place widgets on that screen by clicking the **Add Widget** button. -Just like with responsive layouts a placeholder will appear, allowing you to choose widgets from the library. - -Additionally, you can move the widget within the virtual screen area by dragging its upper left corner at the arrow icon shown. -You can also resize the widget by grabbing the handles. -Depending on the widget, you may also toggle the **Autosize** option in the widget options available from the gear icon on the top right corner of each widget to have the widget take its natural size. - -If you toggle the grid using the grid button, positioning and resizing will snap to the grid but untouched widgets will remain at their current size and position. -The pitch of that grid can be adjusted in the layout configuration. - -The gear icon on the top right corner of each widget allows you to configure or remove a widget. - -#### Configuration - -The following parameters can be adjusted for a Fixed Canvas Layout: - -##### Layout Settings - -_Grid size:_ -Pitch of the grid when the editor grid button is enabled, in CSS pixels. - -##### Screen Settings - -_Screen Width:_ -Screen width in CSS pixels. Defaults to 1280. - -_Screen Height:_ -Screen height in CSS pixels. Defaults to 720. - -_Scaling:_ -Enabling this scales the defined screen to the width available in the browser window. All widgets are resized accordingly. -While this works well in many cases, it can lead to unpredictable styling issues, especially on large divergence from the defined screen width. -Defaults to false. - -_Image URL:_ -URL of the image to display in the background. The image is stretched to fit the screen size, while preserving its aspect ratio. -If you want to achieve a different placement, adding margins to the image in an image editor will be necessary. - -_Image Source Set:_ -The setting is passed to the [`srcset`](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images) attribute of the image element, allowing to specify different images to be used depending on the actual resolution of the device, for example is the layout will be used both on a so called 'retina' and non-'retina' tablet. - -##### Widget Settings - -Specific widget settings are available through the gear popup menu displayed on each widget in the layout. -It provides access to the settings related to the type of the widget (**Widget Settings**) and to settings specific to the usage of this widget within a canvas. - -##### Container Settings - -_Preserve classic style:_ -Enabling this option preserves the widget style definition as in other layout pages (responsive, fixed grid). -Usually, this means preserving the background of the widget. - -_Shadow:_ -Applies a shadow to the widget inner outline. +Then follow the configuration steps for the chosen layout type: -_Bring to Front_, _Mode Up_, _Move Down_, _Send to Back_: -Change the drawing order of several overlapping widgets. +- [Responsive Layouts](layout-pages-responsive.md) or +- [Fixed Grid Layouts](layout-pages-fixed.md)