Security News
RubyGems.org Adds New Maintainer Role
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
@financial-times/o-brand
Advanced tools
o-brand [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](#licence) =================
Tools to tailor Origami components for distinct use cases.
⚠️ Non-Origami projects must not depend on o-brand
directly.
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:
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.
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.
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
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 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'
)
);
example-background
.example-background
over background
.inverse
, b2b-inverse
.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.
oBrandDefine
ExampleThe 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'
)
));
}
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;
}
oBrandGet
returns null
if a variable is undefined. Sass removes css properties which are set to null
. This is a useful feature to conditionally output css properties for different variants.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
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.
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();
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.
This software is published by the Financial Times under the MIT licence.
FAQs
Tools to "brand" other Origami components.
The npm package @financial-times/o-brand receives a total of 791 weekly downloads. As such, @financial-times/o-brand popularity was classified as not popular.
We found that @financial-times/o-brand demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 10 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.
Security News
Research
Socket's threat research team has detected five malicious npm packages targeting Roblox developers, deploying malware to steal credentials and personal data.