AppFloorPlan

AppFloorPlan dans Storybook

Le composant AppFloorPlan définit la disposition générale de l’ensemble de l’application, y compris le contenu de chaque section. Plus précisément, il contrôle :

L'en-tête
Le pied de page
L'emplacement où le volet de navigation est affiché : à gauche (panneau latéral) ou en haut (sous-en-tête)
Le panneau droit

La disposition générale de votre application est gérée par un AppFloorPlan. Ceci étant, pour des zones spécifiques de l’application, vous pouvez utiliser des composants de contenu de mise en page Jutro tels que Grid ou Flex ou des composants personnalisés.

De façon très générale :

Le AppFloorPlan définit la mise en page et le routage pour votre application. Il englobe chacune des pages.
Chaque page gère sa propre mise en page dans l'espace créé par le AppFloorPlan. C'est ici que vous inséreriez l'un des composants de contenu de mise en page standard disponibles.

Note: Grâce aux différentes propriétés et fonctions de rendu transmises au composant AppFloorPlan, il est possible de créer différentes structures de mise en page, en utilisant le contenu prédéfini ou en fournissant des composants personnalisés.

Code

Note:

La dépendance @jutro/auth est désormais facultative pour les packages @jutro/router et @jutro/components . Cependant, AppFloorPlan component nécessite que @jutro/auth soit ajouté aux dépendances de votre application pour être utilisé.

Instruction d'importation

import { AppFloorPlan } from '@jutro/floorplan';

Cahier des charges du composant

Propriétés

className

Type

string

Description

CSS class name for this component.

contentAsSectionElement

Type

boolean

Description

If set to true, content is rendered within <section> HTML tags, otherwise <main> is used. This is used when the page contains nested floorplans as only one element with main role is recommended.

contentClassName

Type

string

Description

Additional class name for the main component.

contentLayout

Type

'canvas' | 'default' | 'center'

Description

Layout type of the main content.

excludeScrollToTopRoutes

Type

Route[]

Description

Routes to be excluded from automatic scroll to the top on a location change.

header

Type

FloorplanHeaderProps

Description

Properties for the application's Header component.

leftSide

Type

object

className: Type
string
Description
CSS class name for this component.
collapsed: Type
boolean
Description
If set to true, component is currently collapsed.
collapsible: Type
boolean
Description
If set to true, component can be collapsed.
contextSwitcher: Type
Nullable<ContextSwitcherPropTypes>
Description
Context switcher object.
renderContextSwitcher: Type
RenderContextSwitcher
Description
Callback to render custom ContextSwitcher instead of default one.

Description

Props passed to SideNavigation component.

noContentPadding

Type

boolean

Description

If set to true, padding of the page content will be removed.

renderFooter

Type

({ className }: { className: string }) => ReactNode

Description

Function to render a custom footer.

rightSide

Type

object

collapsible

Type

boolean

Description

If set to true, component can be collapsed. This prop is false by default for desktop and true for smaller devices.

isInitiallyCollapsed

Type

boolean

Description

If set to true, component will be collapsed on initial render. This prop is false by default for desktop and true for smaller devices.

shouldFocusAfterRender

Type

boolean

Description

If set to true, component will be in focus after render. This is useful for proper accessibility support because the content will be automatically read by a screen reader.

sides

Type

SideContentShape[]

componentobligatoire: Type
ReactComponent
Description
Component to render as content.
labelobligatoire: Type
IntlMessageShape
Description
The aria-label describing the content. This text is not rendered and is only used for accessibility.
componentProps: Type
object
Description
Props to pass to the component passed to the component property. The type depends on the value of the component property.
icon: Type
string | Icon
Description
An Icon component to render on the component. The value must be an Icon component or the icon's name. For example, CheckIcon or 'gw-check'.
id: Type
string
Description
Unique identifier for the component.

Description

List of pages to render in the panel.

Description

Right panel config.

routes

Type

Route[]

Description

App routes to be shown in the subheader or, if the screen is mall, the burger menu.

scrollContent

Type

boolean

Description

If set to true, the height of the content is set to the height of the screen and the footer will be displayed at the bottom of the screen.

showFooter

Type

boolean

Description

If set to false, the footer will not be shown.

showHeader

Type

boolean

Description

If set to false, the header will not be shown.

showLeftSide

Type

boolean

Description

If set to true and if a value has been passed to sideRoutes, then the left side panel will be shown.

