Deployments: loading...

Themes

Services are fully theme-able through a simple and extensible theming engine.

Creating a Theme is a great way to customize the appearance of a Service.

Theming is ideal for user facing Services which are intended to be visited in the browser.

Creating a Service Theme

A Service Theme consists of two parts:

1. A single HTML file ( the Theme View )

2. An optional single JavaScript file ( the Theme Presenter )

Theme View




A HTML file which contains the layout of the Service. This file can also contain links to other assets such as images, CSS, and client-side JavaScript.

Theme Presenter




An optional JavaScript module which exports *one* method. When the Presenter is run on hook.io, it is given special properties to help perform server-side rendering of the Theme HTML.

Adding a Theme View

Adding HTML to a Theme is easy!

To add a Theme View, simply enabled the Theme option in the /admin page for the Hook.

Once a Theme HTML file is specified, the Service will use that file for rendering output.

Mustache Style Replacements

By default, a {{key.value}} style replacement will be performed on the Theme HTML using the completed Service object.

For example:

Loading...

When the Service runs, {{Service.output}} will be replaced with the outputted result of the Service.

To bypass these replacements, simply do not place any matching {{key.value}} tags in the Theme HTML.

For most themes, this simple replacement style should be sufficient. If additional server-side rendering is required, a Service Theme Presenter can be added.

Adding a Theme Presenter

The Service Theme Presenter is an optional JavaScript method which is performed server-side on the rendered Theme View before it's piped to the response. When the Presenter method is run on hook.io, it becomes a View class. This will give the Presenter special properties which allow for server-side rendering of the Theme View with JavaScript.

For example:

Loading...

For full documentation on using the $ object see: cheeriojs/cheerio

For seeing how the View class is implemented see: bigcompany/view

Important Tips

Separation of Concerns

Performing a lot of logic in the Presenter is not recommended. While it is possible to do a lot inside a Theme Presenter, it's always better to create new Services and pipe them together. The Presenter should only focus on taking in data and outputting HTML.

Custom Templating Engines

Want to use a custom templating engine? Not a problem! There are two methods in which custom templating engines can be implemented.

Method 1 ( Not Recommended ) - Require the custom templating engine directly in the Service Presenter and modify the contents of $.html() directly.

Method 2 ( Recommended ) - Create a new Service that is a generic processor for the custom templating engine. Once this Service is created, output from other Service's can be piped to it ( which will process the input using the custom templating engine ).

Client-side JavaScript

Any type of client-side JavaScript library can be used in the Theme HTML through the use of regular <script> tags.

Be Creative, Have Fun!

Themes are a great way to customize a Service's appearance. They can also easily be shared for use with other Services. If you make a theme, open a Pull Request! Your theme could very easily appear as a default theme option in the future.