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.

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

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>

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

Asset
Asset

Region

Asset
Asset
Asset
Asset
Asset
Asset
Background Image

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 max_auto_assets, or if the value is 0, it will add all of the remaining assets to that region. This setting is optional, but recommended.

Heads up! Every theme should have at least one region set up with max_auto_assets="0", usually the main content region.

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: max_cols="3"

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

Row
Asset
size 1
Row
Asset
size 2
Asset
size 2
Row
Asset
size 3
Asset
size 3
Asset
size 3

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 1, 2, 3... and so on.
Columnizer example: size="2"

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.

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 false)

If set to true, then all images appearing in the image slider will be cropped to the size specified in the image slider helper.

If set to false or left undefined, then when the image slider contains just one image, that image will be scaled down to match the width property of the image slider, and the image height will be calculated proportionally (ignoring the height property of the image slider).

Heads up! Unlike a simple {{{resize}}} helper, you should always define both the width and the height of an image slider.

Our image slider helper is based on the excellent jQuery Cycle 2 slider by Mike Alsup. To fine tune the slider's settings for your theme, refer to the jQuery Cycle 2 API documentation.

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:
c = Center
nw = Top left (northwest)
ne = Top right (northeast)
sw = Bottom left (southwest)
se = Bottom right (southeast)

data-style

Background image size. Values can be:
fill = The image will be scaled to cover the page background.
tile = The image will be repeated horizontally and vertically at its original size.
fixed = The image will be in a stationary location at its original size.

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

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 0, the theme rendering engine will use Populr's legacy grid. This serves as a good default setting. If you would like to get fancy with your own grid, set this to 1.

@base-url

The pop's base URL. Should be set to the value '..'. Do not change this value; the system uses this variable to generate paths to the theme's file.

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 @background-color. When someone opens the pop, Populr will display this color as the pop background while the background image is being loaded. This technique creates a less abrupt transition when the background image is finally loaded and displayed.

@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:
Center Styles


Here are the meta tag definitions that result in these thumbnails.

<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;
Color Picker

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, and has-links.
  • If JavaScript is enabled in the pop viewer's browser, <body> gets the class js. If JavaScript is disabled, <body> gets no-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 row
  • columnizer-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

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 of 1, the second an index of 2, 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.

Quick Tip! Checkout the public theme repository for Populr. You can see some working examples of current themes and the CSS & Javascript behind them.

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';

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 assets
  • I for image assets
  • V 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 assets
  • E 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"

Text Asset
Text Asset
Image Asset
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).

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!