Using the Origami Build Service is the quickest way of getting Origami components to work in your product. The service bundles together the CSS and the JavaScript for all Origami components on a central server. You can then access specific component bundles by using a link or script tag.
Below is a step by step walkthrough for building a page for an article about fruit, with FT.com colors and fonts, and we’ll include a few Origami components to do so.
For this tutorial, we recommend you follow along by setting up your project in CodePen, or JSBin.
There are usually three three parts to an Origami component; HTML, CSS and JavaScript. We’re going implement one at a time to put together our page.
Let’s begin.
We’ll need to start with some boilerplate markup.
There are three things we want on a FT-like article page: a grid, consistent typography and a background color.
In order to get that, we’ll need the foundation of our HTML to look like this:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>My First Origami Page</title>
</head>
<body class="o-colors-page-background">
<div class="o-grid-container o-typography-wrapper">
<div class="o-grid-row" data-o-grid-colspan="center 8">
</div>
</div>
</body>
</html>You won’t see anything yet, but the classes and the data attribute will be working together to center our content across a span of 8 columns when we add the CSS to our page.
For now, let’s finish putting together the content of our page.
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.
First, we’re going to add some content for our article, so lets add a heading and some great information about fruit in our o-grid-row:
<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.
All of the markup that comes with an Origami component is available on the components’ page in Storybook.
We can find the markup for the striped variation of o-table in the registry, and copy that HTML into our work from there.
Now we come to the second step in putting our page together, and a big part of what makes the Origami Build Service a quick solution.
The Origami Build Service will perform a number of build steps to compile and bundle up the SCSS that most Origami component styles are written in. Since it is all bundled for us to pick and choose from, let’s begin by styling our grid. This means we’ll have to add a link tag to our <head> tag.
<link rel="stylesheet" href="https://www.ft.com/__origami/service/build/v3/bundles/css?components=o-grid@^6.0.0&brand=core&system_code=$$$-no-bizops-system-code-$$$"/>The href attribute references the Origami Build Service endpoint that serves a CSS bundle. The most important parts of this url are the components, brand, and system_code query parameters.
The system code is the bizops system code for the FT system which is making the Origami build service request. A valid system code is important for usage attribution and technical support, but for the purposes of this tutorial we’ll use a placeholder value $$$-no-bizops-system-code-$$$.
The component query parameter is used to specify what components and which version we want to include. In the above we request o-grid@^6.0.0.
The brand query parameter will affect the appearance of included components, its value depends on what kind of project we are building – more on this later.
Now, you should see all of your content snap to the center of the page. This means that we've successfully fetched the `o-grid` CSS bundle from the Origami Build Service.But we also want to style our content and our table, and fetch the right color from our color palette.
It is important to highlight that you only need one link tag per page, regardless of how many components you are using. The Origami Build Service can include more than one component in the bundle we ask for, meaning that we can add multiple components to the same URL. This avoids duplicating the CSS that is shared between components, because we are only downloading it all once.
So in order to add the styling for all of our other components, we need to add a few components (and versions!) to the query parameter of our original url:
<link rel="stylesheet" href="https://www.ft.com/__origami/service/build/v3/bundles/css?components=o-grid@^6.0.0,o-colors@^6.0.8,o-typography@^7.0.2,o-table@^9.0.2&brand=core&system_code=$$$-no-bizops-system-code-$$$"/>And now, when we look at our page, we should have a styled table, different typography and a type of grid in place.
Public facing, ft.com product are known as “core brand” products, by setting the brand query parameter to “core” we are requesting that style of component. But Origami components offer tailored support for other contexts with component branding.
For example we could set the brand to internal.
<link rel="stylesheet" href="https://www.ft.com/__origami/service/build/v3/bundles/css?components=o-grid@^6.0.0,o-colors@^6.0.8,o-typography@^7.0.2,o-table@^9.0.2&brand=internal&system_code=$$$-no-bizops-system-code-$$$"/>As the colour palette for the “internal” brand does not include “paper” (FT pink), the background we set with o-colors classes has changed, as have the stripes of o-table. Our typography set with o-typography classes has also changed.
Now undo that by setting &brand=core again.
For a list of supported brands and their purpose see the component customisation page.
There is one more step, before our page is entirely functional. Not all Origami components use JavaScript. In fact, of the ones we’ve used in this example, only o-table does.
So our final step involves providing our table with the ability to sort its content. Much like the link tag for the CSS, we fetch JavaScript bundles from a Build Service endpoint, through a script tag. And, also like the url for the link tag, the script src expects a query parameter, which can also be more than one component.
In addition to the o-table component we also request o-autoinit, which will automatically find and initialise all our requested components on the page when it’s ready.
For now though, let’s add the following to our <head>:
<script src="https://www.ft.com/__origami/service/build/v3/bundles/js?components=o-table@^9.0.2,o-autoinit@^3.0.0&system_code=$$$-no-bizops-system-code-$$$" defer></script>Now you can scroll down to your table, and sort fruit alphabetically by name or characteristic, or numerically by popularity.
We’ve stepped through a basic set up of components with the Origami Build Service, and these are the fundamental steps for any component you might want to use within your product.
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: