The “Create A New Origami Component” tutorial is split into eight parts and is intended to be followed sequentially from start to finish:
Usually the Origami team will own an Origami component which is used by multiple teams or groups, but anybody can create and share an Origami component.
In this tutorial we’ll build an Origami component. Our example component will display a “hello world” message and include a button which will count the number of times it was clicked. Visually the component will include multiple variations to suit reader facing (core brand) and internal (internal brand) projects. We’ll also discuss how to document and publish an Origami component so it is visible in the Origami Registry.
Before you get started, it’s a good idea to discuss your new component with the Origami team first. The team will be able to make sure there’s not an existing component or component proposal that fulfils the same purpose, and will be available to answer any questions.
To follow this tutorial ensure the following software is install on your machine:
In addition this tutorial introduces a number of tools and libraries such as git, Sass, sinon.js, etc. We do not cover these in depth but attempt to include brief descriptions and links to relevant documentation so that you may learn separately about the parts which are new to you.
If you have any questions please contact the Origami team to help make this tutorial better 😃. You can find the team on Slack in #origami-support.
The Origami Specification is deprecated, new components may diverge from its rules. However, some Origami tools and services continue to depend on parts of the deprecated specification so we will refer to relevant sections of the specification throughout this tutorial. Including for folder structure, code standards, documentation and more.
Origami components are developed using the Origami Build Tools (
obt) command line interface. To work on our component, install Origami Build Tools (
obt) on your machine by running this command in your terminal:
npm install -g origami-build-tools
This requires Node and npm, see the Origami Build Tools readme for more information.
To help us get started we can use the Origami Build Tools
init command. The
init command will ask a number of questions to determine what kind of component we’re building and generate a basic component for us to build from.
Before we run
obt init, let’s discuss some of those questions.
The first thing we will be asked is to decide a component name. Usually Origami components start with
o-, and only contain lowercase letters or hyphens. See the component naming convention for more details.
For this tutorial we will name our component
Origami components are categorised, and different rules of the specification may apply to different categories. Examples of categories include
layouts. See the full list of categories with description in the component category specification.
For this tutorial we will select the most common
Component brands facilitate component customisation. Brands change the appearance of component elements globally, e.g. change the appearance of all “primary” buttons, including where they are used by other components. Brands include
core (think, ft.com pink),
internal for internal tools and products, and
whitelabel for a striped-back un-opinionated style. Origami components may support one or more brands. We’ll discuss brands more later, for now select the
whitelabel brand when prompted by
All Origami components have a support status. For example a
maintained component means that “[the component is] not actively developed but reproducible bugs will be fixed promptly and work done where necessary to maintain compatibility with platforms and other projects”; an
experimental component means “the [component] is not ready for production use”. For a full list a support statuses and their meaning see the support status section of the specification. It is sometimes a good idea to release a new component as
experimental for a trial period to gather feedback from users, so select
experimental for now.
As well as a support status, the
obt init command will ask for a support email address and slack channel. This will help identify your team as owners of the component. When the component is published a message will display in the component registry letting potential users know that support is not guaranteed by the Origami team, and that they should contact your team before using the component.
This tutorial won’t expand on other questions asked by the
obt init command, like what the component description and keywords are. Please feel free to contact the Origami team if you have any questions during this step.
obt init and answer the questions as above. You should see a directory which contains component boilerplate (commonly shared component code we can build on top of).
The structure of our component now looks something like this. In the next section we will start developing our component, and in the process discuss what is in each directory.
o-example ├── .eslintrc.js ├── .dependabot │ └── config.yml ├── .github │ ├── CODEOWNERS │ ├── ISSUE_TEMPLATE.md │ └── workflows │ └── [a number of .yml files] ├── .gitignore ├── .stylelintrc.js ├── README.md ├── demos │ └── src │ ├── demo.js │ ├── demo.mustache │ ├── demo.scss │ └── pa11y.mustache ├── main.js ├── main.scss ├── origami.json ├── package.json ├── src │ ├── js │ │ └── example.js │ └── scss │ ├── _brand.scss │ └── _variables.scss └── test ├── js │ ├── example.test.js │ └── helpers │ └── fixtures.js └── scss ├── _main.test.scss └── index.test.scss
Now we have a basic component to work from we can start developing!
First we need to install any component dependencies by running the Origami Build Tools
Then we can use the
dev) command to start working on the component. The
dev command creates a server for us to preview our component in the browser. And whenever we make any change to the source code the component will be rebuilt, which we will be able to see by refreshing our browser:
Opening the link output by the develop command, for example
localhost:8999, lists the built component assets in the browser (HTML, JS, and CSS files).
Clicking the HTML file
demo.html will show a blank page. In the next section we will update our component with new HTML and content.
Origami components are not built to work with any particular framework in mind. This is because product developers may choose to use any technology stack to build their application, and it’s important that they not be forced to choose a particular one in order to use Origami components. With that in mind Origami components are not written in a templating language or a framework but in plain HTML.
Therefore to include component HTML Origami users copy and paste component HTML from the readme
README.md or interactive component demos which are presented in the Origami registry.
We will use the demos as previews for local development as well as presenting to users in the Origami registry.
The templates for demos are in the
demos directory and written in mustache. In the demos directory, you should see an example demo
demos/src/demo.mustache (we’ll revisit the other files later). Open
demos/src/demo.mustache in your editor and you should see something which looks like this (assuming a component name of
<!-- demos/src/demo.mustache --> <div class="o-example" data-o-component="o-example"></div>
div element is our component markup. So we can see something in out demo, add some content within the
<!-- demos/src/demo.mustache --> -<div class="o-example" data-o-component="o-example"></div> +<div class="o-example" data-o-component="o-example"> + Hello world, I am a component named o-example! +</div>
obt dev command which we run earlier will detect that you have updated
demos/src/demo.mustache and compile it to
demos/local/demo.html. Now if you refresh your browser you should see the content we just added to the demo.
div tag in our demo may be any HTML tag provided there is a
data-o-component attribute. The
In part one we learnt:
initcommand to generate a component to work from when developing a new component.
gitsource control and are stored remotely on Github.
Now we know how to update our component markup, in part two we will style our component. Continue to part two.