Improvements to UI-related documentation (openhab#2229)

* Persistence config: Mention UI support & Link UI docs Signed-off-by: Florian Hotze <[email protected]> * Add links to docs from Main UI docs pages Signed-off-by: Florian Hotze <[email protected]> * Minor wording improvements Signed-off-by: Florian Hotze <[email protected]> * Building Pages: Add CSS section Signed-off-by: Florian Hotze <[email protected]> * Expand sidebar for Main UI devtools & Creating Widgets Signed-off-by: Florian Hotze <[email protected]> * Add some images Signed-off-by: Florian Hotze <[email protected]> * Fix sidebar Signed-off-by: Florian Hotze <[email protected]> * Remove ugly border from image Signed-off-by: Florian Hotze <[email protected]> * Address review Signed-off-by: Florian Hotze <[email protected]> --------- Signed-off-by: Florian Hotze <[email protected]>
stefan-hoehn · Feb 9, 2024 · d04a583 · d04a583
1 parent c423441
commit d04a583
Show file tree

Hide file tree

Showing 13 changed files with 64 additions and 23 deletions.
diff --git a/.vuepress/docs-sidebar.js b/.vuepress/docs-sidebar.js
@@ -136,7 +136,13 @@ module.exports = [
         ]
       },
       ['mainui/addons', 'Add-on Store'],
-      ['mainui/developer/', 'Developer Tools'],
+      { title: 'Developer Tools',
+        path: '/docs/mainui/developer/',
+        children: [
+          ['mainui/developer/sidebar', 'Developer Sidebar'],
+          ['mainui/developer/widgets', 'Widgets']
+        ]
+      },
       ['mainui/about', 'Help & About'],
     ]
   },
@@ -156,7 +162,13 @@ module.exports = [
           ['ui/building-pages', 'Building Pages'],
         ]
       },
-      ['ui/personal-widgets', 'Creating Personal Widgets'],
+      { title: 'Creating Personal Widgets',
+        path: '/docs/ui/personal-widgets',
+        children: [
+          ['ui/widget-expressions-variables', 'Widget Expressions & Variables'],
+          ['ui/css-pages-widgets', 'Styling Pages & Widgets']
+        ]
+      },
       ['ui/components/', 'Component Reference'],
       'ui/habpanel/habpanel',
       ['apps/android', 'Android App'],

