Themes

Themes defined the global behavior of a website, including the global “chrome” that makes up the header, footer, and potential sidebars of a website. Themes should include a global stylesheet as a resource bundle along with other common elements of the website.

Creating and Distributing Themes

Each Theme is just a collection of files in a directory that Emissary knows to scan. This can be a directory in the local filesystem, or a remote Git repository that is registered in the server configuration. Emissary will recognize a directory as a theme if it contains a theme.json (or theme.hjson) definition file (as opposed to a template.json file or a widget.json file).

Theme File Format

The default theme bundled with Emissary is a good example of this structure.

Property	Description
themeId	Unique name used to identify this theme
label	Human-friendly label, displayed in theme lists
description	Human-friendly description, displayed in theme lists
rank	integer sort order for ordering this theme in lists
extends	Array of zero or more Unique IDs that this theme extends
bundles	Describes resource bundles that are packaged with this Template
startupStreams	Defines initial streams (and content) to add when this Theme first is selected
startupGroups	Defines initial user groups to add when this Theme first is selected.
startupFolders	Defines initial folders to put into every new user’s inbox.
defaultInbox	Template to use when displaying user’s inboxes. Defaults to “user-inbox”
defaultOutbox	Template to use when displaying user’s outboxes. Defaults to “user-outbox”
isVisible	If TRUE, this theme is displayed in selection lists.

Here is an example from Emissary’s default theme

{
	"themeId": "default",
	"extends":["global"],
	"isVisible":true,
	"category":"General",
	"label": "Minimus",
	"description": "Clean, top nav theme for general purpose websites.",
	"rank": 0,
	"bundles": {
		"stylesheet": {
			"content-type":"text/css"
		},
		"javascript": {
			"content-type":"text/javascript"
		},
		"hyperscript": {
			"content-type":"text/hyperscript"
		},
		"registration": {
			"content-type":"text/hyperscript"
		}
	},
	"startupStreams": [
		{templateId:"article-editorjs", token:"home", label:"Welcome!", rank:1},
		{templateId:"article-markdown", token:"about", label:"About Maximus", rank:2},
		{templateId:"article-markdown", token:"join-the-team", label:"Join the Team", rank:3}
	],
	"startupGroups":[
		{"label":"Publishers"},
		{"label":"Subscribers"}
	],
	"defaultFolders: [
		{"label":"Friends"},
		{"label":"Family"},
		{"label":"Colleagues"}
	]
}

Required HTML Files

The following HTML templates MUST be included in order for your Theme to function.

Filename	Description
page.html	Defines the outer borders (or “chrome”) of the website.
register.html	Standalone page displayed when new users sign up for an account
reset-code.html	Standalone page displayed when users request a password reset
reset-confirm.html	Standalone page displayed when users confirm their password reset code
reset-password.html	Standalone page displayed when users enter their new password
signin.html	Standalone page displayed when users sign in to the website

Extending Existing Themes

Many themes share common elements, for example: the register and signin workflows should be pretty consistent, regardless of the rest of your website chrome. In this case, you can use the “extends” element to name one or more existing themes that you want to extend. This applies to all settings, templates, bundles, and resources.

When a file or resource is requested, if it is contained in the current theme then that value will be used. If not, Emissary searches for it in each of the themes named by the “extends” element in order. The first result found will be returned. This makes it straightforward for you to reuse elements you’ve already defined in other themes without having to maintain multiple copies of the same resource.

All of the default themes in Emissary use this mechanism to inherit from the global theme. This is an easy way for you to jumpstart your own theme development, but it is not required. You can also make your own theme from scratch, or inherit from your own base theme definitions.