Creating a theme

A theme is simply a folder following a given structure.

theme
  |__ album.hbs    # main view
  |__ theme.less   # stylesheets
  |__ partials     # optional Handlebars partials
  |__ helpers      # optional JS helpers
  |__ public       # optional static files

It can be loaded using:

--theme-path file://path/to/theme

To submit a theme to be built-in, please raise an issue on Github here.

About build processes

Thumbsup doesn’t install any dependencies (or run any build steps) when loading a theme from disk. If your theme has a build process, you can either:

ask the user to clone your repo and build the theme locally
ideally, build it yourself and publish the result to npm

For example, your Git repo might look like:

|__ package.json
|__ src   # raw files
|__ dist  # result of the build process, typically git-ignored

Because npm publish will publish files relative to the root folder, you must include the following entry in package.json:

{
  "name": "my-thumbsup-theme",
  "thumbsup": {
    "themeRoot": "dist"
  }
}

album.hbs

This Handlebars template will be called for every album in the gallery, including the root album. It should typically render thumbnails for every entry in the album, as well as links to nested albums if applicable.

{{#with album}}
  <h1>{{title}}</h1>

  <h2>Nested albums</h2>
  {{#each albums}}
    <a href="{{relative url}}">{{title}}</a>
  {{/each}}

  <h2>Photos and videos</h2>
  {{#each files}}
    <a href="{{relative urls.large}}">{{filename}}</a>
  {{/each}}

{{#endwith}}

The data available to render is described on the data-model page. It’s also a good idea to read the thumbsup source-code to get familiar with any subtleties.

Like in the example above, make sure to use the built-in relative helper when using URLs.

theme.less

This is the entry point for all your theme’s styles.

h1 {
  color: #2070ee;
}

Some notes:

You can split your styles into multiple files using @import "other.less";
The generated CSS file is placed in the public folder (important for relative paths)

To make your theme configurable, you should use LESS variables for key elements like colors or sizes. For example:

@highlight: #17baef;

h1 {
  color: @highlight;
}

This will allow users to specify their own highlight color using:

thumbsup --theme-path ./your-theme --theme-style custom.less

// custom.less
@highlight: #ed124d;

settings

Just like you can expose LESS variables for customising styles, you can expose HBS variables for customising behaviour. The user will have to create a JSON file and specify --theme-settings file.json.

{
  "notify": true,
  "message": "hello"
}

You can then use these attributes like this:

<!-- At the root of your HBS template -->
{{#if settings.notify}} {{settings.message}} {{/if}}

<!-- Or somewhere within a loop -->
{{#each albums}}
   {{name}}
   {{#if @root.settings.notify}}
     {{@root.settings.message}}
   {{/if}}
{{/each}}

Don’t forget to document these settings in the theme’s README.

partials

Thumbsup automatically loads any .hbs partials in the partials folder. These are available in your view as {% raw %}{{>filename}}. You can pass data to a partial using the {{>filename arg1, arg2}} syntax.

theme/partials
  |__ caption.hbs

<!-- caption.hbs -->
<div>Photo caption</div>

<!-- album.hbs -->
{{> caption}}

helpers

Thumbsup automatically loads JavaScript helpers from the helpers folder. Each helper is available in the views using {{name}} for inline helpers, or {{#name}} for block helpers. You can pass data to a helper using the {{name arg1, arg2}} syntax.

theme/helpers
  |__ hello.js

// hello.js
module.exports = name => {
  return `hello ${name}`
}

<!-- album.hbs -->
<div>
  {{hello world}}
</div>

public

Every theme typically depends on extra static assets such as JavaScript files or images. The content of the public folder is copied as-is to the final gallery, on top of defaults assets bundled by thumbsup.

myTheme
  |__ album.hbs
  |__ public
     |__ cool.js
     |__ dragon.jpg

Themes