Support Center

About Koken

This Help Center provides support for Koken, a free content management system designed for photographers, artists and designers.

Using Pillar

Using Pillar

Last Updated: Sep 03, 2014 03:08PM EDT

Pillar is a JavaScript grid layout library we developed to create mosaic content layouts. Images are ordered left-to-right across a series of fluid columns, aligned flush to each edge, and evenly spaced apart. Pillar is the engine behind the mosaic layouts you see in our Axis, Madison and Regale themes.

How to setup Pillar

Let's start using Pillar in a Lens template to make a simple grid layout. We're going to use the contents.lens template which displays the most recently published images and videos.

First, add Pillar's library to the <head> region of the template. Pillar is built-in to Koken already, so anywhere between the opening and closing <head> tags copy/paste the following:

<koken:asset file="pillar.js" common="true" />

Pillar's library will then be loaded into the template.

Next, create some markup for Pillar to work with. We need one parent div plus child divs for each image/video output by <koken:loop>.

<!-- Loads images and videos in contents.lens -->
<koken:load>
    <!-- Parent element for the whole grid -->
    <div id="kgrid">
        <!-- Loop over every returned item -->
        <koken:loop>
            <!-- Publish a medium-sized image for each -->
            <div class="kgrid_item">
                <koken:img preset="medium" lazy="true" />
            </div>
        </koken:loop>
    </div>
</koken:load>

We now need style markup in the theme's style sheet (css/settings.css.lens) that initially hides the Pillar items and makes the images scale responsively.

.kgrid_item {
    /* Hides each medium sized image */
    display:none;
}
.kgrid_item img {
    /* Responsive magic */
    max-width:100%;
    height:auto;
}

Next step uses JavaScript to fire up Pillar. Add the following anywhere after your layout markup in contents.lens:

<script>
    $(function() {
        $('#kgrid').pillar({
            items: '.kgrid_item'
        });
    });
</script>

Save and reload the document. Assuming all went well you should see content in a three-column mosaic grid inside the #kgrid element.

Assigning dimensions

Pillar automatically scales to fill the entire width of its target element. The columns created by Pillar inside the target element are fluid and expand and contract their widths similar to an HTML table. To control the overall width of the Pillar grid you assign a width to its target element, like so:

<style>
    #kgrid {
        width:960px;
    }
</style>

To control the width of the interior columns you increase or decrease the number of columns Pillar creates. We'll explain that part next as we look at how properties are assigned.

Assigning properties

Pillar provides a number of configurable settings. Here's the full range of settings and their default values.

<script>
    $(function() {
        $('#kgrid').pillar({
            items: '.kgrid_item',
            spacing: 10, // Amount of space between each grid item
            gutter: 0, // Margin on the left and right edges of the grid
            flush: false, // Makes first and last column flush with container edge
            columns: {
                'max': 3 // Number of columns
            },
            responsiveHold: true, // Controls whether image size calculations occur before (false) or after (true) grid creation
            variability: 'none', // Creates grid columns with variable widths. Options: 'random', 'odd' and 'even'
            variability_amt: 0, // Percentage of variable width
            variabilityOverride: 2, // Minimum number of columns needed for variability
            balanceColumns: true // Controls whether items are moved at the bottom of the grid for a more even bottom edge.
        });
    });
</script>

Modifying columns

The columns object allows you to control the number of columns Pillar creates at varying screen width breakpoints. Without columns, Pillar creates a three column grid, and the grid stays at three columns across all screen sizes.

Let's enhance this by displaying more columns on desktops and fewer columns on mobile devices.

<script>
    $(function() {
        $('#kgrid').pillar({
            items: '.kgrid_item',
            columns: {
                '479': 1,
                '767': 2,
                '959': 3,
                'max': 5
            }
        });
    });
</script>

Each number represents the browser width breakpoint (similar to media queries in CSS) that will trigger the smaller column size. In our example above, one column will be used on mobile phones in portrait orientation, two columns on mobile phones in landscape, three columns on tablets in portrait, and finally five columns for every screen size larger than a tablet.

Note that these are just example breakpoints. Include as many or as few as you want. Just make sure you always include max when assigning columns so Pillar knows how many columns you want by default.

Events

Pillar broadcasts events to let you know when things happen. The example below taps into each available event:

<script>
    $(function() {
        $('#kgrid').pillar({
            items: '.kgrid_item',
            imagesLoaded: function() {
                // Fires with each successful image load
            },
            viewportChange: function() {
                // Fires when browser viewport changes
            }
        });
    });
</script>

Let's take a look at an example. In the following we use the imagesLoaded event to assign a .loaded class to the parent element of each image when the image loads successfully.

<script>
    $(function() {
        $('#kgrid').pillar({
            items: '.kgrid_item',
            imagesLoaded: function() {
                $(this).closest('.kgrid_item').addClass('loaded')
            }
        });
    });
</script>
support@koken.me
http://assets3.desk.com/
false
koken
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
false
Invalid characters found
/customer/en/portal/articles/autocomplete