showRightSide

Type

boolean

Description

If set to false, the right side panel will not be shown.

showSubHeader

Type

boolean

Description

If set to false, the subheader will not be shown.

sideRoutes

Type

Route[]

Description

App routes to be shown in leftSide.

subHeader

Type

object

className: Type
string
Description
CSS class name for this component.
contextSwitcher: Type
Nullable<ContextSwitcherPropTypes>
Description
Context switcher component that will be rendered in the left side of the header.
renderContextSwitcher: Type
RenderContextSwitcher
Description
Callback to render custom ContextSwitcher instead of default one.
renderCustomComponent: Type
JSXElementConstructor<Record<string, never>>
Description
Custom component placed on the right side of subheader or in burger menu.

Description

Sub header config.

Propriétés d'en-tête

La propriété header du composant AppFloorPlan prend un objet avec les propriétés suivantes :

appSwitcherCollapsibleGroupsThreshold: Type
number
Description
Number of items from which the groups in AppSwitcher are collapsible and the search field is displayed.
appSwitcherFooterText: Type
IntlMessageShape | LinkPropTypes
Description
Text displayed on the footer link in AppSwitcher. See IntlMessageShape and Link for more detailed information on the accepted types.
appSwitcherFooterUrl: Type
Record<string, (...args: any[]) => void>
Description
URL to which the footer link in the AppSwitcher leads.
appSwitcherHideFooter: Type
boolean
Description
If set to true, the footer in the AppSwitcher is hidden.
appSwitcherItems: Type
AppSwitcherItems
Description
Array of items to be displayed in the App Switcher menu.
appSwitcherSearchEnabled: Type
boolean
Description
If set to true, enables the search field in AppSwitcher if the number of items are equal to or above the appSwitcherCollapsibleGroupsThreshold value.
avatarChildren: Type
React.ReactNode
Description
Avatar content to be rendered before routes links.
avatarProps: Type
AvatarPropTypes
Description
Avatar props to be passed down if not using auth info (username, imageSource, title, subtitle).
burgerMenuRoutes: Type
Route[]
Description
Routes to be rendered in the burger menu, for breakpoints smaller than desktop.
callbackMap: Type
Record<string, (...args: any[]) => void>
Description
Map to resolve callbacks on avatar links.
className: Type
string
Description
CSS class name for this component.
commonAvatarRoutes: Type
Array<DropdownMenuLinkShape>
Description
Array of items to be displayed as common Avatar content.
contextSwitcher: Type
Nullable<ContextSwitcherPropTypes>
Description
Context switcher object.
helpPopoverItems: Type
React.ReactNode[]
Description
Help popover items.
helpUrl: Type
IntlMessageShape | LinkPropTypes
Description
The link path for the help page.
languageSelectorProps: Type
LanguageSelectorProps
Description
Props passed to Language Selector.
logoAlt: Type
IntlMessageShape
Description
Logo image's alt prop.
logoSrc: Type
string
Description
Display a logo from source.
logoTitle: Type
IntlMessageShape
Description
The title for the logo.
logoUrl: Type
string
Description
Link path to a logo.
notificationChildren: Type
React.ReactNode
Description
Notification content to be rendered.
onAppSwitcherFooterClick: Type
(event: React.SyntheticEvent) => void
Description
Callback which will be triggered when the footer link in the AppSwitcher is clicked.
onLoadValues: Type
function
Description
Function for asynchronous data loading in the search field.
onSearchValueChange: Type
function
Description
Display a search field. Callback for the search field value change.
renderBurgerMenuCustomItem: Type
JSXElementConstructor<Record<string, never>>
Description
Component to be rendered inside burger menu after navigation.
renderContextSwitcher: Type
RenderContextSwitcher
Description
Callback to render custom ContextSwitcher instead of default one.
renderCustomComponent: Type
JSXElementConstructor<Record<string, never>>
Description
Custom component to be rendered in the application header. It will be rendered on the left of actions menu.
renderHeader: Type
(props: RenderHeaderProps) => ReactNode
Description
Function to render a custom header.
renderHelpPopoverItems: Type
() => ReactElement
Description
Render custom help popover items.
searchAvailableValues: Type
LookupOptionShape[]
Description
An array of choice objects to display, works only if onLoadValues is not supplied.
searchFieldPlaceholder: Type
IntlMessageShape
Description
Search field placeholder text.
searchOptionTypes: Type
LookupOptionType[]
Description
Array of option types variants in the search lookup field.
showAppSwitcher: Type
boolean
Description
If set to true, will show App Switcher.
showAvatar: Type
boolean
Description
Display the avatar.
showHelp: Type
boolean
Description
If set to true, shows the Help dropdown.
showLanguageSelector: Type
boolean
Description
If set to true, shows the Language Selector.
showNotifications: Type
boolean
Description
Display the notification icon.
useAuthInfo: Type
boolean
Description
If set to true, uses Okta auth information.

