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

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.

The text asset type is the most basic asset in Populr. It allows the user to enter a title and body content.

Template Variables

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>

Template Variables

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.

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

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.

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

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.

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.

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

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.

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.

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.

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.

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.

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

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

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

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

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

Heads up! You don't have to specify a width or height, but if you choose to define one, don't define the other.

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.

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.

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.

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.

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.

Through a combination of helpers, you can add a navigation menu to your theme. Take a look at the example below, which builds a navigation menu from the asset titles of all size 1 text assets.

Example

<ul id="navigation">
  {{#each pop.contents}}
    {{#if_equal layout.size "1"}}
      {{#if_equal type "Text"}}
        <li><a href="#{{{cssify title_raw}}}">{{{strip_html title_raw}}}</a></li>
      {{/if_equal}}
    {{/if_equal}}
  {{/each}}
</ul>

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.

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

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.

Example

<head>
  <meta itemprop="backgroundContainer" content=".columnizer-row:first-child">
  ...

Settings

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 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.

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

@background-color is dark

.asset-title {
  color: #fff;
}

@background-color is bright

.asset-title {
  color: #333;
}

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:

• Preboot.less
• LESS Elements
• LESSHat

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">

These attributes are used like this:

<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.

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;

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.

Assets in Columnizer Regions

• asset-size-1
• asset-size-2
• asset-size-3
• ...and so on for as many sizes as the region allows

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.

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">
  ...

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.

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