o-header-services

This header is for tools and services built by the Financial Times.

• Usage
• Markup
  • Title Section
  • Primary navigation
  • Core experience of the drawer
  • Primary navigation with drop down
  • Secondary navigation
  • Themes
  • Bleed header
• Sass
  • Customisation
• JavaScript
• Migration guide
• Contact
• Licence

Usage

Check out how to include Origami components in your project to get started with o-header-services.

Markup

An o-header-services header is divided into three main parts: title section (required), primary navigation (optional), and secondary navigation (optional). Each section is placed within a header element:

<header class="o-header-services" data-o-component="o-header-services">
    <!-- Markup specific to the needs of your product. Options detailed below. -->
</header>

Title Section

A title section is required for every header, and every title section must include a logo and a product title. The logo will default to the FT logo—if you are not using the build service you can customise it with the oHeaderServices() Sass mixin.

You can choose to include a product tagline to describe your product concisely, and there is space for extra content such as a 'Sign In' link in this section of the header, too.

Note: If there is a 'Sign in' option, it should be consistent with other FT products by aligning itself to the right and avoiding different wording such as 'Log in' or 'Login'.

For an example and markup, see the title-only header in the Origami Registry.

Primary Navigation

The primary navigation is an optional addition to the title section. It's most useful for high-level navigation.

This section of the header has specific behaviour, as it turns into a drawer at smaller viewport sizes (740px down). It requires the addition an extra element in the title section to support the hamburger button.

If you are using extra content (such as a 'Sign in' link), that will be pulled into the drawer, as well. (This behaviour can be supressed by adding the class .o-header-services__related-content--always-visible)

For an example and markup, see the primary navigation in the Origami Registry.

Core Experience Of The Drawer

Small screen users should still be able to access the contents of the drawer even if their browser doesn't cut the mustard or the JavaScript has failed to load. In this case we recommend you have the contents of the drawer at the bottom of the page in a footer that is only visible if the body has a .core class. In core experience the hamburger menu links to an anchor at the bottom of the page.

Primary Navigation With Drop Down

The primary navigation can also handle dropdown menus. These menus are hidden behind a button that lives beside the navigation item that it is pertinent to.

Drop down menus also get pulled into the drawer on smaller viewports.

For an example and markup, see the primary navigation with drop downs in the Origami Registry.

If copying markup from the above example, update the following attributes of dropdown navigation items:

• aria-label: include the title of your navigation item in the label for your dropdown button.
• aria-controls: link your dropdown button to the id of the ul navigation list which it controls

The following example shows the correct markup for a "Documentation" dropdown:

<li data-o-header-services-level="1">
    <a href>Documentation</a
    ><!--
    --><button
        class="o-header-services__drop-down-button"
        aria-controls="documentation-dropdown"
        aria-label="Toggle documentation dropdown menu"
    ></button>
    <ul
        id="documentation-dropdown"
        data-o-header-services-level="2"
        aria-hidden="true"
    >
        <!-- dropdown navigation list items -->
    </ul>
</li>

Secondary Navigation

The secondary navigation is also an optional addition to the header, but it makes more sense alongside the primary navigation, as it serves more complicated products.

It includes two sections of navigation: 'ancestors' and 'children'. The 'ancestor' section works in the form of a breadcrumb, and the children are relative to the ancestor.

At smaller viewports, it does not collapse into the drawer, but becomes scrollable instead.

For an example and markup, see the secondary navigation in the Origami Registry.

Themes

o-header-services offers theming for B2B or B2C products for FT.com products who use the core brand. They are designed to affect the title section and the primary navigation.

To add a theme to the header, add the appropriate class to the header element. For example, for B2B that would be:

+<header class='o-header-services o-header-services--b2b' data-o-component='o-header'>
-<header class='o-header-services' data-o-component='o-header'>
    <!-- Your header markup -->
</header>

For an example and markup, see the B2B and B2C headers in the Origami Registry.

Bleed Header

If your application requires a bleed header, you'll need to add the o-header-services--bleed variant to your header.

+<header class='o-header-services o-header-services--bleed' data-o-component='o-header'>
-<header class='o-header-services' data-o-component='o-header'>
    <!-- Your header markup -->
</header>

Sass

In order to output every type of o-header-services style, you'll need to include the following:

@import '@financial-times/o-header-services/main';

@include oHeaderServices();

You can be more selective about which types you would like to output, by using an $opts map. It accepts the following options:

types

• 'primary-nav'
• 'secondary-nav'
• 'bleed'
• 'b2b'
• 'b2c'

logo

• The logo image to show in the header. The image must come from an Origami image set. Specify the image set and image name as a string [imageset]:[image] e.g ftlogo-v1:origami. Defaults to the FT logo.

drawer-breakpoint

• The breakpoint to move the primary navigation into a drawer. We recommend a rem value or a layout size from o-grid e.g. 'M'. Defaults to the medium grid size 'M'.

To use a logo that is not the FT logo, the logo can be modified in one of two ways:

• By using a logo name from the logo image set (e.g. 'origami')
• By passing in a full url or data url that points at the SVG you want to use as a logo (e.g. 'https://www.example.com/logo.svg'). Bear in mind that you can also run your chosen SVG through the Image Service's URL Builder, which will optimise the image and provide a URL for it.

In this example we include only the styles for a primary navigation with the bleed modifier. We opt to use the Origami logo from the logo image set.

    @import '@financial-times/o-header-services/main';

    @include oHeaderServices($opts: (
        'types': ('primary-nav', 'bleed');
        'logo': 'origami'
    ));

    // Will output styles for a bleed header with a primary navigation and the Origami logo

Customisation

o-header-services provides the option to customise the whitelabel brand. If you are using this brand, you can modify brand-specific variables by overriding them in a map in oHeaderServicesCustomize.

$o-brand: whitelabel;
@import '@financial-times/o-header-services/main';

@include oHeaderServicesCustomize(
        (
            'nav-hover-background': hotpink
                // will apply to background colors on hover, where appropriate,,,,
        )
    ) @include oHeaderServices(
        $opts: (
            'types': (
                'primary-nav',
            ),
            'features': (
                'drop-down',
            ),
        )
    );

We recommend customising the following brand variables:

• top-text
• top-background
• nav-text
• nav-background
• nav-border
• nav-hover-background
• nav-underline-color
• arrow-icon-color
• arrow-icon-hover-color
• button-hover-color

In addition, the following brand variables may also be customised:

• text-hover-color
• drawer-background
• drawer-button-background
• drawer-text-hover-color
• drawer-nav-hover-background
• primary-nav-item-horizontal-padding

JavaScript

No code will run automatically unless you are using the Build Service. You must either construct an o-header-services object or fire an o.DOMContentLoaded event, which o-header-services listens for.

You'll need to set up your header declaratively, as the JavaScript for o-header-services does not construct it for you.

The JavaScript is responsible for generating the drawer and enabling scrolling on the secondary navigation. You can implement that with the following:

import oHeaderServices from '@financial-times/o-header-services';

oHeaderServices.init();

Migration guide

Contact

If you have any questions or comments about this component, or need help using it, please either raise an issue, visit #origami-support or email Origami Support.

Licence

This software is published by the Financial Times under the MIT licence.