Activation/désactivation de différentes parties de AppFloorPlan

Vous pouvez activer/désactiver chaque partie de AppFloorPlan en définissant la propriété correspondante sur false/true. Tous ces éléments sont true par défaut :

showHeader : afficher/masquer l'en-tête ; cette propriété est prioritaire par rapport à la propriété header
showSubHeader : afficher/masquer le volet de navigation supérieur ; pour le voir, au moins un des chemins dans routes doit être défini sur showOnNavBar=true
showFooter : afficher/masquer le pied de page
showRightSide : afficher/masquer le côté droit ; si défini sur false, le panneau droit n'est pas affiché, même si vous configurez rightSide
showLeftSide : afficher/masquer le volet de navigation gauche ; pour le voir, au moins une des routes dans sideRoutes doit être définie sur showOnNavBar=true

Vous pouvez contrôler les routes à l'aide de la propriété routes ou sideRoutes de AppFloorPlan. Pour ajouter de nouvelles pages à votre application, ajoutez-les à l'une de ces propriétés.

Définissez sideRoutes pour afficher le volet de navigation sur le côté gauche. Définissez routes pour afficher le volet de navigation en haut dans le sous-en-tête. Si vous voulez afficher le volet de navigation supérieur et aussi celui de gauche, vous pouvez définir sideRoutes et routes.

Ces routes ont la forme suivante :

export type Route = {
  // react-router-dom Route and Redirect props
  //URL path of the route
  path?: string,
  // If true, will only match if the path matches 
  // the location.pathname exactly
  exact?: boolean,
  //If true, a path that has a trailing slash will 
  // only match a location.pathname with a trailing slash
  strict?: boolean,
  // Match is case sensitive
  sensitive?: boolean,
  //Path to which redirect when entering the current page
  redirect?: string,
  //When true, redirecting will push a new entry onto 
  // the history instead of replacing the current one
  push?: boolean,
  //The location to redirect to
  to?: IntlToShape,
  //A pathname to redirect from
  from?: string,
  // end of react-router-dom
  
  //Identifier for the route
  id?: string,
  // Component to be rendered as the destination page 
  // for this route
  component?: ReactComponent,
  //Properties for the component to be rendered
  componentProps?: Record<string, unknown>,
  //Title to be displayed for the route
  title?: IntlMessageShape,
  //Defines whether the route should be shown in the navigation
  showOnNavBar?: boolean,
  //Nav link properties
  navLink?: NavLinkPropTypes,
  //Array of sub-routes
  routes?: Route[],
  //An external path
  href?: string,
};

Pour plus de détails, consultez la page sur le routage.

Remplacements de plan

Vous pouvez utiliser une définition différente pour chacune des pages de l'application. Créez une configuration (FloorplanOverride) au moyen d'une propriété matches avec des chemins vers les pages.

 { 
  ...
  matches: ["/welcome", "/contact"];
  ...
 }

S'il existe plusieurs configurations de remplacement pour le même chemin, la première est prioritaire.

Si vous disposez de plusieurs configurations sans la propriété matches, la première est considérée comme la configuration par défaut. Si vous ne proposez aucune configuration de remplacement pour une page, celle-ci utilise le plan par défaut.

La configuration de remplacement a uniquement besoin de préciser les différences avec la configuration par défaut, car elle sera fusionnée avec celle-ci.

  export const example2PageDefinition = (): FloorPlanOverride {
    return {
        // Configuration override for the /example2 path only
        showRightSide: false,
        matches: '/example2'
    }
  }
  export const floorPlanDefinition = (): FloorPlan { 
    return { 
      // Default `AppFloorPlan` configuration definition
      contentLayout: 'canvas'
      showRightSide: true,
      rightSide: {
        ...
      }
    }
  }

  export function Jutro(): JSX.Element {
    return <AppFloorPlan 
              floorPlans={[floorPlanDefinition(), example2PageDefinition()]} />;
}

