Merge pull request #1300 from FlowFuse/1225-responsiveness-config

Enable configuration of the responsive breakpoints at the page-level

docs/layouts/index.md

@@ -30,6 +30,12 @@ The core differences are in the "width" property of the size:
 - For "Grid" and "Notebook", the width is calculated as a portion of 12 _columns_, i.e. a width of "6", would take up half of the width of the layout.
 - For "Fixed", the width is calculated as a multiple of 90 _pixels_, i.e. a width of "3", would take up 270px of the screen.
 
+## Breakpoints
+
+Most layouts in Dashboard utilise a concept of "Columns", whereby the group width is defined as a number of columns, e.g. 6, and the page then renders a given number of columns too, e.g. 12. This means that a group with a width of 6 would take up half of the page's width.
+
+Breakpoints [can be configured](../nodes/config/ui-page.md#breakpoints) on a page-by-page basis, controlling how many columns are rendered at different screen sizes. This is particularly useful for responsive design, allowing you to control how many columns are rendered on a mobile device, tablet, or desktop.
+
 ## Theme Options
 
 In addition to the core layout structure, defining how the groups are ordered and laid out, it is also possible to control some of the spacing in a layout through the page's [Theme](../nodes/config/ui-theme).

docs/layouts/types/fixed.md

@@ -16,3 +16,7 @@ It will automatically move widgets to the next row if they don't fit within a gi
 
 ![Fixed Layout](../../assets/images/layout-eg-flex.png){data-zoomable}
 *An example UI rendered using the "Fixed" Layout*
+
+## Breakpoints
+
+Below 576px, Fixed layouts will render in a responsive mode in order to support mobile rendering. Here, they actually become [Grid](../grid.md) layouts, with the width of each group being calculated as a portion of 3 columns, rather than a fixed pixel size.

docs/layouts/types/grid.md

@@ -12,30 +12,12 @@ The layout will automatically move widgets to the next row if they don't fit wit
 
 ## Breakpoints
 
-Depending on the screen size, the number of default columns rendered will change. Here you can see examples of the columns rendered at three breakpoints:
+Depending on the screen size, the number of default columns rendered can change. Here you can see examples of the columns rendered at three breakpoints:
 
 ![Guidelines demonstrating the columns rendered in the "Grid" Layout](../../assets/images/layout-grid-columns.png){data-zoomable}
 _Guidelines demonstrating the columns rendered in the "Grid" Layout at different screen sizes_
 
-### Desktop
-
-- **Breakpoint:** 1024px
-- **Columns:** 12
-
-### Tablet
-
-- **Breakpoint:** 768px
-- **Columns:** 9
-
-### Medium
-
-- **Breakpoint:** > 576px
-- **Columns:** 6
-
-### Mobile
-
-- **Breakpoint:** < 576px
-- **Columns:** 3
+The exact breakpoints used can be configured in the [page's settings](../../nodes/config/ui-page.md#breakpoints).
 
 ## Controlling Width
 

docs/layouts/types/notebook.md

@@ -32,27 +32,11 @@ We can get finer grain width control within a group by increasing it's width. Th
 
 ## Breakpoints
 
-Depending on the screen size, the number of default columns rendered will change. Here you can see examples of the columns rendered at three breakpoints:
+Depending on the screen size, the number of default columns rendered can change. Here you can see examples of the columns rendered at three breakpoints:
 
 ![Guidelines demonstrating the columns rendered in the "Grid" Layout](../../assets/images/layout-grid-columns.png){data-zoomable}
 _Guidelines demonstrating the columns rendered in the "Grid" Layout at different screen sizes_
 
-### Desktop
+The exact breakpoints used can be configured in the [page's settings](../../nodes/config/ui-page.md#breakpoints).
 
-- **Breakpoint:** 1024px
-- **Columns:** 12
-
-### Tablet
-
-- **Breakpoint:** 768px
-- **Columns:** 9
-
-### Medium
-
-- **Breakpoint:** > 576px
-- **Columns:** 6
-
-### Mobile
-
-- **Breakpoint:** < 576px
-- **Columns:** 3
+Also, because Notebook layouts render groups at the full width, the number of columns _within_ the group is generally driven by the _minimum_ of the group's columns/width and the page's columns. So, in a case where a Group has 9 columns, if the page layout enforces 6 columns due to the breakpoint, it will render with 6. If however, the group's width is 6, and the page breakpoint defines 12 columns, the group will still render at 6.

docs/layouts/types/tabs.md

@@ -27,22 +27,6 @@ Depending on the screen size, the number of default columns rendered will change
 ![Guidelines demonstrating the columns rendered in the "Grid" Layout](../../assets/images/layout-grid-columns.png){data-zoomable}
 _Guidelines demonstrating the columns rendered in the "Grid" Layout at different screen sizes_
 
-### Desktop
+The exact breakpoints used can be configured in the [page's settings](../../nodes/config/ui-page.md#breakpoints).
 
-- **Breakpoint:** 1024px
-- **Columns:** 12
-
-### Tablet
-
-- **Breakpoint:** 768px
-- **Columns:** 9
-
-### Medium
-
-- **Breakpoint:** > 576px
-- **Columns:** 6
-
-### Mobile
-
-- **Breakpoint:** < 576px
-- **Columns:** 3
+Also, because Tab layouts render groups at the full width of the screen, the number of columns _within_ the group is driven by the _minimum_ of the group's columns/width and the page's columns. So, in a case where a Group has 9 columns, if the page layout enforces 6 columns due to the breakpoint, it will render with 6. If however, the group's width is 6, and the page breakpoint defines 12 columns, the group will still render at 6.

docs/nodes/config/ui-page.md

@@ -7,6 +7,7 @@ props:
     Theme: Which Dashboard 2.0 theme to use for this page. You can customise your own too.
     Layout: Which Layout Manager to render the widgets with
     Default State: <ul><li><b>Visibility</b> - Defines the default visibility of this page in hte side navigation menu.</li><li><b>Interactivity</b> - Controls whether the item is disabled/enabled in the side navigation menu.</li></ul><p>Both of these can be overridden by the user at runtime using a <code>ui-control</code> node.</p>
+    Breakpoints: Configure the responsive breakpoints for your Dashboard, controlling how many columns render at different screen sizes. Not available for "Fixed" layouts.
 ---
 
 <script setup>
@@ -18,4 +19,42 @@ Each page will be rendered in a navigation drawer within the UI, and can be acce
 
 ## Properties
 
-<PropsTable :hide-dynamic="true"/>
+<PropsTable :hide-dynamic="true"/>
+
+### Breakpoints
+
+![Breakpoints](../../assets/images/breakpoints-config.png)
+_Screenshot showing the default breakpoints configuration_
+
+As detailed in the Layouts section of the documentation, most layout types in Dashboard utilise "breakpoints". Each breakpoint defines:
+
+- A **pixel** value, i.e. when the breakpoint comes into effect
+- A **columns** value, i.e. how many columns should be rendered at this breakpoint
+
+The more columns you have, the more groups and widgets you can fit _side-by-side_ in your page. After this, new content will render to a new row.
+
+Note that configurable breakpoints are not available for "Fixed" layouts as that does not use the column approach to rendering groups.
+
+The default breakpoints are:
+
+### Mobile
+
+- **Breakpoint:** < 576px
+- **Columns:** 3
+
+### Medium
+
+- **Breakpoint:** > 576px
+- **Columns:** 6
+
+### Tablet
+
+- **Breakpoint:** 768px
+- **Columns:** 9
+
+### Desktop
+
+- **Breakpoint:** 1024px
+- **Columns:** 12
+
+

nodes/config/locales/en-US/ui_page.html

@@ -49,5 +49,12 @@ <h3>Properties</h3>
         <dd>
             Any custom CSS classes you want to append to the page's styling when rendered.
         </dd>
+        <dt>
+            Responsive Layouts
+            <span class="property-type">array</span>
+        </dt>
+        <dd>
+            Allows the definition of varying columns to be rendered at different screen sizes, and better render your Dashboard at varying screen sizes. Not available for "Fixed" layouts.
+        </dd>
     </dl>
 </script>

nodes/config/locales/en-US/ui_page.json

@@ -13,6 +13,11 @@
             "notebook": "Notebook",
             "class": "Class",
             "classNamePlaceholder": "Optional CSS class name(s) for page",
+            "responsiveness": "Responsive Layouts",
+            "reset": "reset to defaults",
+            "name": "Name",
+            "breakpoint": "Breakpoint (px)",
+            "columns": "Columns",
             "defaultState": "Default State",
             "visibility": "Visibility",
             "visible": "Visible",