Components

Components are the building blocks of primo sites. They're totally self-contained (unless there's a style or field they share with other components).

Creating a Component

1. Focus on a row on the page

2. Click 'Component' in the toolbar

3. Write code under the 'Code' tab, create fields under the 'Fields' tab

Component Code

HTML

• See an instant preview of what your code looks like

• Use [Handlebars](https://handlebarsjs.com/) to wire up your fields

• Use [Emmet](https://docs.emmet.io/abbreviations/syntax/) to quickly write HTML (e.g. div>div>h1.headingand press Tab)

CSS

• Styles are encapsulated (so if you only have one image tag in your component, you can safely select it with img.

• Nested styles are supported (using [postcss-nested](https://github.com/postcss/postcss-nested))

JavaScript

• You can import any JS modules by name with import module from 'module-name' , where module-name is the module's name on [npm](https://www.npmjs.com/). In the background, primo turns that into a request to [Skypack](https://skypack.dev/) that looks like

  import module from 'https://cdn.skypack.dev/module-name'.Skypack is a CDN that sends visitors pre-optimized packages.

• Additional values related to the component can be found under a variable named primo . primo contains three properties:

  • id is the component's unique ID. Typically used to select the component's node.

  • data contains the component's field values

  • fieldscontains the component's fields

Sometimes you'll need to call a function from your HTML

<button onclick="doSomething()">click</button>

To do so, you'll need to define the function globally from the component's JS

window.doSomething = function() {}

To avoid overwriting a global function (especially when reusing a component), create a global namespace using the component's ID.

window[primo.id] = {
    ...window[`component${primo.id}`] || {},
    doSomething: function() {}
}

And access it from the component's HTML

<button onclick="{{id}}.doSomething()">click</button>

Component fields

Fields let you easily change content inside HTML from the CMS side.

Create a field

1. From within the Component Editor, click the Fields tab

2. Add a field, selecting a field type based on the data type

   • Repeater: Lists

   • Group: Objects

   • Content: Markdown

   • Switch: Boolean

   • Text, Number, URL

3. Give the new field a label and an ID

   • Label: Labels the input field in the CMS

   • ID: Used from within the component's HTML to access the field value

Connect field to HTML

primo uses the [Handlebars](https://handlebarsjs.com/) compiler to build HTML from field values. Once you create a field, you can access their values from within the component HTML using the field's ID.

Some handlebars features like partials aren't supported yet

Repeater

<!-- This assumes we created and populated a repeater field with the ID of `nav` -->
{{#each nav}}
    <a href="{{url}}">{{title}}</a>
{{/each}}

Group

<div>
    <h3>{{teaser.title}}</p>
    <p>{{teaser.description}}</p>
</div>

Text

<h1>{{heading}}</h1>

Image

<img src="{{header.url}}" alt="{{header.alt}}" />

Number

<span>{{count}}</span>

Content

<!-- Since this field produces html, we'll need to wrap it in three brackets -->
<!-- 'primo-copy' gives the div the same copy styles as copy rows on the page -->
<div class="primo-copy">
    {{{ page_content }}}
</div>

Switch

{{#if show_contact}}
  <address>
    <a href="mailto:[e-mail]">[e-mail]</a><br>
    <a href="tel:[phone]">[phone]</a>
  </address>
{{else}}
  <h1>Unfortunately, we're currently unavailable for hire</h1>
{{/if}}

URL

<a href="{{detail_url}}">See More Details</a>

Link

<a href="{{cta.url}}">{{cta.title}}</a>