Mise en page du contenu

Dans AppFloorPlan, lors de l’application d’une mise en page de remplissage pour un conteneur de contenu principal, vous pouvez utiliser la propriété contentLayout avec l’une de ses variantes :

center qui indique une largeur maximale et centrée horizontalement
canvas sans remplissage
default avec un remplissage Guidewire standard (valeur par défaut)

contentLayout définit la mise en page par défaut pour toutes les pages de votre application. Si vous souhaitez modifier la mise en page des sous-pages de façon à ce qu'elle soit différente de la mise en page par défaut, vous devez définir les paramètres souhaités à partir d'un élément FloorplanOverrides:

  export const example2PageDefinition = (): FloorPlanOverride {
    return {
        contentLayout: 'center',
        matches: '/example2'
    }
  }
  export const floorPlanDefinition = (): FloorPlan { 
    return { 
      // Default configuration
      contentLayout: 'canvas'
    }
  }

  export function Jutro(): JSX.Element {
    return <AppFloorPlan 
              floorPlans={[floorPlanDefinition(), example2PageDefinition()]} />;
}

Propriété `contentClassName`

Vous pouvez également utiliser une propriété contentClassName permettant de placer des fichiers CSS personnalisés dans le conteneur de contenu principal pour modifier les arrière-plans et d'autres styles.

Exemples

Consultez les sections Utilisation et Code pour obtenir plus de détails, ainsi que des options et des exemples de configuration.

Configuration de base

L'exemple ci-dessous affiche la façon d'utiliser les différentes propriétés de AppFloorPlan. Une page avec un en-tête et des volets gauche et droit s’affiche, chacun d’entre eux avec deux éléments enfants.

import React from 'react';
import { AppFloorPlan } from '@jutro/floorplan';
import { FloorPlan } from '@jutro/floorplan';
import { ChatIcon, MailIcon } from '@jutro/icons';
import { Card } from '@jutro/components';

export const floorPlanDefinition = (): FloorPlan {
    return {
        showHeader: true,
        header: {
            showNotifications: true,
            logoSrc: './images/guidewire-logo-dark.svg',
            logoTitle: 'Guidewire',
            showHelp: true,
            showAppSwitcher: true,
            showLanguageSelector: false,
        },
        showSubHeader: false,
        showLeftSide: true,
        leftSide: {
            collapsible: true,
            
        },
        sideRoutes: [
            {
                path: '/',
                exact: true,
                showOnNavBar: false,
                redirect: '/example',
            },
            {
                title: 'Example page',
                path: '/example',
                exact: true,
                component: PageExample,
            },
            {
                title: 'Example page 2',
                path: '/example2',
                exact: true,
                component: PageExample,
            },
        ],
        showRightSide: true,
        rightSide: {
            collapsible: true,
            isInitiallyCollapsed: true,
            sides: [
                { 
                    label: "Open chat",
                    icon: ChatIcon,
                    component: RightSideExample,
                },
                { 
                    label: "Email",
                    icon: MailIcon,
                    component: RightSideExample,
                }
            ],
        },
        showFooter: false,
    };
};

export function Jutro(): JSX.Element {
    return <AppFloorPlan floorPlans={[floorPlanDefinition()]} />;
}


const PageExample = (): JSX.Element {
    return <Card title="Example page" 
              subTitle="This can be any type of component" isPanel></Card>
}

const RightSideExample = (): JSX.Element {
    return <Card title="Example page" 
              subTitle="This can be any type of component"></Card>
}

En-tête personnalisé

Warning: L'option d'en-tête personnalisé est extrêmement flexible, mais il y a un prix à payer. Vous êtes responsable de gérer vous-même les aspects tels que la réactivité et l'accessibilité. Jutro met à votre disposition quelques petits blocs pour vous aider à créer un en-tête personnalisé de ce type ; reportez-vous à l'exemple de sous-en-tête personnalisé dans Storybook.

Si la conception de votre en-tête est radicalement différente de l'en-tête de la configuration de base et que les options de personnalisation disponibles ne sont pas suffisantes, vous pouvez proposer une fonction de rendu d'en-tête personnalisé au moyen de l'attribut renderHeader :

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

<AppFloorPlan floorPlans={floorplans} />;

La fonction renderHeader comporte les arguments suivants :

