YUI Grids and the Koha OPAC

Koha uses the Yahoo! UI Library Grids CSS framework for both the OPAC and the staff client. When we revamped the Koha interface for 3.0 the Grids framework was chosen because it would simply the process of structuring pages while giving us a pretty good selection of possible layouts.

A nice feature of the Grids framework is that you can control the layout of your page with relatively minor changes in markup. Here’s an example for one of the basic layouts:

[sourcecode language=”html”]

Main Content



You can see that YUI’s Grids framework suffers from the same problem a lot of CSS frameworks  have: the class names are pretty nonsensical if you’re not used to them. I consider this to be par for the course: Better that they be nonsensical than have semantic-sounding names which aren’t appropriate for your actual page structure.

How does the framework make it easy for us to change page layouts? I’ve put together a simple example. This example uses JavaScript to swap out one class name. Try it and see how much can change based on one class name:


Click to try the demo

The above example shows how the “primary” page structure can be changed. I say primary because you can only choose one of those layouts at a time. If you want to have additional columns or blocks within that layout you can use “grids” and “units” within that main page structure:

Just like with the page structure, there is a set of pre-defined grid structures you can use within your page. The simplest is a set of two equal-width containers:

[sourcecode language=”html”]

First grid unit

Second grid unit


Just like with the page structure example, a change to the grid’s class name can affect the layout of the units within it. Notice that the grid/unit structure is changing within the page structure we defined before: a single main block with a left-hand sidebar:

Click the try the demo

Click the try the demo

The power of the framework’s grid/unit structure really comes into play when you start nesting grids within grids. Start with a grid which creates two equal columns, and then nest the same two-column grid within each of those columns:

[sourcecode language=”html”]

Unit one, sub-unit one

Unit one, sub-unit two

Unit two, sub-unit one

Unit two, sub-unit two


In the markup above, instead of nesting a unit (‘<div class=”yui-u”>’) inside a grid (‘<div class=”yui-g”>’), we’re nesting a grid inside a grid. The containing grid can still be altered to change the layout of the units inside it:

Click to try demo

Click to try demo

The Koha OPAC’s grid structure

How is this implemented in the Koha OPAC? Koha has to take advantage of  the Grids framework’s flexibility when obeying different conditions in the OPAC. Take, for example, the main page of the OPAC. There are four possible layouts the user might see based on state and system preferences:


No OpacNav, not logged in


No OpacNav, logged in


OpacNav, not logged in


OpacNav, logged in

Using some logic in the Koha templates, the layout can be easily altered based on each of those conditions. And because the Grids framework makes it so easy to switch between those different layouts, the template can be much simpler:

[sourcecode language=”html”]


The template logic can check one condition (whether the OpacNav system preference is populated) and alter the page layout accordingly.

What does this mean to me?

Unless you’re hacking Koha templates you won’t many opportunities to build your own grids. However, there are a couple of instance where you might want to try it, and I’ll talk about that in my next post.

1 thought on “YUI Grids and the Koha OPAC

Leave a Reply

Your email address will not be published.