Quick Start

Quick start guide for theme developers

Table of contents

1. Create a Theme Folder
2. Folder Structur
3. The Configuration File
   1. Theme Configuration
   2. Theme Settings
4. Template Files
5. Base Template
6. Page Templates
7. Template Options
8. Section Templates
9. Using the Hello One Theme Editor
10. Asset Folder
11. Forms
12. E-Mails
13. Upload your Theme

---

Create a Theme Folder

You’ll need a folder to store the contents of your theme.

$ mkdir theme-name
$ cd theme-name

Folder Structur

Every theme consists at least of a package.json and a base template.

name	Description
/layouts/	folder of layout templates
/pages/	folder of page templates
/sections/	folder of section templates
/partials/	folder of partial templates
/emails/	folder of email templates
/assets/	assets of the theme (e.g. css & js files)
/packages.json	configuration file of the theme

The Configuration File

Start by creating a package.json file in the root of your project and add some basic information.

{
  "name": "@teraone/theme-name",
  "description": "example theme",
  "license": "MIT",
  "author": {
    "name": "unknown",
    "email": "pool@teraone.de",
    "url": "https://teraone.de"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/teraone/default-template"
  }
}

Theme Configuration

Settings and configuration of the theme are stored in the config object.

{
  "config": {
    "defaultPageTemplate": "pages/default.twig"
  }
}

The configuration above specifies the path of the default page template, which should be used to render a page.

Theme Settings

If you want the user to be able to customize your theme by setting some variables, you can use the themeSettings array.

{
  "config": {
    "themeSettings": [
      {
        "name": "textColor", // name of the setting
        "category": "colors", // used for categorisation
        "type": "select",
        "options": {
          "blue": "Blue Text",
          "green": "Green Text"
        }, // avaible options
        "value": "blue" // default value
      }
    ]
  }
}

The setting above enables the user to select the text color of the theme. The user is able to select one of the options. The default is blue.

Template Files

Hello One uses twig for rendering any template files of a theme.

More Information:

Twig Docs.

A template is just a simple .twig file. If the user should be able to set some options you should also create a corresponding .twig.json file.

Base Template

Page Templates

Templates for rendering a page are located in the /pages folder.

Let’s start by creating a simple page template.

/pages/default.twig

{% block content %}
<div>
  <h1>Page Template</h1>
</div>
{% endblock content %}

Template Options

If the user should be able to set some page specific settings, create an corresponding .twig.json file.

/pages/default.twig.json

[
  {
    "name": "color",
    "type": "select",
    "value": "blue",
    "options": ["blue", "red", "green"]
  }
]

The above option enables the user to select a color for every page and sets the default to blue.

You can now use the variable in the template file

{% block content %}
<div style="background-color: {{ color }}">
  <h1>Page Template</h1>
</div>
{% endblock content %}

Section Templates

Templates for rendering a section are located in the /sections folder. In order to render the sections of a page, we will insert the follwing code in our page template.

/pages/default.twig

<div>
  <h1>Page Template</h1>

  {% block sections %}
    {% for section in page.sections %}
      {% include section._template_name with section.data %}
    {% endfor %}
  {% endblock %}
</div>

Using the Hello One Theme Editor

Asset Folder

Additional files such as css, js or images are stored in the /assets folder. You can reference those files in you template files.

For instance, you can reference a styles.css in your template like this:

This will create a html <style> tag, which source is the styles.css file.

Forms

E-Mails

Upload your Theme