@financial-times/dotcom-ui-layout

This package composes the basic page layout, including selection of the header and footer variants, and insertion of elements that prepend/append them.

Getting started

This package is compatible with Node 12+ and is distributed on npm.

npm install --save @financial-times/dotcom-ui-layout

After installing the package you can use it to wrap your application views and pages. The layout includes the global UI elements so you can focus on the contents of your pages.

Usage with JSX

If you're using React and JSX you can use the <Layout /> component to wrap your existing component tree.

import React from 'react'
import Home from './pages/Home'
import { Layout } from '@financial-times/dotcom-ui-layout'

const page = <Layout {...options}><App /></Layout>

Please note that the layout component is designed to be used on the server-side. It can be rendered on the client-side but there is not usually a good reason to do so. If possible you should consider <App /> as your application root and client-side mounting point.

Usage without JSX

If your application is not using React or JSX then you can still use the Layout component via React's createElement() function to wrap your existing HTML. In this case the contents option is used to pass in a pre-rendered string of HTML.

const React = require('react')
const renderApp = require('./lib/render-app')
const { Layout } = require('@financial-times/dotcom-ui-layout')

const html = renderApp()
const page = React.createElement(Layout, { contents: html, ...options })

Rendering to a string

However you are integrating the layout component with your application you will need to convert the output from a React element to a string or stream of HTML to send to your application's users. You need to use the react-dom package for this:

const ReactDOM = require('react-dom/server')
const outputHTML = ReactDOM.renderToStaticMarkup(document)

For a full example for how to use this component please refer to the FT UI example app.

Styles

This component includes styles written in Sass which includes the styles for n-ui-foundations and the header and footer components. It can be imported into your application's main Sass stylesheet:

@import '@financial-times/dotcom-ui-layout/styles';

It is also possible to build the layout styles individually, for example to improve long-term caching. If you integrate the layout styles this way then you may need to add a dependency on n-ui-foundations and import its mixins into your app's main Sass stylesheet:

@import 'n-ui-foundations/mixins';

Please note that the exact usage will depend on how you configure your Sass compiler and whether or not you are using Bower to install dependencies.

Options

Props

| PROP | TYPE | OPTIONAL | DEFAULT | DESCRIPTION | |-----------------|-------------------------------------------------|----------|-------------|----------------------------------------------------------------------------------------------| | navigationData | TNavigationData | true* | undefined | Required if using the built in header and/or footer components. See note below. | | headerVariant | 'simple' | 'large-logo' | 'logo-only'| 'no-outbound-links'| false | true | "simple" | The type of built in header to display | | headerBefore | string | ReactElement | true | undefined | A slot for content to appear before Header | | headerAfter | string | ReactElement | true | undefined | A slot for content to appear after Header | | headerOptions | THeaderProps | true | undefined | Pass options to the header component | | headerComponent | ReactElement | true | undefined | Pass a custom header | | footerVariant | 'simple' | 'legal' | false | true | "simple" | The type of built in footer to display | | footerBefore | string | ReactElement | true | undefined | A slot for content to appear before Footer | | footerAfter | string | ReactElement | true | undefined | A slot for content to appear after Footer | | footerOptions | TFooterProps | true | undefined | Pass options to the footer component | | footerComponent | ReactElement | true | undefined | Pass a custom footer | | contents | string | true | undefined | A prerendered string of HTML used to insert the page contents when not using JSX composition |

* Navigation data is required to render all header variants except for "logo-only". Navigation data is required to render all built in footer components. It is recommended to integrate the navigation package with your application to get navigation data.

Custom components

All slots accept both custom React components or a string of HTML.

import { Layout } from '@financial-times/dotcom-ui-layout'

const adBannerHTML = getAdBanner(id) // => <iframe>...<iframe>

<Layout
  headerBefore={adBannerHTML}
  headerComponent={<CustomHeader />}
  headerAfter={adBannerHTML}
  footerComponent={<CustomFooter />}
/>