Origami Frontend Components & Services

The manual build process

Adding Origami components to your product through the manual build process gives you more granular control over their styling and their behaviour. It requires more set up though, so we’re providing an in-depth walkthrough for building a page for an article about fruit.

This tutorial assumes that:

Setting up your sandbox

We will need a folder structure for our page. So let’s begin by creating a new directory to work in.

mkdir o-fruit-demo && cd o-fruit-demo

Eventually, we’ll have a folder structure that separates our HTML, CSS, JavaScript, dependencies and assets. Let’s start by adding an index.html to the root of our new project with some boilerplate HTML:

<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="utf-8">
		<title>My First Origami Project</title>

		<link rel="stylesheet" href="public/main.css">
		<script async src="public/main.js"></script>
	</head>
	<body>

	</body>
</html>

The link and the script tags are pointing at our public assets, which will be available once we have performed a build step and compiled our source code. That source code will be written in plain Javascript and in SCSS, and each of those will be in their individual folders in our project:

mkdir src && touch src/main.js src/main.scss

Now we’re ready to start adding components to our page.

Component HTML

With the exception of JavaScript-only components, all of Origami’s components rely on markup. This markup, combined with the styling and the functionality, is what determines how a component will look and behave on a page. So before we can style anything, we’ll need to add some component markup to our page.

o-grid will determine how our content sits on our page. To begin, let’s add the following to the <body> in our index.html:

<div class="o-grid-container">
	<div class="o-grid-row o-typography-wrapper" data-o-grid-colspan="center 8">
	</div>
</div>

We want to share some fruit facts, so let’s add some content to that inner div:

<h1>Funky Fruit Facts</h1>
<h2>Durian</h2>
<p>Due to its overpowering smell, durian has been banned on many types of public transport across Thailand, Japan and Hong Kong. In Singapore, the fruit is banned across all types of public transportation and even taxis have signs to let you know they refuse to carry passengers transporting the smelly fruit.</p>
<h2>Dragonfruit</h2>
<p>The cactus flower that produces dragon fruit survives only a single night. It blooms in the evening, ready for pollination by bats and moths, and wilts the very next day. The very brief pollination period, however, is sufficient for the plant to bear fruits.</p>
<h2>Naseberry, aka Sapodilla</h2>
<p>The sapodilla tree supplies the building blocks for a number of products utilized by humans.  Long ago, the Mayas and Aztecs would boil its ‘chicle’ sap, mold it into thick blocks and cut them into small pieces to chew. They were making the first chewing gum!</p>

Finally, we want to showcase the popularity of each fruit in a sortable table. To do that, we’re going to use the o-table component.

This is a good time to highlight how the manual build process provides more flexibility, because we don’t need to include all the table variations provided by Origami - we can include the minimum features we need.

Let’s head over to the striped variation of o-table in the registry, and copy that HTML in under our content.

Bower & the Origami Registry

Now that we have set up the scaffolding for our page, we need to install those components so we can access their respective styles and functionalities.

All Origami-compliant components are available for installation via Bower. They live in the Origami Registry, and are made visible to Bower through the Origami Bower Registry.

This means that, in order for Bower to find the components we will be installing, we need to tell it where to look. For that, we use a .bowerrc file in the root of our directory:

{
	"registry": {
		"search": [
			"https://origami-bower-registry.ft.com",
			"https://registry.bower.io"
		]
	}
}

Next, we need to install our components as direct dependencies, because they are crucial to our page. We will opt to install them through the command line, and save them to a bower.json. For the scope of this tutorial, all that needs to be in that file right now is:

{
	"name": "o-fruit-demo"
}

Now we need to install our components, and we can save them all to our file by running:

bower i --save o-grid o-typography o-colors o-table

And your bower.json should now look something like this:

{
  "name": "o-fruit-demo",
  "dependencies": {
    "o-grid": "^4.5.1",
    "o-typography": "^5.10.1",
    "o-colors": "^4.8.5",
    "o-table": "^7.2.1"
  }
}

The Build Step

So that we can see our progress as we build the page, now is the time to implement our build step. For that, we are going to use the Origami Build Tools. As long as you have Node.js installed, you can run:

npx origami-build-tools [command]

There are many commands that the Origami Build Tools provide, but the one we will be focussing on today is build.