diff --git a/configuration/persistence.md b/configuration/persistence.md
@@ -22,17 +22,19 @@ Please refer to the [available persistence service add-on](/addons/#persistence)
 You should configure a default persistence service even if you have only one persistence add-on installed.
 The default persistence service is used to provide data for the UI charting features and rules (you may choose to use another persistence service in either of these, configured on a case-by-case basis).
 
-To select a default persistence service, in UI, select `Settings->Persistence`.
-Select your default service from the drop-down list.
-Note that you must first install a persistence add-on before you make this selection.
-Be sure to save your choice once you have selected your default service.
+To select a default persistence service via UI, refer to the [Main UI docs]({{base}}/mainui/settings/persistence.html).
 
 ## Persistence Configuration
 
 The information below allows you to determine which Item states are persisted, when they are persisted, and where they are stored.
 
-Persistence Strategies are configured in a file named `<persistenceservice>.persist`, stored in `$OPENHAB_CONF/persistence`.
-Replace "persistenceservice" with the name of your persistence add-on (e.g. `rrd4j.persist`).
+Persistence Strategies are configured:
+
+- in a file named `<persistenceservice>.persist` (fill-in your persistence add-on name, e.g. `rrd4j.persist`), stored in `$OPENHAB_CONF/persistence`.
+- from the UI, refer to the [Main UI docs]({{base}}/mainui/settings/persistence.html).
+
+As usual, it is possible to combine both types of configuration, i.e. use the UI for one and a file for another persistence service.
+It is not possible to configure the same persistence service via UI and file.
 
 ### Persistence Triggers
 

diff --git a/mainui/developer/widgets.md b/mainui/developer/widgets.md
@@ -10,6 +10,10 @@ title: Developer Tools - Widgets
 
 Community made Widgets can also be added to your system from the **UI** tab of the add-on store.
 
+Please read [Creating Personal Widgets]({{base}}/ui/personal-widgets.html) to learn about the structure, components and styling of personal widgets.
+
+![developer-widgets](../images/developer-widgets.png)
+
 On this page you can manage all the custom widgets you have added to your system:
 
 - **Add new Widgets**<br>

diff --git a/mainui/images/developer-widgets.png b/mainui/images/developer-widgets.png
diff --git a/mainui/images/model-overview.png b/mainui/images/model-overview.png
diff --git a/mainui/images/persistence-settings.png b/mainui/images/persistence-settings.png
diff --git a/mainui/settings/model.md b/mainui/settings/model.md
@@ -17,6 +17,8 @@ For most systems it only makes sense to include these Items that users will inte
 
 On this page you can manage your system's semantic model:
 
+![model-overview](../images/model-overview.png)
+
 - **Add new Locations**<br>
   Add group Items with semantic group tags to represent physical locations in and around your home.
 - **Add new Equipment**<br>

diff --git a/mainui/settings/persistence.md b/mainui/settings/persistence.md
@@ -12,10 +12,14 @@ The data may be retrieved at a later time, for example to restore your system af
 openHAB ships with the [RRD4J persistence service](/addons/persistence/rrd4j/) installed by default, which persists every Item on every state change and at least once a minute.
 Additionally, it restores the last stored value at system startup.
 
+Learn more about persistence in the [persistence docs]({{base}}/configuration/persistence.html).
+
 To change this behaviour, this is the page you are looking for!
 
 Here you can:
 
+![persistence-settings](../images/persistence-settings.png)
+
 - Set the **default persistence service**.
 - **Configure Persistence Policies**<br>
   For each installed persistence service, a list entry is added.

diff --git a/mainui/settings/rules.md b/mainui/settings/rules.md
@@ -11,6 +11,8 @@ Rules can be as simple as a directive to turn on a single light at a given time
 
 Community made Rule Templates can also be added to your system from the **Automation** tab of the add-on store.
 
+There is a [rules concepts page]({{base}}/concepts/rules.html) that explains the idea of rules in detail, and a comprehensive introduction to rules in the [rules tutorial]({{base}}/tutorial/rules_basic.html).
+
 On this page you can manage all the basic rules you have added to your system:
 
 ![rules-overview](../images/rules-overview.png)

diff --git a/mainui/settings/transformations.md b/mainui/settings/transformations.md
@@ -11,6 +11,8 @@ Transformations can be used in many different instances including links between
 
 The different available transformation methods must be individually installed via the **Other** tab of the add-on store.
 
+To learn more about transformations, read the [transformation docs]({{base}}/configuration/transformations.html).
+
 On this page you can manage all the transformations you have added to your system:
 
 - **Add new Transformations**<br>

diff --git a/ui/building-pages.md b/ui/building-pages.md
@@ -94,19 +94,19 @@ No matter which type of page you’re editing, the designer will feature black b
 
 These menus will in most cases allow you to:
 
-- configure the documented parameters with a config sheet (“Configure Widget” or similar)
-- open the part of the page’s YAML representation pertaining to the widget (“Edit YAML”), that is, a subgraph of the page’s component tree with that widget as its root component
-- perform cut/copy/paste operations, if supported (you can only do that in the same page currently, to copy or move widgets between pages, you may use the YAML view)
-- reorder the widget within its parent slot (these options are usually named “Move Up” and “Move Down” although you may occasionally encounter other labels, like “Move Left”/“Move Right”)
-- remove the widget
+- Configure the documented parameters with a config sheet (“Configure Widget” or similar)
+- Open the part of the page’s YAML representation pertaining to the widget (“Edit YAML”), that is, a subgraph of the page’s component tree with that widget as its root component
+- Perform cut/copy/paste operations, if supported (you can only do that in the same page currently, to copy or move widgets between pages, you may use the YAML view)
+- Reorder the widget within its parent slot (these options are usually named “Move Up” and “Move Down” although you may occasionally encounter other labels, like “Move Left”/“Move Right”)
+- Remove the widget
 
 Configuring the widget with the config sheet is of course more user-friendly than editing the YAML, as the options are usually organized logically in groups and feature a description:
 
 ![Configuring a Widget](./images/widget_config_sheet.png)
 
 However, it's important to know that there are limitations and sometimes editing the YAML directly will be best, because:
 
-1. not all options are described, since widgets are often wrappers for a similar concept in the library it's based on, either Framework7, ECharts, Leaflet, or other specialized libraries.
+1. Not all options are described, since widgets are often wrappers for a similar concept in the library it is based on, either Framework7, ECharts, Leaflet, or other specialized libraries.
   This means that in these cases, these underlying concepts will usually be passed the key/values of the (openHAB) widget component's config so that more parameters can be accepted than those which are documented in the widget's definition.
   Sometimes it will be indicated somewhere when configuring the widget, or in the openHAB documentation itself, on the other hand some options won't be available for use (for instance, because they expect a callback function and you cannot define those in the widget's config) or need some transformation.
 
@@ -119,24 +119,24 @@ However, it's important to know that there are limitations and sometimes editing
 
 Besides, there are several options that virtually all widgets in layout pages, map pages and plan pages accept, all of which are not currently available in the config sheet:
 
-- `visible`: you can specify a `false` boolean to this option to hide the widget. This powerful feature, combined with [widget expressions](widget-expressions-variables.html), allows you to dynamically show widgets or even entire sections (if you use it on layout widgets containing other widgets), depending on the state of your items
+- `visible`: You can specify a `false` boolean to this option to hide the widget. This powerful feature, combined with [widget expressions](widget-expressions-variables.html), allows you to dynamically show widgets or even entire sections (if you use it on layout widgets containing other widgets), depending on the state of your items
 Example: `visible: =items.TV_Powered.state === 'ON' && items.TV_Input.state === 'HDMI1'`
-- `visibleTo`: this accepts an array of strings like `role:administrator`, `role:user`, or `user:<userid>`, allowing the widget to be only visible to specific users or those with a certain role.
+- `visibleTo`: This accepts an array of strings like `role:administrator`, `role:user`, or `user:<userid>`, allowing the widget to be only visible to specific users or those with a certain role.
 Example: `visibleTo: ["user:scott", "role:administrator"]`
 - `class` and `style` are  [standard Vue.js attributes](https://vuejs.org/v2/guide/class-and-style.html) and can be used to either alter the CSS classes or add inline styling to the component. Please refer to [Styling pages & widgets using CSS](css-pages-widgets.md).
 
 ### Types of Widgets
 
 To help you define usable pages, there are a number of built-in widgets that you can use - most of which will be in layout pages. Those built-in widgets revolve around several libraries:
 
-- the **System** library includes "crude" controls that you cannot add with the designers - for instance `oh-button`, `oh-slider`, `oh-colorpicker`.
+- The **System** library includes "crude" controls that you cannot add with the designers - for instance `oh-button`, `oh-slider`, `oh-colorpicker`.
 Instead, you're more likely to use them within some container (card, list item...) provided by a widget of the Standard library; but when designing a personal widget with a complex layout you may want to use one or several of them directly.
 You may also use them in a slot of another widget, for those which define some, in order to add additional controls to that widget.
-- the **Standard** library, which has several classes of widgets:
+- The **Standard** library, which has several classes of widgets:
   - **layout widgets**, examples: `oh-block`, `oh-masonry`, `oh-grid-row`, `oh-grid-col` that you usually add with the designer to a layout page
   - **standalone widgets**, examples: `oh-label-card`, `oh-slider-card`, `oh-player-card` - usually not much more than widgets from the System library wrapped in a card
   - **list item widgets**, examples: `oh-list-item`, `oh-stepper-item`, `oh-toggle-item` - widgets that are thinner than the standalone ones, which you can only add as a part of a list (`oh-list` or `oh-list-card`)
-  - **cell widgets**, examples: `oh-cell`, `oh-knob-cell`, `oh-colorpicker-cell`: these widgets are fixed-size cells that you can only add to an `oh-cells` container widget immediately below an `oh-block` in a layout page - they will either perform an action - switching a light on & off - or expanding to reveal additional controls
+  - **cell widgets**, examples: `oh-cell`, `oh-knob-cell`, `oh-colorpicker-cell`: These widgets are fixed-size cells that you can only add to an `oh-cells` container widget immediately below an `oh-block` in a layout page - they will either perform an action - switching a light on & off - or expanding to reveal additional controls
   - **page-specific widgets**, for instance map pages have `oh-map-marker` or `oh-map-circle-marker`, charts have different types of widgets than the rest to represent axes, series etc.
 
 See the [Component Reference](./components/) for details about the different libraries of components.
@@ -147,6 +147,19 @@ To dynamically configure components based on data changed on runtime, expression
 
 Please refer to [widget expressions](widget-expressions-variables.html) for more information.
 
+## Modifying Styling with CSS
+
+In case you want to customize the styling of a page or all its widgets, you can set CSS classes and properties globally for the page:
+
+```yaml
+config:
+  label: My Page
+  style:
+    --f7-card-border-radius: var(--f7-card-expandable-border-radius)
+```
+
+Please read [CSS for Pages & Widgets](css-pages-widgets.html) to learn more about using CSS.
+
 ## Actions
 
 When configuring a widget, you will encounter options related to actions (usually, when something is clicked or touched, but there might be several actions configured for a single widget, for instance, clicking on different parts or a long tap with a touch device); regardless, they will all have the same options:
@@ -175,7 +188,7 @@ Configuring the action type reveal more options in the action sheet:
 | Group details      | Used with Group items to open a popup with an automatically-generated list of the members of the group, represented by their default list item widget. For Groups with a base type like Switch, a standard card widget will also be shown for the Group itself. |
 | Analyze Item(s)    | Opens the Analyzer window for the specified item(s) and period                                                                                                                                                                                                  |
 | External URL       | Open an external web page                                                                                                                                                                                                                                       |
-| Set Variable       | Set a variable that you can use in other parts of the page or widget.                                                                                                                                                                                           |
+| Set Variable       | Set a [variable](widget-expressions-variables.html) that you can use in other parts of the page or widget.                                                                                                                                                      |
 
 ::: tip
 

diff --git a/ui/css-pages-widgets.md b/ui/css-pages-widgets.md
@@ -1,9 +1,9 @@
 ---
 layout: documentation
-title: Styling pages & widgets using CSS
+title: Styling Pages & Widgets
 ---
 
-# Styling pages & widgets using CSS
+# Styling Pages & Widgets
 
 ## Predefined CSS Classes
 

diff --git a/ui/personal-widgets.md b/ui/personal-widgets.md
@@ -59,7 +59,7 @@ This is accomplished by adding a `config` section to the component's YAML.
 ```
 
 Some of the available configuration parameters are specific to a certain component while others, such as `visible` or `class` are available in most components.
-[Expressions](widget-expressions-variables.html) can be used to dynamically set configuration parameters depending on dynamic, changing data, e.g. Item states.
+[Widget expressions](widget-expressions-variables.html) can be used to dynamically set configuration parameters depending on dynamic, changing data, e.g. Item states.
 
 ### Component slots