Merge pull request #664 from FlowFuse/659-docs-layouts

Docs: Layout Management

docs/.vitepress/config.js

@@ -119,9 +119,15 @@ export default ({ mode }) => {
           text: 'Layouts',
           collapsed: false,
           items: [
-            { text: 'Grid', link: '/layouts/grid' },
-            { text: 'Fixed', link: '/layouts/fixed' },
-            { text: 'Notebook', link: '/layouts/notebook' }
+            { text: 'Getting Started', link: '/layouts/' },
+            { 
+              text: 'Types',
+              items: [
+                { text: 'Grid', link: '/layouts/types/grid' },
+                { text: 'Fixed', link: '/layouts/types/fixed' },
+                { text: 'Notebook', link: '/layouts/types/notebook' }
+              ]
+            }
           ]
         },
         {

docs/layouts/index.md

@@ -0,0 +1,53 @@
+# Layouts
+
+Layouts are a configuration available on a page-by-page basis. They control how all of the [Groups](../nodes/config/ui-group) of widgets are laid out on a given [Page](../nodes/config/ui-page):
+
+![Screenshot of the layout options on a ui-page](../../assets/images/layouts-page-layout-option.png){data-zoomable}
+_Screenshot of the layout options on a `ui-page`_
+
+We currently offer three different layout options:
+
+- [Grid](./types/grid.md)
+- [Fixed](./types/fixed.md)
+- [Notebook](./types/notebook.md)
+
+## Sizing Groups & Widgets
+
+A fundamental component of building out layouts in Dashboard 2.0 (which follows the Dashboard 1.0 principle) is the ability to control the size of each group and widget with the size selection widget:
+
+![Screenshot of the size selection widget for a ui-gauge](../../assets/images/layouts-sizing-options.png){data-zoomable}
+_Screenshot of the size selection widget for a ui-gauge_
+
+Exactly what this sizing means does differ slightly depending on the layout you're using, but the general principle is that the size of a group or widget will control how much space it takes up in the layout. 
+
+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.
+
+## 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).
+
+### Configurable Options
+
+![Screenshot of the theme options available to control sizings of the layout](../../assets/images/layouts-theme-options.jpg){data-zoomable}
+_Screenshot of the theme options available to control sizings of the layout_
+
+Each color here correlates to the respective section in the following image:
+
+![Screenshot of the theme options available to control sizings of the layout](../../assets/images/layouts-theme-example.jpg){data-zoomable}
+_Screenshot of the theme options available to control sizings of the layout, here showing a "Grid" layout_
+
+- **Page Padding:** The spacing that encapsulates the full page's content, depicted above as the <span style="color: orange;">orange</span> space.
+- **Group Gap:** The spacing between each group, depicted above as the <span style="color: lightseagreen;">green</span> space.
+- **Widget Gap:** The spacing between each widget, within a group, depicted above as the <span style="color: deeppink;">pink</span> space.
+
+An additional option available on a group-by-group basis is whether or not to show the Group's name, above depeicted by the <span style="color: goldenrod;">yellow</span> space. If this is hidden, the Group Padding (<span style="color: blue;">blue</span>), will render on all four sides of the group.
+
+### Not Configurable (Currently)
+
+Whilst we do offer reasonable levels of customization, there are some areas not currently configurable:
+
+- **Row Height:** A single unit of height is currently fixed at 48px. This cannot be changed at this time. This also affects the "Fixed" layout, where a single unit of width is driven by this value.
+- **Group Padding:** The spacing that encapsulates the full group's content, depicted above as the <span style="color: blue;">blue</span> space.

docs/layouts/types/fixed.md

@@ -0,0 +1,14 @@
+# Layout: Fixed
+
+_Note: This layout still needs work to make it more flexible and practical, it is advised to use another layout for now._
+
+Each "unit" is a fixed width, which was the only layout available in Dashboard 1.0. 
+
+It is built as a flexbox layout, with a single row of widgets. Width of each group is a fixed pixel size, calculated as the "width" property of a group, multiplied by 90px (where our default row height is 45px).
+
+The groups themselves follow the same pattern as all other layouts whereby a group of width "6" would have 6 "columns", with the widgets sizing accordingly, soa  widget of size "3 x 1" would be 50% of the group's width.
+
+It will automatically move widgets to the next row if they don't fit within a given screen width, and does not change size with the screen size, which often leaves a lot of empty screen real estate. The height of each row is determined by the tallest widget in that row.
+
+![Fixed Layout](../../assets/images/layout-eg-flex.png){data-zoomable}
+*An example UI rendered using the "Fixed" Layout*

docs/layouts/types/grid.md

@@ -0,0 +1,51 @@
+# Layout: Grid
+
+Similar to Bootstrap's [Grid](https://getbootstrap.com/docs/4.0/layout/grid/) System, this provides 12 (by default) columns, within which content can be scaled. It is built as a CSS Grid layout.
+
+Each group's width represents the number of columns that it will populate in the overall Page's Grid layout, e.g. a Group, with width 12, will be full width of the screen, even when that screen width is changed.
+
+The layout will automatically move widgets to the next row if they don't fit within a given row. The height of each row is determined by the tallest widget in that row.
+
+## 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:
+
+![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
+
+### Mobile
+
+- **Breakpoint:** < 768px
+- **Columns:** 6
+
+## Controlling Width
+
+Groups will populate the width as defined, and then they create their own grid layout internally where the number of columns in that group is equal to the width of the group. The groups can have their own internal paddings and pages that can be customized.
+
+![Guidelines demonstrating the columns rendered in the "Grid" Layout](../../assets/images/layout-grid-example.png){data-zoomable}
+_Guidelines demonstrating the columns rendered in the "Grid" Layout at different screen sizes_
+
+You can read more about these customizations to the theme and layout [here](../index.md).
+
+## Controlling Empty Space
+
+Controlling empty space can be tricky with a Grid Layout. We do not have a smart masonry layout ([example](https://masonry.desandro.com/layout)) currently, instead we are utilizing [CSS's Grid Layout Module](https://www.w3schools.com/css/css_grid.asp).
+
+As such, the height of a given "row" of widgets is determined by the tallest widget in that row.
+
+Most widgets will strictly abide by their widget and height specified, however, some (e.g. `ui-template` or `ui-markdown`) will grow with their content, even if that means surpassing the height specified in the widget's config.
+
+Here, we can see an example of a rendered Grid layout in Dashboard 2.0:
+
+![Grid Layout](../../assets/images/layout-eg-grid.png){data-zoomable}
+*An example UI rendered using the "Grid" Layout*

docs/layouts/types/notebook.md

@@ -0,0 +1,28 @@
+<script setup>
+    import AddedIn from '../../components/AddedIn.vue'
+</script>
+
+# Layout: Notebook <AddedIn version="0.4.0" />
+
+This layout mimics a traditional Jupyter Notebook, where the layout will stretch to 100% width, up to a maximum width of 1024px, and will centrally align.
+
+A common use case for this type of layout would be to inject dynamic Markdown, data tables and data visualisations.
+
+![Notebook Layout](../../assets/images/layout-eg-notebook.png){data-zoomable}
+*An example UI rendered using the "Notebook" Layout*
+
+## Controlling Width & Columns
+
+Within the Notebook itself, the "width" property follows the same _columns_ principles of the Grid layout, which you can read more about [here](grid.md), but with a full default width of "6".
+
+By increasing the "width" of a group, you're actually increasing the number of columns that group will represent, within which the widgets will render. This provides the means to add finer grain control over the layout of your UI, allowing you to put more widgets side-by-side in a single row, and helps with responsiveness of your dashboard.
+
+A group has a default width of "6" columns, with the full Notebook also a width of "6". Here, we can see two charts, rendered side-by-side, with each chart having a width of "3" columns.
+
+![Notebook Layout](../../assets/images/layout-eg-notebook-width6.png){data-zoomable}
+*An example UI rendered using the "Notebook" Layout*
+
+We can get finer grain width control within a group by increasing it's width. The Notebook itself will not render the group any wider, but the group itself will render with 12 columns internally. So, if we increase the "width" (number of columns) of the group to 12, then the two charts are then setup to only take up half of the width of the group (3 columns each).
+
+![Notebook Layout](../../assets/images/layout-eg-notebook-width12.png){data-zoomable}
+*An example UI rendered using the "Notebook" Layout*