Creating a Custom HTML Theme

If you want even more control over your website's design, you can create your own custom HTML theme by following the guide below. This guide is for advanced users who have a working knowledge of hand-coding HTML and CSS. If that's you, then by all means continue with the guide, if not then you might want to stick with the built in editing features of the Themes app.

Things To Know

If you want to take advantage of advanced features, here are other formats you should know before you start:

Getting Started

The best way to get started is to familiarize yourself with what customizations are already possible directly through the default UI of the Themes app, if you haven't already. It's important to have a good understanding of how the Themes app works because there are some unique concepts that you will have to keep in mind when building a custom HTML theme. Also open up a SnapPages website in your browser and view the source code for the page so you can get a sense for how it is structured.

After you feel comfortable with how the Themes app works, use the link below to install a sample custom HTML theme for you to refer back to while reading the documentation. After it's installed we suggest opening up this custom theme in the Themes app and keeping it open in a seperate browser tab while you learn.

Install custom theme >

Theme Files

Custom SnapPages themes are primarily controlled by three different files that allow you to override default theme settings or create new ones. If you have a Developer account, each of these files can be manually edited directly in the Themes app. Read the guide below to better understand how they work.

HTML

This file forms the basic HTML structure of your custom theme. It can contain basic HTML structure elements as well as special Theme Variables that allow it to work with the SnapPages platform. Some of these variables are required for a theme to be considered valid and some are not so you will need to read the guide on template variables to learn more. Learn more >

CSS

Much of the theme's visual style is actually controlled by user defined settings in the theme's config file. However you can override any style or add new ones by adding CSS/LESS to the themes style.css file. If you are not familiar with LESS it is highly recommended that get a basic understanding of what it is if you want to take advantage of some of the advanced functionality it allows.

Config

If you are planning on distributing your theme to multiple users and you want to allow them to easily modify certain aspects of it without using any code, this is how you can achieve that. By editing the theme's custom JSON configuration file, you can add many powerful options to your theme that will allow any user to make simple modifications to a theme using basic UI controls in the Themes app. Learn more >

HTML

The HTML theme file contains a combination of HTML structural elements, as well as Theme Variables. It's important that you know how both of these work together if you want your code to be valid. There are certain HTML elements and Theme Variables must always be present, and there are some that are optional.

What are Theme Variables?

Theme Variables are code snippets that are used to insert special SnapPages specific code. For instance the "{sp.content}" variable will insert the user generated content for the current web page. Learn more >

Sample Theme HTML:

<html>
	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
	{sp.top}
	</head>
	<body>
		<div id="wrapper">
			<div id="sp-header">
				{sp.header-canvas}
				{sp.navigation-bar}
			</div>
			<div id="sp-content">
				{sp.content}
			</div>
			<div id="sp-footer">
				{sp.footer-menu}
			</div>
		</div>
	{sp.bottom}
	</body>
</html>

HTML Theme Elements

There are certain HTML elements that are required for the theme to function properly with the Themes app. Some elements can be removed, and the Themes app will just remove functionality related to that element, however some can not be removed all or the theme will become invalid. Here is a list of the specific theme elements and what they do:
Element ID Description
#wrapper This element is required. All theme HTML elements should be contained inside of it.
#sp-header Used to contain all the elements that go into the "header" section at the top of the theme. This typically includes the Navigation Bar, and any extra header elements like a logo image. It is not required for a valid theme, but if it is not present, none of the "Header" related functionality will function in the Themes app.
#sp-header-canvas This element is dynamically added using the {sp.header-canvas} variable. It will contain all header elements including positional text and image elements.
#sp-navigation This element is dynamically added using the {sp.navigation-bar} or {sp.navigation-links} variables. It is a wrapper element for the other navigation elements.
#sp-navigation-bar This element is dynamically added using the {sp.navigation-bar} variable. It contains the graphics for the user customizable navigation bar.
#sp-navigation-links This element is dynamically added using the {sp.navigation-bar} or {sp.navigation-links} variables. It contains an unordered list for the anchor tags that create the websites main navigation links.
#sp-content Used to contain the main content for a page. The {sp.content} variable should always be placed inside this element which will load all the web blocks and user generated content. It is not required for a valid theme, but if it is not present, none of the "Content" related functionality will function in the Themes app.
#content This element is dynamically added using the {sp.content} variable.
#grid This element is dynamically added using the {sp.content} variable.
#sp-footer The {sp.footer-menu} variable should always be placed inside this element which will load footer menu inside of it. It is not required for a valid theme, but if it is not present, none of the "Footer" related functionality will function in the Themes app.

Can I use Javascript?

The HTML file can also contain custom Javascript, but do not try to import the jQuery library because it is loaded by default for all SnapPages themes already. If the Javascript code has errors in it, or conflicts with the Theme app's existing code, it could cause the editor to stop funcitoning properly.

Theme Variables

Theme Variables are the key to getting your custom HTML theme work inside the SnapPages platform. They are placeholders that dynamically add user generated content and SnapPages specific scripts into the theme when a web page is loaded. When used correctly they can be a powerful way to customize your theme.

You can reference the HTML of the custom sample theme to get a better understanding of how these work. Also refer to the table below to see specifically what each theme variable does and which ones are required:
Theme Variable Description
{sp.top} This variable is required. It is used to insert almost all the SnapPages code that is needed for a website to function properly and it must always be placed in the "<head>" element of the page.
{sp.content} This variable is required. All of the user generated content for a page will be inserted wherever this variable appears.
{sp.bottom} This variable is required. Any specific user generated code that must appear at the bottom of a page will be inserted with this variable. It must always be placed right before the closing body tag in the HTML.
{sp.header-canvas} The header canvas is an area generally placed at the top of the theme that allows users to add custom text and image elements inside a specific area. This is a great way to allow users to add their own logo or company name to the theme.
{sp.navigation-bar} The navigation bar is a customizable horizontal rectangle that will be displayed with the navigation links appearing on top of it. If you choose to add this to your theme, it will automatically pull in the same data that {sp.navigation-links} would so you don't need to add both. This variable should always be placed inside a #sp-header element.
{sp.navigation-links} This variable will insert an unordered list of all the main navigation links for the users website. This variable is optional but if you want to distribute your theme to multiple users you should always use this instead of hard-coding a navigation menu.
{sp.footer-menu} If you want users to be able to use the Themes app's built in functions for editing a footer menu, place this variable in the footer section of the theme.

LESS Variables

There are a few LESS variables that you can incorporate with your CSS that you should be aware of. Refer to the table below to learn more about what they do:
LESS Variable Description
@primaryColor This variable can be used to replace any color value with the themes user selected primary color.
@secondaryColor This variable can be used to replace any color value with the themes user selected secondary color.
@theme_width This variable can be used to keep the width of an element in sync with the width of the entire theme.
@theme_width This variable can be used to keep the width of an element in sync with the width of the content section of the theme.

Custom Configuration Options

When creating a custom HTML theme, you can add user customizable options that will allow any user to make simple modifications to a theme using basic UI controls in the Themes app. These options are defined inside the theme's "config" file using a simple JSON structure.

The config file contains some basic metadata at the top which is followed by an array of properties. These properties contain the custom options you want to add to your theme along with their default values.

Sample Config File:

{
  "title": "My Theme",
  "author": "SnapPages",
  "properties": [
    {
      "title": "Custom Color",
      "name": "customColor",
      "type": "color",
      "color": "#0091ba",
      "allowtransparency": "true"
    },
    {
      "title": "Custom Background",
      "name": "customBackground",
      "type": "background",
      "color": "#222",
      "src": "",
      "position": "top left",
      "repeat": "both",
      "size": "auto",
      "attachment": "fixed"
    },
    {
      "title": "Custom Typography",
      "name": "customTypography",
      "type": "typography",
      "font": "Open Sans",
      "color": "#ffffff",
      "weight": 400,
      "style": "normal",
      "size": "46px",
      "lineheight": "1em",
      "decoration": "none",
      "transform": "none",
      "letterspacing": "-.04em"
    }
  ]
}

Metadata

title The title of the theme that you want to display when a user installs the theme.
author Your name goes here.


Options

Every customizable option that you add will at least contain these default properties:
title This is the title or label that the user will see in the custom options menu.
name This is the internal variable name for the property that is used within the HTML and CSS file. It can only contain alpha numeric characters with no spaces or punctuation marks. We also recommend that you camel-case these.
type There are different types of custom options and each one has unique properties. The type can be set to any one of the following:
  • color
  • background
  • typography
  • text
  • link
  • image


Option Types

In addition to the default properties given to each customizable option, each type of option has spefic properties and different methods to actually integrate them into the theme.

Color

This option type allows users to select a custom color using the color picker UI element.

Additional Properties

color A color in either a hex or RGBA value.
allowtransparency A boolean value of either "true" or "false". When set to true, a slider will appear on the color picker UI element that allows a user to also select the alpha value for the color.

Sample Option Config

{
  "title": "Custom Color",
  "name": "customColor",
  "type": "color",
  "color": "#0091ba",
  "allowtransparency": "true"
}

Implementation Instructions

When a color option is set by a user, a custom LESS variable is created with a name that is identical to the "name" property for that option. This LESS variable can then be used for any color value in the CSS file for the theme like in the following example:
#customElement{
	color: @customColor;
}


