Floorplan and layouts overview

Floorplan and layouts overview in Storybook

Usage

Floorplans enable the designer to immediately start building out their applications. They facilitate consistent and responsive UI composition across application types. Designers can select from four available floorplans and adapt to meet application requirements. Similar to architectural drawings, which illustrate the shape, size, and arrangement of a room, floorplans define a page's shape, layout, and components. Floorplans streamline design across multiple form factors. Learn more by watching the following video.

What are floorplans?

Download transcript

Anatomy

Jutro currently features four different floorplans, which address common use cases:

A sidebar has a maximum width of 320px. It pushes the content in the main content area, forcing it to be responsive. Note: Sidebars do not overlap the main content area.

Content layouts determine the column proportions for components in the main content area. There are five layout options:

1. Global header: the header enables consistent navigation across application experiences. It defines the uppermost part of any given page. Headers are composite components. In other words, they combine other components to fulfill a specific use case.
2. Left navigation: left navigation organizes the content structure and provides context to orient users. It occupies the left of the screen and spans vertically from the header to the bottom of the page.
3. Right sidebar: Jutro floorplans accommodate push and overlay models of the right sidebar. The push model of the right sidebar contains information that is related to the main content area. It is useful for comparing and contrasting information. The overlay model functions as a workspace. It enables users to enter information, toggle, set dates, among other tasks.

Best practices

• Detach once placed and sized: Floorplans need to be detached in order to place content within them. The components and/or styles they contain will still receive updates.
• Access floorplans via the symbol library menu, or as a pre-placed symbol on an art board with a layer grid, which you can copy and paste into your own file.
• All floorplans are symbolized. To make changes, you will need to detach them first.
• When selecting a floorplan, consider which of the following elements you need: left navigation; global header; right sidebar. All floorplans feature the global header.
• Use "L-shape" floorplans when you require a header and left navigation.
• Use "I-shape" floorplans when you only require a header.
• Use "C-shape" floorplans when you require a header, left navigation, and right sidebar.
• Use "r-shape" floorplans when you require a header and right sidebar.
• "r-shape" floorplans with a push model work best with single column, 2:1, 1:2, and 1:1 layouts.

Responsiveness/adaptiveness

Jutro offers responsive layouts to accommodate different screens and form factors. Layouts utilize a 12-column grid for desktop, an 8-column grid for tablet, and a 4-column grids for mobile sizes, all with a 24-pixel gap between columns.

Each shape and layout combination responds to the following breakpoints.

Cards

Cards align to the column grid and are the primary containers for placing content on the layout grid in the main area.

Cards as panels

Cards as panels (<Card isPanel />) are used for the left and right sidebars for contextual content such as navigation or controls.

Layout panels - examples

L-Shape 2:1 Left Nav Collapsed

L-Shape 2:1 Left Nav Expanded

I-Shape 1:1

I-Shape 1:1:1

Interactions

Left navigation includes pre-grouped components for navigation. When you select from these elements, the view of the main content area changes to reflect the selection.

The right sidebar also utilizes the push model which resizes the responsive main content area in order to present its typically contextual content.

Iconography

Out of the box, the left navigation and global header feature icons. However, you have the option to override these.

Code

The AppFloorPlan component sets the overall layout for the entire application. More specifically, it controls:

• Where the navigation is displayed (left or top)
• The header
• The footer
• The right panel

Your overall application layout is managed by a Floorplan. But for specific areas in the application, you can use Jutro layout components.

On a very high level:

1. The Floorplan sets the layout and routing for your application. If wraps each individual page.
2. Each page manages its own layout within the space created by the floorplan. This is where you would insert one of the available layout components.

Jutro has four types of layout components: Flex, Grid, GridLayout, and ColumnsLayout.

The floorplan allows the designer and developer to start with a basic UI application structure, rather than a blank page. The main goal of this is to promote consistent user experience and UI across Guidewire and accelerate the development and design processes.

Shapes

Floorplan shapes are a shorthand for the overall application layouts. Each shape refers to where the navigation is located and whether there is a right panel.

• I-shape: set routes=[]
• L-shape: set sideRoutes=[]
• C-shape: set sideRoutes just like in an L-shape, but you add a rightSide
• r-shape: set routes=[] just like in an I-shape and add a rightSide

Example of usage for basic configuration

The example below shows how to use the various props of AppFloorPlan. Floorplan config is created in a separate metadata file and can be passed to the AppFloorPlan component's floorPlans property. In order to have validation of the floorplan config you need to add $schema path in your floorplan JSON configuration file.

The rightSide prop takes presentation metadata and determines the contents of the right panel.

Expand the metadata