We want to compile our source code (which we don’t have yet) into a public folder that our HTML can read. We will need to pass the npx origami-build-tools build command a few arguments to do so:

Altogether, the command looks like this:

npx origami-build-tools build --build-folder="./public/" --sass="./src/main.scss" --js="./src/main.js" --watch

You can leave that running in the background, and open your index.html in a browser to see the styling changes we’ll be making in the next step.

Component Styling

Now we can begin styling our components. For this, all of our work is going to happen in our src/main.scss file.

All Origami components have a silent mode. When silent mode is ‘on’ (or true), the components’ SCSS will not be compiled — instead, only its mixins and functions will be available. In this tutorial, we are going to use a mix of ‘on’ and ‘off’ silent modes for components.

Silent Mode: Off

Let’s start off with o-grid. It is likely we’ll want most of the features that o-grid provides, so we’ll include it with silent mode switched off (or false). For now, all we need in our main.scss is:

$o-grid-is-silent: false;
@import 'o-grid/main';

If we open our index.html in a browser window, we’ll see that our content is now centred on the page. This is because of the classes that we added to our outside div at the very beginning. Since we’ve requested all of the o-grid styling, the styling applies to those classes as soon as we include the component’s SCSS.

We added an o-typography class to our inner div at the beginning of the tutorial, as well. It will apply styling just as the grid did, so the next—unguided—step, is for you to implement o-typography in the same way we implemented o-grid above.

Look at your index.html in the browser when you’re done - your headings and paragraphs should have received font families and styling of their own.

Silent Mode: On

We’ll be using o-colors, which has a wide variety of colours in its palette. As with every other component, the o-colors silent mode variable is set to true by default to prevent outputting more CSS than we really need. And since we don’t need all of the colours in the palette for this page, we will leave the silent mode for the component as is.

o-colors comes with predefined use cases. These use cases are not a valid hex code but they refer to the name of a colour within our brand palette. This means we’ll need to use two mixins to get the right colour for our page:

@import 'o-colors/main';

body {
	background-color: oColorsGetPaletteColor(oColorsGetUseCase(page, background));
}

As soon as your build has completed, visit your index.html again. You should have the pink that is characteristic of the FT as a background colour.

We’re going to get a little more specific with o-table since we’re after a particular variation.

We only want the base styling of a table, and some stripes to tell each row apart:

@import 'o-table/main';
@include oTable($opts: ('stripes'));

With this, we’ve added all of the styling we needed for our page, so let’s take another look at our index.html and admire our handywork.

Selecting A Brand

By default Origami components are tailored for public facing, ft.com products – these are known as “master brand” products. But Origami components offer tailored support for other contexts with component branding.

To choose a brand other than the default “master” brand, set the $o-brand SCSS variable at the start of your root SCSS file, before importing any components.

To see this in action we can set our brand to “internal”:

$o-brand: "internal"; // Set brand before anything else.
@import 'o-colors/main';
//...

As the colour palette for the “internal” brand does not include “paper” (FT pink), the background we set with o-colors and the stripes of o-table have changed. The typography of our project has also changed.

Now we will undo that by deleting $o-brand: "internal";, making our project default to the “master” brand again.

For a list of supported brands and their purpose see component brands.

Component Functionality

The final step in our tutorial involves adding JavaScript to our components, and we’ll be doing all of that work in src/main.js.

Not all Origami components use JavaScript. For example, of the components we have installed today, only o-table requires it.

Origami components listen for a custom event named o.DOMContentLoaded in order to initialise. We’ll need to add that to our project so that the o-table JavaScript can kick in.

We’ll need to add this to our file:

require('o-table');

// Wait until the page has loaded
if (document.readyState === 'interactive' || document.readyState === 'complete') {
	document.dispatchEvent(new CustomEvent('o.DOMContentLoaded'));
}

document.addEventListener('DOMContentLoaded', function() {
	// Dispatch a custom event that will tell all required modules to initialise
	document.dispatchEvent(new CustomEvent('o.DOMContentLoaded'));
});

Now you can sort fruit alphabetically by name or characteristic, or numerically by popularity.

Next steps

We’ve given you an overview of how to build components manually. There is more information about each component, its variations, its individual behaviour and configuration in the Origami Registry. Here we’ve covered the fundamentals, but there are a few more aspects to the development of a product with Origami components that are important for compatibility and consistency, and we encourage you to read more about them: