
Theming
Creating your own Populr theme is piece of cake once you get to know the system. This guide will help you learn the fundamentals of theming.
Getting Started
First thing's first, watch this brief video to get an overview of the most important concepts for designing and building a Populr theme.
Populr theming is based on a couple of existing open-source technologies. If you already know Handlebars.js and LESS, feel free to skip ahead. Otherwise, keep reading intrepid explorer!
A Populr theme, like any (good) HTML/CSS breakdown, is separated into two layers: semantic structure/content, and style.
Structure/Content
A theme's structure is built in Handlebars.js,
a JavaScript-based templating language. Although it may appear
overwhelming at first, a Handlebars.js template is simply centered around
one basic construct: the curly-brace { }
.
With this, you can define every piece of stucture and content you will
use in creating your theme. The Handlebars.js elements of the asset return HTML, so they can be wrapped in div
tags to apply styling.
Example Asset Template (don't worry about the syntax right now)
{{#asset "text" size="2"}} {{{title}}} {{{body}}} {{/asset}}
Asset templates are comprised of 3 parts: a title, the content, and a description. (Text assets like the one shown above generally don't include a description, since the content is a block of text.) The content is the only mandatory component of the template; titles and descriptions are optional. These parts can be appear in any order within the asset template.
Style
Stylesheets are built in LESS
CSS. If you are comfortable with CSS, you will be comfortable with LESS.
Populr uses LESS variables to allow users to change various settings in
the Pop. Refer to the variables.less
file in the base theme
for more information.
Heads up! If you choose not familiarize yourself with Handlebars.js and LESS before continuing, you will have a difficult journey ahead. Seriously, read up on these two technologies or we will be forced to flip a table (╯°□°)╯︵┻━┻ You don't want us to do that, do you?
The base theme contains the bare minimum you need to build a new theme:
a single columnizer region with 3 columns
A Simple Example Theme
Populr themes are simple HTML5 websites with a few special hooks. Once you're comfortable with Handlebars.js, the code below should make sense to you. This is the index.html file for a very simple theme containing just one region. Look it over to get a feel for the syntax.
You can also download the base theme to get started with your own theme.
index.html
<!doctype html> <html itemscope> <head> <meta charset="utf-8"> <title>My New Theme</title> <meta itemprop="dummyImageCategory" content="All"> <meta itemprop="dummyContentLength" content="medium"> <link rel="stylesheet/less" type="text/css" href="/styles/main.less"> <script src="http://populr.me/assets/developers/themer.js"></script> <script src="/js/main.js"></script> </head> <body> <script id="theme" type="text/x-handlebars-template"> {{{title}}} {{#region "columnizer" id="main-region" max_cols="3" max_auto_assets="0" dummy_content="T-1|I-3|V-3|D-3|E-3"}} {{#asset "text" size="1"}} {{{title}}} {{{body}}} {{/asset}} {{#asset "imagegroup" size="1"}} {{{title}}} {{{imageslider images width="400" height="300"}}} {{{description}}} {{/asset}} {{#asset "documentgroup" size="1"}} {{{title}}} {{{description}}} <ul> {{#documents}} <li><a href="{{original_url}}">{{title}}</a></li> {{/documents}} </ul> {{/asset}} {{#asset "embedgroup" size="1" width="400"}} {{{title}}} {{#embeds}} <div class="embed">{{{html}}}</div> {{/embeds}} {{{description}}} {{/asset}} {{/region}} </script> </body> </html>
Anatomy of a Theme
A Populr theme is basically made up of two things: regions and assets.
Regions
At its core, a region is simply a container for assets. The magic happens when defining what type of layout engine a region uses to display those assets. We'll talk more about this in a bit. The only layout engine currently available is:
- Columnizer
Assets
Assets are the heart of Populr. Users can add 5 types of content to Populr:
- Text
- Images
- Files/documents
- Embeds
- Recorded video(s), which are treated as embeds
Each asset is contained inside of a region, and is rendered according to the region it resides in, as well as the size selected for the asset.
Sample Pop Layout
Pop Title
Region
Region
Regions
Regions are intelligent layout containers for assets. Every region you define will become an area users can place assets in the Pop editor.
Regions are defined with the {{#region}}
Handlebars.js block helper. They are rendered as HTML5
section
elements.
{{#region "columnizer" id="main-region" max_cols="3" max_auto_assets="0" dummy_content="T-1|I-3,D-2,E-1"}} ... {{/region}}
<section class="region columnizer-region" id="main-region" data-region-type="columnizer" data-region-id="0"> </section>
There are a few settings that should be defined for every region.
Name | Usage |
---|---|
id |
The ID of the region |
max_auto_assets |
The maximum number of assets Populr will automatically place in
this region when a user applies your theme to their pop. When automatically
placing assets, Populr will work through your regions in source
order. If it finds a region that doesn't define
Heads up! Every theme should have at least one region set up with |
Columnizer Layout Engine
The Columnizer engine arranges assets first into rows, then into columns. Each row spans the full width of the region. When a user adds an asset to a row, the engine automatically resizes other assets in that row to make room for the new asset. As the themer, you define the maximum number of columns per row, from as few as 1 to as many as you'd like to style.
Helper
{{#region "columnizer" id="main-region" max_auto_assets="0" max_cols="3"}} {{/region}}
Engine-Specific Settings
Name | Usage |
---|---|
max_cols |
The maximum number of columns (assets) in a row Example: |
Asset Sizing
Within Columnizer regions, asset sizes are determined by the number of assets in the row. For example, if a row contains just one asset, then that asset's size
is 1
and it's assigned the class asset-size-1
. If
a row contains two assets, each asset is a size 2
and they're each assigned the class asset-size-2
.
Columnizer Region
Rowsize 1
size 2
size 2
size 3
size 3
size 3
Assets
Assets are the actual content a user places in Pop. Each type of asset
has unique properties that you can access when creating your theme.
Assets are defined with the {{#asset}}
Handlebars.js block helper, and are rendered as div
elements.
Heads up! Asset templates must be nested inside of region definitions, and you must define asset templates for every asset type and every available asset size in each region.
{{#asset "text" size="2"}} {{{title}}} <div class="content"> {{{body}}} </div> {{/asset}}
<div class="asset asset-type-text asset-size-2" data-region-id="0"> <div class="asset-inner"> <h2 class="title">Aenean Commodo Ligula</h2> <div class="content"> <div class="body">Lorem ipsum dolor sit amet.</div> </div> </div> </div>
The size
setting must be defined for every asset template.
Name | Usage |
---|---|
size |
The size this asset template is associated with.
For a Columnizer region, the available asset sizes are |
Text Asset Type
The text
asset type is the most basic asset in Populr. It
allows the user to enter a title and body content.
Template Variables
Variable | Description | Contents |
---|---|---|
{{{title}}} |
Title of the asset |
<h2 class="title">Lorem Ipsum</h2>
|
{{{body}}} |
Body content of the asset |
<div class="body content"><p>Lorem ipsum dolor sit amet.</p></div>
|
ImageGroup Asset Type
The imagegroup
asset type is a container for one or more images selected by the user.
The example template below shows you an image asset template that doesn't use Populr's image slider helper. To see an image asset template that uses our image slider helper, take a look at the simple example theme near the top of this document.
{{#asset "imagegroup" size="m"}} {{{title}}} <ul class="images"> {{#images}} <li><img src="{{{resize original_url width=640 height=480}}}" title="{{{title}}}"/></li> {{/images}} </ul> {{{description}}} {{/asset}}
<div class="asset asset-type-imagegroup asset-size-m" data-region-id="0"> <div class="asset-inner"> <h2 class="title">Aenean Commodo Ligula</h2> <ul class="images"> <li><img src="https://i.populr.me/640/480/http://lorempixel.com/1280/1024%3F0" title="Lorem Ipsum"/></li> </ul> <div class="description">Lorem ipsum dolor sit amet.</div> </div> </div>
Heads up! Multiple images can be added to an imagegroup. We strongly recommend you use Populr's image slider helper in your image assets. Other sliders are unsupported, meaning you can give them a try but if it doesn't work you'll miss out on the super-helpful support of our theming staff. You'll be on your own, cowboy/girl.
Template Variables
Variable | Description | Contents |
---|---|---|
{{{title}}} |
Title of the asset |
<h2 class="title">Lorem Ipsum</h2>
|
{{{description}}} |
Description content of the asset |
<div class="description"><p>Lorem ipsum dolor sit amet.</p></div>
|
{{{images}}} |
Array of images in the imagegroup
|
[images]
|
Templating {{{images}}}
The {{{images}}}
variable is an
array of individual images. Even when there is only one image in the asset, that image is stored as an element of the array. To display the asset contents, you must use a helper either to loop through
each image or to access a specific image in the array.
Variable | Description |
---|---|
{{{title}}} |
Title of the image |
{{{description}}} |
Description of the image |
{{{original_url}}} |
URL for the image Heads up! You should almost always pass this value into the resize helper. |
{{{source_file_name}}} |
Original filename |
{{{source_file_size}}} |
Original filesize, in bytes Heads up! You can use the {{{format_file_size}}} helper
to automatically display the filesize in an easy-to-read format.
|
{{{width}}} |
Original image width |
{{{height}}} |
Original image height |
DocumentGroup Asset Type
The documentgroup
asset type is a container for one or
more files uploaded by the user.
{{#asset "documentgroup" size="m"}} {{{title}}} {{{description}}} <ul class="documents"> {{#documents}} <li class="file-extension file-extension-{{{extension}}}"> {{#if title}} <a href="{{{original_url}}}">{{{title}}}</a> {{else}} <a href="{{{original_url}}}">{{{source_file_name}}}</a> {{/if}} </li> {{/documents}} </ul> {{/asset}}
<div class="asset asset-type-documentgroup asset-size-m" data-region-id="0"> <div class="asset-inner"> <h2 class="title">Aenean Commodo Ligula</h2> <div class="description">Lorem ipsum dolor sit amet.</div> <ul class="documents"> <li class="file-extension file-extension-zip"> <a href="files.populr.me/assets/theme_sample.zip">theme_sample.zip</a> </li> </ul> </div> </div>
Template Variables
Variable | Description | Contents |
---|---|---|
{{{title}}} |
Title of the asset |
<h2 class="title">Lorem Ipsum</h2>
|
{{{description}}} |
Description content of the asset |
<div class="description"><p>Lorem ipsum dolor sit amet.</p></div>
|
{{{documents}}} |
Array of documents in the documentgroup
|
[documents]
|
Templating {{{documents}}}
The {{{documents}}}
variable is an
array of individual user-uploaded documents. Even when there is only one document in the asset, that document is stored as an element of the array. To display the asset contents, you must use a helper either to loop through
each document or to access a specific document in the array.
Variable | Description |
---|---|
{{{title}}} |
Title of the document |
{{{description}}} |
Description of the document |
{{{original_url}}} |
URL to document |
{{{extension}}} |
Extension name of the document, without period |
{{{source_file_name}}} |
Original filename of the uploaded document, including extension |
{{{source_file_size}}} |
Original filesize, in bytes. Heads up! You can use the {{{format_file_size}}} helper
to automatically display the filesize in an easy-to-read format.
|
{{{source_content_type}}} |
Content type of document (application/octet-stream if unknown) |
EmbedGroup Asset Type
The embedgroup
asset type is a container for one or
more embedded elements added by the user.
{{#asset "embedgroup" size="m" width="640"}} {{{title}}} <div class="embeds"> {{#embeds}} <div class="embed embed-type-{{{css_safe_provider}}}"> {{{html}}} </div> {{/embeds}} </div> {{{description}}} {{/asset}}
<div class="asset asset-type-embedgroup asset-size-m" data-region-id="0"> <div class="asset-inner"> <h2 class="title">Aenean Commodo Ligula</h2> <div class="embed embed-type-{{{css_safe_provider}}}"> <div class="embedded-object"> <iframe width="640" height="480" src="http://www.youtube.com/embed/q-_4mcYsQdE?wmode=transparent&fs=1&feature=oembed" frameborder="0" allowfullscreen></iframe> <img src="http://i3.ytimg.com/vi/q-_4mcYsQdE/hqdefault.jpg" alt="" style="width:640px;height:480px;display:none;"/> </div> </div> <div class="description">Lorem ipsum dolor sit amet.</div> </div> </div>
Heads up! Note that embeds are the only asset type for which the widths have to be specified in the {{#asset}}
block helper.
Template Variables
Variable | Description | Contents |
---|---|---|
{{{title}}} |
Title of the asset |
<h2 class="title">Lorem Ipsum</h2>
|
{{{description}}} |
Description content of the asset |
<div class="description"><p>Lorem ipsum dolor sit amet.</p></div>
|
{{{embeds}}} |
Array of embeds in the embedgroup
|
[embeds]
|
Templating {{{embeds}}}
The {{{embeds}}}
variable is an
array of individual user-selected embed elements. Even when there is only one embed in the asset, that embed is stored as an element of the array. To display the asset contents, you must use a helper either to loop through
each embed or to access a specific embed in the array.
Variable | Description |
---|---|
{{{title}}} |
Title of the embed |
{{{description}}} |
Description of the embed |
{{{html}}} |
Actual html of the embed |
{{{provider}}} |
Website embed originated from |
{{{css_safe_provider}}} |
CSS-safe version of embed provider |
Asset Template Variations
Each region must contain asset templates for every combination of asset type and size that can appear in the region. This provides an opportunity to apply different layouts and styling to assets depending on parent region, asset type, or size. Furthermore, the {{{if_many}}}
helper can be used to apply layout and style variations depending on how many items are contained in an asset - see the {{{if_many}}} helper documentation for details.
Get creative! The most successful Populr themes are the ones that give users a range of stylistic variations. Add a region at the top of the theme for a hero image or video. Vary your typography depending on the size of the asset. Change your image slider parameters for the body and footer regions. Mix things up a bit and you'll have a beautiful theme in no time.
Helpers
Populr provides several Handlebars.js template helpers and other bits of code to assist you in building your theme.
Resize
The {{{resize}}}
helper is fundamental
to Populr theming. Users can upload any size image they want in the
Populr editor. Obviously, this is not ideal for a good looking theme,
so the resize helper allows you to scale and crop images to your
liking by redirecting urls through our image transformer.
Helper
{{{resize original_url width=640 height=480}}}
Settings
Name | Usage |
---|---|
width |
Target width (optional) |
height |
Target height (optional) |
Heads up! Defining either a width
or a height will proportionally scale the image to fit
the defined dimension. If you define both the width and
the height, the image will be scaled and cropped to fit within both
dimensions. A value of 0
will act the same as an undefined value.
If Many
The {{{if_many}}}
helper gives you the
ability to detect whether a group asset has one item or multiple items
in its contents. This is particularly useful when you want to create one
template for a single item, and another for multiple. This helper works
exactly the same as a normal Handlebars.js if
helper. The else
block is
optional.
Helper
<!-- within an imagegroup template --> {{#if_many images}} <!-- loop through images --> {{else}} <!-- display single image --> {{/if_many}}
Settings
There are no settings for this helper.
If Equal
The {{{if_equal}}}
helper gives you another way to add conditionals into your templates. The else
block is optional.
The example here shows how the {{{if_equal}}}
helper can be used to style embedded videos differently from other embeds.
Helper
<!-- within an embedgroup template --> {{#embeds}} {{#if_equal kind "video"}} <div class="embedded-video">{{{html}}}</div> {{else}} <div class="embed">{{{html}}}</div> {{/if_equal}} {{/embeds}}
Settings
There are no settings for this helper.
If Or
The {{{if_or}}}
helper is passed 2 parameters, and will evaluate as true if either parameter is true. The else
block is optional.
The example here shows how the {{{if_or}}}
helper can be used to render a div in an asset only if the asset's title or description are visible.
Helper
{{#asset "imagegroup" size="1"}} {{{imageslider images width="220" height="147"}}} {{#if_or title_visible description_visible}} <div class="text"> {{{title}}} {{{description}}} </div> {{/if_or}} {{/asset}}
Settings
There are no settings for this helper.
If And
The {{{if_and}}}
helper is passed 2 parameters, and will evaluate as true only if both parameters are true. The else
block is optional.
The example here shows how the {{{if_and}}}
helper can be used to render a div in between a text asset title and description only when both are visible.
Helper
{{#asset "text" size="1"}} {{{title}}} {{#if_and title_visible body_visible}} <div class="h-rule" /> {{/if_and}} {{{body}}} {{/asset}}
Settings
There are no settings for this helper.
Format File Size
The {{{format_file_size}}}
helper
formats a filesize, listed in bytes, to a more-readable representation.
It will automatically decide if the size should be displayed as one of
the following: 'Bytes', 'KB', 'MB', 'GB', 'TB'
Helper
{{{format_file_size source_file_size precision=2}}}
Settings
Name | Usage |
---|---|
precision |
Number of decimal places (optional, default is 2 ) |
Image Slider
The {{{imageslider}}}
helper creates a
ready-made JavaScript image slider for your imagegroup
assets.
If there is only one image in an asset's {{{images}}}
array, then that image will not be cropped; it will simply be scaled to fit the full width of its container. However, if there are multiple images in the {{{images}}}
array, they will be first scaled, then cropped as needed to fit the dimensions specified by the width
and height
parameters.
If your theme uses the image slider helper, you must include the following line of code in your main.less file.
main.less
#populr > #image-slider-themes > .basic();
Helper
{{{imageslider images width=640 height=480}}}
Settings
Name | Usage |
---|---|
width |
Target width |
height |
Target height |
crop-single |
Image cropping setting (optional, default is
If set to
If set to |
Heads up! Unlike a simple
{{{resize}}}
helper, you should
always define both the width and the height of an image slider.
Pop links
The {{pop_links}}
helper lets your users add small link icons to their pop. For example, someone could set up links to their Facebook and Twitter pages, then display those links in their pop using the Facebook and Twitter favicons. You can override the favicon with an icon of your choosing. Users set these links up in their account settings. They can then choose whether or not to display these link icons for each pop by toggling the Show Default Links switch in the Options dropdown menu of the pop editor.
Note that if you don't manually insert this helper in the location of your choice, Populr will automatically insert it at the bottom of your theme.
Helper
{{pop_links}}
Settings
There are no settings for this helper.
Default appearance
For example, links to Facebook and Twitter pages will look like this:
Logo
The {{logo}}
helper lets your users add a logo to their pop, in a location you specify. A user adds a logo image through the Logo dropdown menu of the pop editor.
Note that if you don't manually insert this helper in the location of your choice, Populr will automatically insert it at the top of your theme.
Helper
{{logo max_width=250}}
Settings
Name | Usage |
---|---|
max_width |
Maximum width in pixels (optional) |
max_height |
Maximum height in pixels (optional) |
Heads up! You don't have to specify a width or height, but if you choose to define one, don't define the other.
strip_html
The {{{strip_html}}}
helper will strip the HTML from any template you pass to it. For example, when {{{strip_html title}}}
is inserted into an asset template, it will return the asset's title as plain text.
Helper
{{{strip_html [template]}}}
Settings
There are no settings for this helper.
Raw text helpers
These helpers will return the value of their respective templates as plain text. For example, {{{title_raw}}}
will return its asset's title as plain text. The output of these helpers is effectively the same as the output when using the {{{strip_html}}} helper on a template.
Helpers
{{{title_raw}}} {{{body_raw}}} {{{description_raw}}}
Settings
There are no settings for this helper.
cssify
The {{{cssify}}}
helper will turn a template's contents into CSS-friendly syntax. For example, if {{{cssify title_raw}}}
is inserted into an asset template, and that asset's title is "So it goes.", it will return the asset's title as "so-it-goes".
Helper
{{{cssify [template]}}}
Settings
There are no settings for this helper.
base_path
The {{{base_path}}}
helper is used for specifying a relative file path within your theme's Handlebars template. If you have to specify a relative file path inside the <script id="theme" type="text/x-handlebars-template">
tag of your index.html file, you must use this helper.
Example
<img src='{{{base_path}}}/images/bg_image.png' />
Settings
There are no settings for this helper.
Log helper
The Populr {{log}}
helper will write a template's context state to the browser console.
Example
{{log}}
Settings
There are no settings for this helper.
Default background image
You can set a default background image for your theme by adding the following meta tag to your theme header. Users will always have the capability to override the default background through the Background dropdown menu of the pop editor.
Heads up! For this tag to work properly, your html tag must include the itemscope element, like so: <html itemscope>
Example
<head> <meta itemprop="defaultBackground" content="/images/background.jpg" data-width="1800" data-height="1800" data-position="c" data-style="fill" data-color="#665b42"> ...
Settings
Name | Usage |
---|---|
itemprop |
defaultBackground (do not change) |
content |
Path to the background image file. Can be a relative path. |
data-width |
Image width in pixels |
data-height |
Image height in pixels |
data-position |
Background image position. Values can be: |
data-style |
Background image size. Values can be: |
data-color |
The average color of the image. This color will fill the page background while the image is loading. |
Apply Background to Element
The user-specified background image is applied to the pop's <body>
tag by default. However, you can override this default and set that image as the background for a different element on the page. In the example to the right, taken from the theme named Cumberland, the background image is applied to the first columnizer row in the pop.
Heads up! For this tag to work properly, your html tag must include the itemscope element, like so: <html itemscope>
Example
<head> <meta itemprop="backgroundContainer" content=".columnizer-row:first-child"> ...
Settings
Name | Usage |
---|---|
itemprop |
backgroundContainer (do not change) |
content |
CSS selector specifying the element that gets the background |
Styling
The CSS styling for Populr themes is generally stored in 2 LESS files: main.less and variables.less.
Main.less
Main.less is where the majority of your CSS should be stored. It contains calls to import variables.less, populr_mixins.less, and any other necessary LESS files.
Heads up! You must import variables.less before populr_mixins.less.
Variables.less
Variables.less stores LESS variables that can be changed by the user through Populr's pop editing interface, or that are updated by the pop rendering engine when the page loads.
Name | Description |
---|---|
@populr-theme-version |
Flag that sets the theme's grid. When set to |
@base-url |
The pop's base URL. Should be set to the value This variable is used to set relative links within your CSS. For example, the background image for a page element can be set like this: background: transparent url("@{base-url}/images/region-bg.png") no-repeat;
|
@custom-color |
If a theme includes the "Custom" style, this variable can be overridden by the user through a color picker that will appear in the Style menu. Learn more about styles and the custom color picker |
@background-color |
The background color used when this page is first rendered
Once a user sets a background image for their pop, Populr will calculate the average color of the image and store that value in |
@headline-font-family |
The default font family for the pop title and asset titles when the theme is selected This value can be overridden by the user with the Font drop-down menu. |
@headline-font-weight |
The default font weight for the pop title and asset titles when the theme is selected This value can be overridden by the user with the text formatting bar. |
Populr_mixins.less
Populr_mixins.less contains several important mixins for your theme. Make sure to add the following line to the top of your main.less file:
@import 'http://populr.me/assets/developers/populr_mixins.less';
Some Helpful Populr Mixins
Text Color
#populr > .text-color-over-color(@color-parameter);
It's often desirable for a piece of text to change its color based on the color behind it. For example, if a user chooses a very bright background image for their pop, text set against the image should be a dark color, so that it's legible. However, if a user chooses a very dark background image, that same text will only be legible if it's a light color.
The .text-color-over-color() helper provides a quick solution for this scenario. This helper takes a single parameter – the color behind the text – and sets the CSS color
attribute based on what text color would be legible against the parameter color.
Let's look at an example wherein an asset's title text is set against the pop background image. The following CSS will automatically apply legible text colors.
.asset-title { #populr > .text-color-over-color(@background-color); }
@background-color is a LESS variable automatically calculated as the average color of the user-specified background image. So this code will compile into one of the following results based on the brightness of @background-color.
@background-color is dark
.asset-title { color: #fff; }
@background-color is bright
.asset-title { color: #333; }
Inline Title and Logo
#populr > .inline-logo-title();
This mixin provides a quick way to add elegant responsive behavior to your theme's logo helper and title if they sit side by side. It's used in the themes called Edgefield and Cumberland.
Icon styling
#populr > .icon(@color-parameter);
This mixin applies some attractive default styling to the icons that users can add via the pop editor. The color parameter sets the backdrop color for the icon. The icon itself is colored according to the .text-color-over-color() mixin.
The .icon() mixin will be automatically incorporated into your theme's stylesheet if you set @populr-theme-version: 0;
in your variables.less file. If you set @populr-theme-version: 1;
, you will have to manually add this mixin if you want to incorporate this styling; you can also omit this mixin and style the icons yourself.
Button styling
#populr > .link-button(@color-parameter);
This mixin applies some attractive default styling to the link buttons that users can apply to their text via the pop editor. The color parameter sets the backdrop color for the button. The button text is colored according to the .text-color-over-color() mixin.
The .link-button() mixin will be automatically incorporated into your theme's stylesheet if you set @populr-theme-version: 0;
in your variables.less file. If you set @populr-theme-version: 1;
, you will have to manually add this mixin if you want to incorporate this styling; you can also omit this mixin and style the buttons yourself.
LESS Mixin Libraries
At Populr, we often find it helpful to use LESS mixin libraries when creating a theme. These libraries provide a quick way to add cross-browser compatibility or some functional or stylistic coolness. Our favorites are:
Theme Styles
Put simply, theme styles are variations on a theme. Populr's UI gives end users the ability to customize their pop by choosing from a set of styles defined by the theme designer. Styles can represent a series of color palettes for a theme, a set of variations in the asset layout, or other design changes. While styles are optional, we encourage theme designers to create at least 2 styles for each theme. (One simple way to meet this request is to create a light and a dark style for your theme.)
For example, the theme Norway uses styles to give users a choice of color variations for the background of the title and footer. Users can choose from 4 colors selected by the designer who built the theme.
Each theme style is defined in its own LESS file, located in the theme's styles directory. Every theme that uses more than one style must have the default style specified in a file named palette-default.less. Additional styles can be named whatever sematically makes sense. In the case of Norway, the additional styles have fun names based on the color they represent: palette-sulu.less, palette-tango.less, etc.
These theme style files are referenced from the theme's index.html file with the following syntax (using the theme Norway as an example):
index.html in the theme called Norway
<meta itemprop="palette" content="palette-default" title="Malibu" data-preview="#66b5f2"> <meta itemprop="palette" content="palette-sulu" title="Sulu" data-preview="#bcf266"> <meta itemprop="palette" content="palette-tango" title="Tango" data-preview="#f36d24"> <meta itemprop="palette" content="palette-custom" title="Custom" data-preview="custom">
Heads up! For these tags to work properly, your html tag must include the itemscope element, like so: <html itemscope>
These attributes are used like this:
Name | Description |
---|---|
itemprop |
Should always be set to "palette" |
content |
The name of the LESS file containing the theme style's CSS. Do not include the ".less" file extension. |
title |
The name of the theme style that will appear in the Styles dropdown menu of the pop editor. This is what the end user will see when choosing styles. |
data-preview |
This attribute defines the color bars that act as a thumbnail for each style. Populr will turn each comma-separated hex value for this attribute into a vertical bar in the styles thumbnail box. (Thumbnail boxes appear in the Styles dropdown menu of the pop editor.) These thumbnail boxes give the end user a visual cue for each style.
For example, let's look at the theme Center. The Styles dropdown menu for Center looks like this by default:
<meta itemprop="palette" content="palette-default" title="Light" data-preview="#cccccc"> <meta itemprop="palette" content="palette-dark" title="Dark" data-preview="#111111"> <meta itemprop="palette" content="palette-transparent" title="Transparent" data-preview="#888,#fff,#888,#fff,#888,#fff,#888,#fff,#888,#fff"> |
The theme properties that vary across styles are defined in main.less with variables. Norway's main.less file specifies the background of the header area like this:
// main.less in Norway background: @header-color url("@{base-url}/images/header-overlay.png") repeat bottom center;
Note the use of @header-color
to specify the background color. To set that color, each theme style assigns a unique value to @header-color
. The theme's palette-default.less file contains this line of CSS:
// palette-default.less in Norway @header-color: #66b5f2;
By default, this theme will use the hex color #66b5f2 for the header's background color. A different style file for this theme (palette-sulu.less) contains this line:
// palette-sulu.less in Norway @header-color: #bcf266;
...so an end user who selects the style "Sulu" is basically redefining the value of the @header-color
LESS variable through Populr's UI.
Adding the Custom Color Picker
Populr has a built-in way for the end user to specify a custom color for a theme. This is accomplished through a special theme style.
The custom color theme style file must be named palette-custom.less. Also, the style definition tag in the theme's index.html file must be set up as follows:
<!-- index.html in Norway --> <meta itemprop="palette" content="palette-custom" title="Custom" data-preview="custom">
This will give the end users a color picker in the Style dropdown menu of the pop editor. The color selected by the user will be assigned to the less variable @custom-color
. To continue to our example with the theme Norway, the custom style file contains this line of CSS:
// palette-custom.less in Norway @header-color: @custom-color;

Theme Styles While Building Locally
Populr's local theming environment will allow you to test your theme styles one at a time by adding import statements to the top of your main.less file. For example, if one of your theme styles was stored in a file named red_accent.less, you could test that theme style in the local theming environment by adding this line to the top of your main.less file:
@import 'red_accent';
To test a different style for this theme, you'd replace red_accent
with the file name for the desired style.
For more information on building locally with the local theming environment, jump to that section of the documentation.
System-Generated Classes
Populr's theming engine automatically adds system-generated classes to certain page elements. Here are a few that will be especially valuable for building unique behaviors into your theme, such as applying styling variations based on content location, size, etc.
Classes added to the <html> tag
Populr uses Modernizr to add several classes automatically to the <html> tag. Head over to their site for the details.
<html> will also get IE classes in the style originally proposed by Paul Irish and improved by a few others.
Classes added to the <body> tag
Pops will have a number of classes added to the <body> tag as well.
- The theme style name will be added to <body> as a class. (See the theme styles section for more info.)
- <body> will get several classes that act as flags based on whether or not the user has enabled certain features for their pop. These classes are:
has-title
,has-logo
,has-sharing
, andhas-links
. - If JavaScript is enabled in the pop viewer's browser, <body> gets the class
js
. If JavaScript is disabled, <body> getsno-js
.
Rows in Columnizer Regions
Each columnizer row will automatically have the following classes applied.
columnizer-row
columnizer-cols#
, where#
is the number of assets contained in the rowcolumnizer-row-contents-[contents]
where[contents]
lists each asset type within the row in the corresponding order. For example:- A columnizer row containing only a single text asset gets the class
.columnizer-row-contents-text
- A columnizer row containing two image assets gets the class
.columnizer-row-contents-imagegroup-imagegroup
- A columnizer row containing a embed asset, a text asset, and then an document asset (in that order) gets the class
.columnizer-row-contents-embedgroup-text-documentgroup
- A columnizer row containing only a single text asset gets the class
Also, each columnizer row has a clearfix automatically applied by Pouplr's theming engine. This clearfix adds the :after
pseudo-element to the .columnizer-row div and applies a little CSS styling. Because .columnizer-row:after
is used by Populr's theming engine, you should avoid relying on it when styling a theme. One alternative could be to use .columnizer-row-inner
, a div nested just inside of .columnizer-row
.
Assets in Columnizer Regions
Each asset in a columnizer row is assigned to a class according to its index in the row.
columnizer-col#
, where#
is the index number of the asset in the row. The first asset has an index of1
, the second an index of2
, and so on.
Asset Types
Every asset is assigned to a class according to its type. Only one of the following classes is applied per asset.
asset-type-text
asset-type-imagegroup
asset-type-documentgroup
asset-type-embedgroup
Asset Sizes
Every asset is assigned to a class according to its size. Only one of the following classes is applied per asset.
Assets in Columnizer Regions
asset-size-1
asset-size-2
asset-size-3
- ...and so on for as many sizes as the region allows
Text Sizes
Users can choose from 3 sizes for any text in their pop: default, smaller, and larger. When a user applies either the smaller or larger size to a piece of text, that text gets wrapped in a div with a class that modifies the text size.
- Smaller text size:
<div class="font-size-smaller">
- Default text size: No class applied
- Larger text size:
<div class="font-size-larger">
You don't have to style these classes yourself; Populr will simply decrease or increase the font size when these classes are applied. However, you're free to style them if you wish. One suggestion: styling the font-size-smaller
class in your asset titles opens up some cool opportunities for fancy subtitles.
JavaScript
Populr's base theme includes a main.js file in js directory for easy inclusion of specific code. Please note that $(document).on('pop-initialized', function(){}); is equivalent to $(document).ready() in Populr's theme engine. All JavaScript code should be located here or in a subsequent file in the js directory. Inline scripts should not be added to the head tag of the index.html file.
For the best cross-browser experience, we highly recommend avoiding JavaScript solutions for CSS or appearance based manipulation. Please see the section System-Generated Classes for more inforation on available selectors.
Quick Tip! Checkout the public theme repository for Populr. You can see some working examples of current themes and the CSS & Javascript behind them.
Mobilization
Populr's theming engine does a great job rendering themes on mobile devices. In fact, we promise our customers that their content will look good on smartphones and tablets. As such, we require all themes to work on mobile devices with the help of responsive design.
We built a LESS mixin that handles a lot of the work for you. This mixin stacks each region vertially, then stacks all assets vertically within each region. You just have to add the mixin to your first media query within your main.less file. Take a look at this example:
main.less
@media screen and (max-width: 768px) { #populr > .mobile-reset(); ... }
That'll get your mobilization started. You'll almost certainly have to make additional adjustments in your media query to get things looking good. Be sure to test with a comprehensive set of dummy content to make sure you catch any mobile layout bugs!
Also, testing your theme on smaller screens can only be approximated by narrowing your browser window. To ensure your theme is stable on mobile, use a good simulator, or test on the mobile devices you have on hand.
Note that the main.less file must contain the following import statement in order for the mobile mixin to work.
main.less
@import 'http://populr.me/assets/developers/populr_mixins.less';
Building Locally
The Populr theming engine allows you to work on your theme locally before uploading it to Populr. Any theme can generate its own sample pop using dummy content pulled from Populr's servers, and this sample pop is run from Populr's local theming environment.
Using Dummy Content to Test Your Regions
Dummy content is generic asset content that's displayed when running your theme in the local theming environment. The text is lorum ipsum text, the images are from 500px, the embed is one of the world's greatest short films, etc.
Dummy content is defined as an attribute of the {{region}}
Handlebars.js helper. You might have noticed this earlier while reviewing the sample theme. Here it is again:
{{#region "columnizer" id="main-region" max_cols="3" max_auto_assets="0" dummy_content="I-3,T-1|T-2,E-1,D-4"}}
Columnizer Dummy Content Sizes
Each comma-separated string of the dummy content represents a single asset. The syntax for each asset is as follows:[asset type]-[# of items]
[asset type]
can have the following values:
T
for text assetsI
for image assetsV
for video recordings (which are treated by Populr as embed assets even though they are listed separately in the pop editor UI)D
for document assetsE
for embed assets
[# of items]
represents something different based on the asset type.
- For text assets, it represents the number of paragraphs of lorum ipsum text that will be generated.
- For all other assets, it represents the number of items that are contained within the asset. For example, a piece of dummy content defined as
I-3
represents an image asset containing 3 images.
Dummy content for columnizer regions does not specify a size. Instead, the |
(pipe) character is used to specify the end of a columnizer row, and asset sizes are determined based on the number of assets in a row. For example, dummy content defined as T-1,T-1|I-3
represents two text assets in the first row, each with a size of 2
and containing a single paragraph of lorum ipsum text, and single image asset in the next row with a size of 1
and containing 3 images.
Columnizer Region where dummy-content="T-1,T-1|I-3"
containing 3 images
Dummy Content Properties
The index.html file must contain the following meta
tags inside the head
tag in order for dummy content to render properly.
<head> <meta itemprop="dummyImageCategory" content="All"> <meta itemprop="dummyContentLength" content="medium"> ...
Heads up! For these tags to work properly, your html tag must include the itemscope element, like so: <html itemscope>
dummyImageCategory
Dummy images are pulled from the 500px photography site. The content
property can be used to specify a search term that will filter the images from 500px. For example, setting content="kitten"
will use pictures of adorable kittens for all dummy images.
dummyContentLength
This property specifies how much dummy text appears in the asset titles and descriptions of your dummy content.
We strongly recommend using content="medium"
while building your theme, as this is the most efficient setting for catching bugs. This setting will render all available text styles for your dummy asset titles and descriptions: bold, italic, underline, linked text, ordered lists, and unordered lists. (Lists will render only in asset descriptions.)
You can also use content="short"
to use dummy content of a more typical length and style, and content="long"
to ensure that lengthy pieces of text don't break your layouts.
Dummy Content Mixin
The main.less file must contain the following import statement in order for dummy content to render properly.
main.less
@import 'http://populr.me/assets/developers/populr_mixins.less';
Dummy Content Sets
We've typed up the following sets of dummy content to use when building your theme. Each set is defined to include all 5 types of content (text, image, video recording, document, embed) at all available sizes for a particular region. Copy the set you need for your region and paste it into the dummy_content property.
Running the Local Theming Environment on your Machine
At any time, you see how your theme looks by running Populr's local theming environment on your machine. The local theming environment is a simple HTTP server that runs from your theme's directory. Once you start the environment, you can use a browser to see how your theme looks on a pop containing dummy content (as covered in the previous section).
The Populr team uses Python to run the local theming environment, since Python has a simple HTTP server built right in. The local theming environment should also work with other methods of running an HTTP server locally For PC, we recommend installing http-server.
To start the local theming environment on your Mac using Python, open Terminal, then use the cd
command to change to your theme's directory. Once you're in the right directory, use this command to start your server:
python -m SimpleHTTPServer 8080
To start the local theming environment on your PC using http-server, open Terminal, then use the cd
command to change to your theme's directory. Once you're in the right directory, use this command to start your server:
http-server
You can then check out your theme by opening a browser and entering the URL http://localhost:8080
. You will see a pop that uses your theme, constructed from the dummy content you specified in your theme's region definition(s).
Recommended Theme Build Process
Now that you've seen the nuts and bolts of a Populr theme, read through our recommended process for taking your theme from concept to finished product. This'll save you some time, some effort, and at least a few headaches.
Step 1: Design
Designing up front will shorten your development time. Keep these pointers in mind while designing.
Review the requirements
We set certain design and feature requirements for all Populr themes. It's best to review these before you begin designing, that way you'll have them in mind while you plan out your theme.
Populr theme design requirements
Pick a concept
Get an idea of what your theme is "about." Themes turn out best when built around a purpose. What's the aesthetic: vintage, modern, playful? You could also think in terms of how it will be used. Will this theme be useful for newsletters, event invitations, or something else entirely?
Plan your regions
Next, plan your theme's regions. For your first theme, we recommend designing for two regions to keep it simple. Maybe you want a large region for the users' primary content and a footer region with different styling at the bottom. Maybe a hero region at the top for an eye-catching image or headline, and the page body underneath.
Sketch your asset styles
With your theme's purpose in mind, sketch out how your assets will look in each region. While some people jump straight into building, those people often run into design issues that they hadn't initially considered. Planning your design first will keep your CSS cleaner & shorter. Basically, you want to plan the styling for all combinations of asset type and size.
Remember that you'll have to define and style all asset types for every size that you allow in each region.
Design for compatibility
Finally, keep in mind that we require all of our themes to be compatible with Chrome, Safari, Firefox, and Internet Explorer all the way back to IE7. Your theme doesn't have to be pixel-perfect in all browsers, but when it does fail it should fail elegantly.
Step 2: Build
With your design in mind, you're ready to start coding. Follow these tips for a smooth build.
Start with our base theme
Start your theme from our base theme (GitHub repo or ZIP file). It's a clean, basic columnizer region with just enough code written to run as stand-alone theme.
Test as you go
Use dummy content well and test as you work. If you set up your dummy content to test all available asset types and sizes in each region, you'll save time by catching design bugs early. Review the dummy content documentation earlier on this page if you've forgotten how it works.
Step 3: Test
There's only so much testing you can do using dummy content. You'll have to test your theme out in the live system to make sure it's ready for showtime.
Sync your theme with GitHub
You can use GitHub to load your theme into Populr. Follow the instructions in this pop titled "Loading Your Theme Into Populr" and you'll have it working in no time. Once your theme is loaded, it will appear in the pop editor's Themes dropdown with a red border around it. The red border indicates that your theme is in beta.
Test in the editor
Create a new pop and apply your theme to test it in Populr's editor. Keep an eye out for strange behavior or layout issues.
The QA team at Populr uses this theme QA checklist to make sure everything's behaving the way it should. Follow those steps and you'll catch any remaining errors in your theme. Note that we don't pay our 3rd-party themers until their theme passes this checklist.
Step 4: Publish
Once your theme is bug-free, it's ready to be published. Publishing your theme will allow you to distribute it to others.
Publish from the "My account" screen
Go to the "My account" page and open the Themes tab. Click the Publish link for your theme. It will now appear in the editor in your Themes dropdown without the red border.
Share with others
Once published, you can share your theme with others by clicking on the Grant Access link of the Themes tab in the "My account" page. Just send that link to anyone with a Populr account. When they click the link, your theme will be added to their account.
The Kincannon theme design was fleshed out in a PSD before any code was written.
Download the full Kincannon PSD

Ready to get poppin'?
Congratulations! You made it to the end of the Populr documentation page. What a thorough and industrious developer you must be :).
If you still have questions about this stuff, get in touch with us: send an email to Jared at jared[at]populr.me
and he will get you sorted right out.
Pop pop!