{
  "$schema": "../metadata.schema.json",
  "jutro": "10.3.0",
  "floorplan.default": {
    "type": "floorplan",
    "scrollContent": false,
    "showLeftSide": false,
    "showRightSide": false,
    "routes": [
      {
        "path": "/",
        "exact": true,
        "showOnNavBar": false,
        "redirect": "/welcome"
      },
      {
        "title": {
          "id": "jutro-app.Pages.Welcome.title",
          "defaultMessage": "Welcome"
        },
        "path": "/welcome",
        "exact": true,
        "component": "Welcome"
      },
      {
        "title": {
          "id": "jutro-app.Pages.CodelessForm.FormsMenu",
          "defaultMessage": "Forms"
        },
        "id": "forms",
        "path": "/forms",
        "routes": [
          {
            "title": {
              "id": "jutro-app.Pages.CodelessForm.title",
              "defaultMessage": "Codeless Form"
            },
            "path": "/forms/codeless",
            "exact": true,
            "component": "CodelessForm"
          }
        ]
      },
      {
        "title": {
          "id": "jutro-app.Pages.Settings.title",
          "defaultMessage": "Settings Page"
        },
        "path": "/settings",
        "exact": true,
        "component": "SettingsPage"
      }
    ],
    "header": {
      "showAvatar": true,
      "commonAvatarRoutes": [
        {
          "title": {
            "id": "jutro-app.app.commonAvatar.welcomePage",
            "defaultMessage": "Go to Welcome Page"
          },
          "to": "/welcome",
          "onClick": "trackClick",
          "className": "sampleDropdownLink"
        }
      ],
      "showNotifications": true,
      "logoSrc": "./images/guidewire-logo-dark.svg",
      "showHelp": true,
      "showAppSwitcher": false,
      "helpPopoverItems": [
        {
          "id": "heading",
          "component": "HelpHeading",
          "componentProps": {
            "content": {
              "id": "jutro.app.help.gwCloud",
              "defaultMessage": "Guidewire Cloud"
            }
          }
        },
        {
          "id": "paragraph",
          "component": "HelpParagraph",
          "componentProps": {
            "content": {
              "id": "jutro.app.help.gwCloudDescription",
              "defaultMessage": "Guidewire Cloud™ is the optimal way to experience the power of Guidewire InsurancePlatform™, combining Guidewire software, services, and ecosystem in a scalable SaaS model. It scales according to use, provides cost predictability, and transfers IT risk to Guidewire. Expert Guidewire teams and our SaaS-certified partners provide implementation services, security, ongoing management, and regular updates"
            }
          }
        },
        {
          "id": "link",
          "component": "HelpLink",
          "componentProps": {
            "content": {
              "id": "jutro.app.help.readMore",
              "defaultMessage": "Read more about GW Cloud"
            },
            "href": "https://docs.guidewire.com/"
          }
        }
      ]
    },
    "footer": {
      "content": [
        {
          "id": "footer-text",
          "type": "element",
          "component": "FooterText",
          "componentProps": {
            "text": {
              "id": "jutro.app.footer.legalNotice",
              "defaultMessage": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum vel augue enim. Sed at maximus urna. Integer ut massa non augue sodales lacinia. Integer vestibulum at mi ac fringilla. Aenean posuere sagittis pharetra. Nunc viverra, ex a eleifend faucibus, lorem leo laoreet lectus, consequat dapibus lacus diam non elit. Cras metus magna, lacinia ac ipsum pharetra, gravida amet."
            }
          }
        },
        {
          "id": "footer-nav-bar",
          "type": "container",
          "component": "FooterNavBar",
          "content": [
            {
              "id": "footer-nav-link-1",
              "type": "element",
              "component": "FooterNavLink",
              "componentProps": {
                "header": {
                  "id": "jutro.app.footer.privacyPolicy",
                  "defaultMessage": "Privacy Policy"
                },
                "key": "1"
              }
            },
            {
              "id": "footer-nav-link-2",
              "type": "element",
              "component": "FooterNavLink",
              "componentProps": {
                "header": {
                  "id": "jutro.app.footer.legalNotes",
                  "defaultMessage": "Legal Notes"
                },
                "key": "2"
              }
            },
            {
              "id": "footer-nav-link-2",
              "type": "element",
              "component": "FooterNavLink",
              "componentProps": {
                "header": {
                  "id": "jutro.app.footer.contactUs",
                  "defaultMessage": "Contact Us"
                },
                "key": "3"
              }
            }
          ]
        },
        {
          "id": "footer-copyright",
          "type": "element",
          "component": "FooterCopyright"
        }
      ]
    }
  },
  "floorplan.welcome": {
    "type": "floorplan",
    "matches": [
      "/welcome"
    ],
    "showFooter": false,
    "header": {
      "logoSrc": "./images/guidewire-logo-dark.svg",
      "showNotifications": false,
      "showAppSwitcher": false
    }
  }
}

And add configuration to your page in JSX:

import config from './config.json5';
import { AppFloorPlan } from '@jutro/floorplan';

