Origami Frontend Components & Services

Readme: o-brand

o-brand is experimental. This component is not guaranteed to be ready for production use, and the API should be considered unstable.

Tools to tailor Origami components for distinct use cases.

⚠️ Non-Origami projects must not depend on o-brand directly.

Terms

Brand

A brand represents an environment which requires components to offer a distinct appearance or unique functionality. A brand may be thought of as a theme, but branded components may provide unique features as well as a distinct appearance.

Brands include:

Variant

A variant is an addition or modification to a component within a given brand. Variants must be optional and build upon a fully functional component. E.g. A button component may have an "inverse" variant, a "big" variant, etc. A header component may have a "subnav" variant, a "sticky" variant, etc.

Sass

Mixins within o-brand help configure components to support brands. There is no configuration in o-brand. It provides the mechanisms for components to apply their own brand support. Projects which consume branded Origami components may choose a brand by setting the $o-brand variable.

The following mixins and functions help brand a component.

oBrandGetCurrentBrand

This function will return the brand defined at a product level.

If $o-brand has been defined by a project oBrandGetCurrentBrand will return that value.

$o-brand: internal // Defined in the product using branded Origami components.

$chosen-brand: oBrandGetCurrentBrand(); // internal

If it has not yet been defined, it will provide a default brand (master).

//$o-brand is undefined

$chosen-brand: oBrandGetCurrentBrand(); // master

oBrandDefine

Components are individually responsible for defining the configuration for each brand they support. In order to add configuration for a new brand, use the mixin oBrandDefine.

Where $component is the component's name; $brand is one of "master", "internal", or "whitelabel"; and $config is a map which comprises of variables and supported variants:

@if oBrandGetCurrentBrand() == 'master' {
    @include oBrandDefine($component, $brand, $config);
}

Note: oBrandDefine should be used in conjunction with oBrandGetCurrentBrand, to define only the requested brand.

Brand Variables

Brand variables configure a component for a brand. E.g. a component o-example might define a variable example-background to configure its background colour.

$variables: (
    example-background: 'paper'
);

A nested map configures a variant, which may provide new variables or a different value for an existing variable. E.g. for an inverse variant which has a different value for the variable example-background:

$variables: (
    example-background: 'paper',
    'inverse': (
        example-background: 'slate'
    )
);

Supported Variants

To indicate a brand should support a variant, add the variant name to the supports-variants list.

E.g. To configure support for "inverse" and "b2b" variants:

$supports-variants: (
    'inverse',
    'b2b'
);

Variant support can then be checked using oBrandSupportsVariant.

A Complete oBrandDefine Example

The below example defines a master brand for the component o-example. We define four variables including example-background, but we provide a different example-background value for the inverse and b2b variants. Using the supports-variants list we explicitly state the master brand supports both of these variants.

@if oBrandGetCurrentBrand() == 'master' {
    @include oBrandDefine('o-example', 'master', (
        'variables': (
            example-background: 'paper',
            example-border-width: 1px,
            example-border-type: solid,
            example-border-type: grey,
            'inverse': (
                example-background: 'slate'
            )
            'b2b': (
                example-background: 'lightblue'
            )
        ),
        'supports-variants': (
            'inverse',
            'b2b'
        )
    ));
}

oBrandGet

Use oBrandGet to retrieve a brand variable. First create a private, component-specifc function which calls oBrandGet, e.g. for a component o-example, create _oExampleGet:

/// Helper for `o-brand` function.
/// @access private
@function _oExampleGet($variables, $from: null) {
    @return oBrandGet($component: 'o-example', $variables: $variables, $from: $from);
}

Your new component specifc function _oExampleGet can then be used to fetch variables. E.g. building on the oBrandDefine example:

.o-example {
    background: _oExampleGet($variables: 'example-background'); // background: paper;
}

It is possible to request multiple variables:

.o-example {
    border: _oExampleGet($variables: ('example-border-width', 'example-border-type', 'example-border-color')); // border: 1px solid grey;
}

To retrieve a variable for a variant use the $from argument:

.o-example--inverse {
    background: _oExampleGet($variables: 'example-background', $from: 'inverse'); // background: slate;
}

The $from argument also accepts a custom variant:

$custom-variant: (
    'example-background': 'hotpink',
    'example-border-width', '2px'
);

.o-example--custom {
    background: _oExampleGet($variables: 'example-background', $from: $custom-variant); // background: hotpink;
    border-width: _oExampleGet($variables: 'example-border-width', $from: $custom-variant); // border-width: 2px;
}

oBrandSupportsVariant

To check if a brand supports a variant call oBrandSupportsVariant. First create a private, component-specifc function which wraps oBrandSupportsVariant, e.g. for a component o-example, create _oExampleSupports:

/// Helper for `o-brand` function.
/// @access private
@function _oExampleSupports($variant) {
    @return oBrandSupportsVariant($component: 'o-example', $variant: $variant);
}

Then call your new function _oExampleSupports to determine whether to output CSS for a variant or not. E.g. to only output the inverse variant if the brand supports it:

@if _oExampleSupports($variant: 'inverse') {
    .o-example--inverse {
        background: _oExampleGet($variables: 'example-background', $from: 'inverse'); // background: slate;
    }
}

oBrandCustomize

oBrandCustomize allows existing brand variables to be modified, so long as those variables have been defined with oBrandDefine. This customisation is component-specific, so a branded component must wrap oBrandCustomize within a mixin of its own, as o-brand must not be used directly outside Origami components.

Currently only the whitelabel brand is allowed to be customised in this way.

Example Component (o-example):

/// Create a component-specific mixin to wrap `oBrandCustomize`.
@mixin oExampleCustomize($variables) {
    @include oBrandCustomize('o-example', $variables);
}

// Define the whitelabel brand for the component.
@if oBrandGetCurrentBrand() == 'whitelabel' {
    @include oBrandDefine('o-example', 'whitelabel', (
        'variables': (
            example-background: white,
            example-color: black,
        ),
        'supports-variants': ()
    ));
}

Example Project:

$o-brand: 'whitelabel';
@import 'o-table/main';

// Customise the example component.
// Here we change the variable "example-background" from "white" to "lightblue".
// The "example-color" variable has not been customised so remains "black".
@include oExampleCustomize((
    example-background: lightblue
));

// Output the example component CSS.
@include oExample();

Contact

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


Licence

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

Switch component view

GitHub Repository

Install o-brand

If using the Build Service, add o-brand@^3.2.4 to your link tag.

If running a Manual Build, run bower install --save "o-brand@^3.2.4".

Help & Support

o-brand is maintained directly by the Origami team. If you have any questions about o-brand or Origami in general, we are happy to help. 😊

Slack: #ft-origami
Email: origami.support@ft.com

Feedback / Issues

To report a bug or request features please create an issue on Github. For support or general feedback please get in touch 😊

Slack: #ft-origami
Email: origami.support@ft.com