navigationRoutes : routes visibles (routes avec showOnNavBar non défini surfalse)
header : les propriétés d’en-tête de AppFloorPlan.
subHeader : les propriétés de sous-en-tête de AppFloorPlan.

Avec showSubHeader définie sur false, vous pouvez également implémenter votre propre sous-en-tête en tant qu’en-tête personnalisé, la hauteur de l’en-tête personnalisé n’étant limitée d’aucune façon.

Côté droit

La propriété rightSide utilise un objet de configuration qui détermine le contenu du panneau de droite. Prenons l'exemple du côté droit :

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

Pour que cet exemple fonctionne, créez un RightSideContent :

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

La configuration crée un panneau droit avec deux boutons. Cliquez sur les boutons pour passer d'un panneau à l'autre. L'un d'eux indique « Goûtez cette banane ! » et l'autre « Goûtez cette tasse de café ! ».

Les propriétés possibles pour rightSide se trouvent dans le tableau des propriétés de l’onglet Code.

Code​

Instruction d'importation​

Cahier des charges du composant​

Propriétés​

className​

contentAsSectionElement​

contentClassName​

contentLayout​

excludeScrollToTopRoutes​

header​

leftSide​

noContentPadding​

renderFooter​

rightSide​

routes​

scrollContent​

showFooter​

showHeader​

showLeftSide​

showRightSide​

showSubHeader​

sideRoutes​

subHeader​

Propriétés d'en-tête​

appSwitcherCollapsibleGroupsThreshold​

appSwitcherFooterText​

appSwitcherFooterUrl​

appSwitcherHideFooter​

appSwitcherItems​

appSwitcherSearchEnabled​

avatarChildren​

avatarProps​

burgerMenuRoutes​

callbackMap​

className​

commonAvatarRoutes​

contextSwitcher​

helpPopoverItems​

helpUrl​

languageSelectorProps​

logoAlt​

logoSrc​

logoTitle​

logoUrl​

notificationChildren​

onAppSwitcherFooterClick​

onLoadValues​

onSearchValueChange​

renderBurgerMenuCustomItem​

renderContextSwitcher​

renderCustomComponent​

renderHeader​

renderHelpPopoverItems​

searchAvailableValues​

searchFieldPlaceholder​

searchOptionTypes​

showAppSwitcher​

showAvatar​

showHelp​

showLanguageSelector​

showNotifications​

useAuthInfo​

Activation/désactivation de différentes parties de AppFloorPlan​

Routes, navigation et pages​

Remplacements de plan​

Mise en page du contenu​

Propriété contentClassName​

Exemples​

Configuration de base​

En-tête personnalisé​

Côté droit​

Code

Instruction d'importation

Cahier des charges du composant

Propriétés

`className`

`contentAsSectionElement`

`contentClassName`

`contentLayout`

`excludeScrollToTopRoutes`

`header`

`leftSide`

`noContentPadding`

`renderFooter`

`rightSide`

`routes`

`scrollContent`

`showFooter`

`showHeader`

`showLeftSide`

`showRightSide`

`showSubHeader`

`sideRoutes`

`subHeader`

Propriétés d'en-tête

`appSwitcherCollapsibleGroupsThreshold`

`appSwitcherFooterText`

`appSwitcherFooterUrl`

`appSwitcherHideFooter`

`appSwitcherItems`

`appSwitcherSearchEnabled`

`avatarChildren`

`avatarProps`

`burgerMenuRoutes`

`callbackMap`

`className`

`commonAvatarRoutes`

`contextSwitcher`

`helpPopoverItems`

`helpUrl`

`languageSelectorProps`

`logoAlt`

`logoSrc`

`logoTitle`

`logoUrl`

`notificationChildren`

`onAppSwitcherFooterClick`

`onLoadValues`

`onSearchValueChange`

`renderBurgerMenuCustomItem`

`renderContextSwitcher`

`renderCustomComponent`

`renderHeader`

`renderHelpPopoverItems`

`searchAvailableValues`

`searchFieldPlaceholder`

`searchOptionTypes`

`showAppSwitcher`

`showAvatar`

`showHelp`

`showLanguageSelector`

`showNotifications`

`useAuthInfo`

Activation/désactivation de différentes parties de AppFloorPlan

Routes, navigation et pages

Remplacements de plan

Mise en page du contenu

Propriété `contentClassName`

Exemples

Configuration de base

En-tête personnalisé

Côté droit