export default function MyApp() {
  const floorPlans = Object.values(floorPlanConfig).filter(isObject);
  return <AppFloorPlan floorPlans={floorPlans} />;
}

note

The @jutro/auth dependency is now optional for @jutro/router and @jutro/components packages. However, the AppFloorPlan component requires @jutro/auth to be added to your app dependencies to be used.

Routes, navigation, and pages

See our page about routing.

Enabling/disabling different parts of the AppFloorPlan

You can disable/enable each part of the floorplan by setting corresponding property to false/true in the metadata config. All of these are true by default:

• showHeader - show/hide header, this takes precedence over header prop
• showSubHeader - show/hide top navigation, in order to see it you need to have at least one route in routes with showOnNavBar=true
• showFooter - show/hide footer
• showRightSide - show/hide right side, if set to false, the right panel is not displayed, even if you configure rightSide
• showLeftSide - show/hide left navigation, in order to see it you need to have at least one route in sideRoutes with showOnNavBar=true

Custom header

If your header design is significantly different than the out of the box header, and the available customization options are not sufficient, you can provide a custom header renderer function using the renderHeader attribute:

const floorplans = {
    'floorplan.default': {
        ...
        renderHeader() {
            // myCustomHeaderRenderer implementation
        }
    }
}

<AppFloorPlan floorPlans={floorplans} />;

The renderHeader function takes an object with:

• navigationRoutes - visible routes (routes with showOnNavBar not equal/set to false)
• header - the floorplan's header properties
• subHeader - the floorplan's sub header properties.

With showSubHeader set to false you can also implement your own sub header as part of the custom header. The custom header height is not limited anyhow - you can render any header you and your designers imagine!

important

The custom header option is extremely flexible, but keep that in mind that there is a cost. You are responsible for handling aspects like responsiveness and accessibility yourself. Jutro exposes a few small blocks to help build such a custom header - see the custom header example in Storybook.

Right side

The rightSide prop takes a configuration object which determines the contents of the right panel. Consider this example of right side:

{
  "showRightSide": true,
  "rightSide": {
    "collapsible": true,
    "sides": [
      {
        "label": {
          "id": "lelum",
          "defaultMessage": "Example right side 1"
        },
        "icon": "gw-home",
        "component": "RightSideContent",
        "componentProps": {
          "foodItem": "banana"
        }
      },
      {
        "label": {
          "id": "polelum",
          "defaultMessage": "Example right side 2"
        },
        "icon": "gw-star",
        "component": "RightSideContent",
        "componentProps": {
          "foodItem": "cup of coffee"
        }
      }
    ],
    "shouldFocusAfterRender": true,
    "isInitiallyCollapsed": false
  }
}

To make this example work, create a RightSideContent:

function RightSideContent({ foodItem }) {
  return <div>Enjoy this {foodItem}!</div>;
}

The configuration creates a right panel with two buttons. Clicking the buttons switches between two panels. One of them says "Enjoy this banana!", and other says "Enjoy this cup of coffee!".

rightSide accepts the following props:

• collapsible - if true, the user can collapse the panel. This prop is false by default for desktop and true for smaller devices.

• isInitiallyCollapsed - if true, the panel is collapsed when the floorplan renders. This prop is false by default for desktop and true for smaller devices.

• shouldFocusAfterRender - if true, the panel is focused after expanding. This is useful for proper accessibility support because the content will be read by a screen reader. If the rightSide panel is expanded by something other than the default expansion button, such as when controlled mode is used, it is also easy for keyboard users to navigate through it.

• sides - an array of objects, each contains configuration of a button and a content section. Each object can have following props:

  • id - (optional) a unique ID you want to set on the component.
  • label - the label for the button.
  • icon - (optional) the icon to display on the button, for example gw-bathtub. At least two icons are required for them to appear.
  • component - the component to render.
  • componentProps - (optional) the props to pass to the component.

  When the user clicks a button, the panel renders the associated component.

Floorplan overrides

You can use a different floorplan for individual pages of the application. Create a floorplan configuration with a matches prop with paths to pages.

"matches": ["/welcome", "/contact"];

If there are several override configs for the same path, the first one takes precedence.

If you have more than one floorplan configuration without the matches prop, the first one is considered default. If you do not provide an override for a page, it uses the default floorplan.

If header, footer etc props are specified in the default configuration, you need to override all the properties in the override configuration. They will not be merged together with the default configuration.

Adding this floorplan override for the metadata above will alter configuration for the welcome page:

{
  "$schema": "../metadata.schema.json",
  "jutro": "10.1.0",
  "floorplan.welcome": {
    "type": "floorplan",
    "matches": [
      "/welcome"
    ],
    "showFooter": false,
    "header": {
      "logoSrc": "./images/guidewire-logo-dark.svg",
      "showNotifications": false,
      "showAppSwitcher": false
    }
  }
}