Background

This option type allows users to the background image or color for a particular HTML element.

Additional Properties

color A color in either a hex or RGBA value.
src The path of the image file to use as a background. Leave this value blank if you only want to set a background color. If this file is an image you have uploaded in the Themes app, use a simple relative path to the image (ex: "./images/filename.jpg").
position The position of the background image. This property can be any valid CSS background-position value.
repeat The tiling of the background image. This property can be any valid CSS background-repeat value.
size Determines if the image should scale to fit the HTML element or not. This property can be any valid CSS background-size value.
attachment Set whether the background image should scroll with the page or not. This property can be either "scroll" or "fixed".

Sample Option Config

{
  "title": "Custom Background",
  "name": "customBackground",
  "type": "background",
  "color": "#222",
  "src": "",
  "position": "top left",
  "repeat": "both",
  "size": "auto",
  "attachment": "fixed"
}

Implementation Instructions

When a background option is set by a user, a LESS mixin is created with a name that is identical to the "name" property for that option. This mixin can then be used for any rule in the CSS file for the theme like in the following example:
#customElement{
	.customBackground;
}


Typography

This option type allows the style of how certain text should look. This option is unique in that it's properties are optional. If there is a certain aspect of the typographic style that you don't want to give the user control over, simple leave out that property.

Additional Properties

font The name of the font to use for this style. The easiest way to set this is to just create it with a default value of "Open Sans" and then use the Themes app font selector UI to set this later.
color A color in either a hex or RGBA value.
weight The numerical font weight for the text. Unless you know all the font weights available for each font, set this to 400 and then modify it later using the Themes app typography UI.
style The position of the background image. This property can be any valid CSS background-position value.
size The numerical size fo the text in pixels. This can be anywhere from 8px to 72px.
lineheight The numerical value for the line height of the text in ems. This can be anywhere from 1em to 8em.
decoration This property can be any valid CSS text-decoration value.
transform This property can be any valid CSS text-transform value.
letterspacing The numerical value for the letter spacing of the text in ems. This can be anywhere from -.1em to .5em.

Sample Option Config

{
  "title": "Custom Typography",
  "name": "customTypography",
  "type": "typography",
  "font": "Open Sans",
  "color": "#ffffff",
  "weight": 400,
  "style": "normal",
  "size": "46px",
  "lineheight": "1em",
  "decoration": "none",
  "transform": "none",
  "letterspacing": "-.04em"
}

Implementation Instructions

When a typography option is set by a user, a LESS mixin is created with a name that is identical to the "name" property for that option. This mixin can then be used for any rule in the CSS file for the theme like in the following example:
#customElement{
	.customTypography;
}


Text

This option type allows a user to input some custom text that will be inserted into the actual HTML of the theme.

Additional Properties

content The default text that will appear inside the custom HTML element.

Sample Option Config

{
  "title": "Custom Text",
  "name": "customText",
  "type": "text",
  "content": "My custom text goes here."
}

Implementation Instructions

You must create a custom element inside the HTML of the theme and give it the class of "sp-custom" and a "data-name" attribute set to the name of the custom option. The contents of this element will be completely replaced by user's input. Here is a sample of how the HTML should look:
<div class="sp-custom" data-name="customText">Custom text goes here.</div>


This option type allows a user change the value of the "href" and "target" attributes for an anchor tag.

Additional Properties

url The URL that you want the link to point to.
target The value of the "target" attribute for the anchor tag.

Sample Option Config

{
  "title": "Custom Link",
  "name": "customLink",
  "type": "link",
  "url": "http://snappages.com",
  "target": "_blank"
}

Implementation Instructions

You must create an anchor tag inside the HTML of the theme and give it the class of "sp-custom" and a "data-name" attribute set to the name of the custom option. The values of the "href" and "target" attribute for the tag will replaced by user's input when the site is loaded. Here is a sample of how the HTML should look:
<a href="" target="" class="sp-custom" data-name="customLink"></a>


Image

This option type allows a user swap out the "src" of an "img" tag with an image of their choosing.

Additional Properties

src The URL that you want the link to point to.
width The value of the "target" attribute for the anchor tag.
height The value of the "target" attribute for the anchor tag.

Sample Option Config

{
 "title": "Custom Image",
  "name": "customImage",
  "type": "image",
  "src": "./images/filename.jpg",
  "width": "150",
  "height": ""
}

Implementation Instructions

You must create an image tag inside the HTML of the theme and give it the class of "sp-custom" and a "data-name" attribute set to the name of the custom option. The value of the "src" attribute for the tag will replaced by user image. Here is a sample of how the HTML should look:
<img src="" class="sp-custom" data-name="customImage" />