A New OPAC Theme: Bootstrap

As of Koha 3.14 the OPAC has a new default theme: Bootstrap. It’s a theme I developed with the intention of offering a flexible, modern, and responsive theme option for Koha libraries. It takes as its visual basis the CCSR theme, added in 3.10. However, it greatly expands the catalog’s mobile-friendliness over the CCSR theme.

The Bootstrap theme is so named because it uses the Bootstrap framework, a set of JavaScript and Cascading Style Sheet tools for use by web developers to quickly and easily add functionality to sites. Bootstrap helps web developers do things like add menus, dialogs, tooltips, etc. Bootstrap also brings some improved default styling to buttons and forms.

Like the CCSR theme, the Bootstrap CSS framework offers something called responsiveness. This means that when the size of your viewport (for instance, the browser window) changes, the layout of the page changes in response. With a desktop browser you can see this by resizing the browser window. Users with mobile devices of varying sizes will see a layout more closely tailored to the size of the screen on their device.

In the CCSR theme there is only one breakpoint. Breakpoints are the pixel dimensions at which the layout changes. When browsing a catalog which uses the CCSR theme, if the viewport size is below 700 pixels the layout changes to accommodate the smaller screen.

Bootstrap offers a few more breakpoints. If you’re reading this in a desktop browser you can view this demo page and resize your browser window to see the effects on the page layout. In Bootstrap there are three primary breakpoints, for large, medium, and small screens.

Koha’s new Bootstrap theme expands on these default breakpoints by adding a few more which are tuned to the layout of the OPAC.

Customization

The Bootstrap theme was designed to be just as flexible for customization as the old default theme. All the customizable regions are there. The same options are available for adding custom CSS and JavaScript. However, the responsive nature of the theme adds some new complications.

If you’re adding content to a region like opacheader or OpacMainUserBlock you’ll need to keep in mind that your content should respond comfortably to the same range of breakpoints that the rest of the catalog does. If you’re simply adding text this isn’t a problem because text flows naturally no matter the page width. If you’re adding something more complicated like images or navigation menus it will require some additional testing.

If you find your custom content is not flowing nicely at multiple screen sizes you can try tailoring that content with CSS using the same major breakpoints which are built into the Bootstrap theme:

@media only screen and (min-width: 0px) and (max-width: 390px){
/* Screens bewteen 0 and 390 pixels wide */
/* Add custom CSS here */
}
@media only screen and (min-width: 342px) and (max-width: 479px) {
/* Screens bewteen 342 and 479 pixels wide */
/* Add custom CSS here */
}
@media only screen and (min-width: 480px) and (max-width: 608px) {
/* Screens between 480 and 608 pixels wide */
/* Add custom CSS here */
}
@media only screen and (min-width: 608px) and (max-width: 767px) {
/* Screens between 608 and 767 pixels wide */
/* Add custom CSS here */
}
@media only screen and (min-width: 768px) and (max-width: 984px) {
/* Screens between 768 and 984 pixels wide */
/* Add custom CSS here */
}
@media only screen and (min-width: 984px) {
/* Screens above 969 pixels wide */
/* Add custom CSS here */
}

If you would like to get visual feedback in the Bootstrap OPAC about which media queries are being applied, add this HTML to the opacheader system preference:

<div id="oh"></div>

Some examples

One of the more common items to customize in the previous default OPAC theme was the logo. My first post here was on Customizing Koha 3’s OPAC logo. The Bootstrap theme no longer has an area designed specifically for a logo. The main search bar area takes up the full width of the screen. This makes it more adaptable to various screen sizes.

opac-main-search-bar-full

There is a Koha logo in the “nav bar” region at the very top of the screen which could be customized using CSS, but it’s quite small and disappears at narrower screen widths.

The opacheader region (customizable via system preferences) will probably be the primary customization option for adding logos, banners, custom top-level navigation, etc.

Image banner

A simple option is to add an image to the opacheader region. This is a simple option because the built-in CSS for images allows an image banner to naturally resize to match the browser width. This method uses the browser’s built-in image resizing algorithm.

In your opacheader system preference:

<img alt="Your Library Name" src="http://yourlibrary.example.com/path/to/your/image.png" />

The result is fully-adaptable to various screen sizes.

Tabbed navigation

As an example of some  custom content which might require more complex CSS customization at varying screen sizes let’s look at an example with tabbed navigation.  Here’s the code we’ll start with:

In OPACUserCSS

#opacheader {
padding : 10px 10px 0 10px;
border-bottom : 1px solid #666;
}
#opacheader ul {
margin-bottom : 0;
}
#opacheader li {
display: inline;
}
#opacheader li a {
font-size: 125%;
display: inline-block;
border : 1px solid #666;
border-bottom-width: 0;
padding : 5px 15px 5px 15px;
background-color : #FFF;
border-radius : 5px 5px 0 0;
}

In opacheader:

<ul>
<li><a href="#">About</a></li>
<li><a href="#">Services</a></li>
<li><a href="#">Collections</a></li>
<li><a href="#">Research</a></li>
<li><a href="#">Events</a></li>
</ul>

At the default browser font size/zoom setting these tabs work with a viewport width down to about 607 pixels wide:

opac-header-tabs-607

Below that width the tabs start to wrap in an awkward way:

opac-header-tabs-319

Here’s where the use of CSS media queries can help us out. Let’s say we determine that the layout breaks at 600 pixels wide (a browser extension like Web Developer Toolbar can help us find the correct number). Let’s write a media query which targets a browser window which is narrower than 600 pixels wide:

@media only screen and (max-width: 600px) {
/* Screens below pixels wide */
#opacheader {
text-align : center;
}
#opacheader li a {
font-size : 110%;
border-bottom-width : 1px;
border-radius: 5px;
margin : 4px;
}
}

We append that CSS to the CSS already in OPACUserCSS and test:

opac-header-tabs-responsive-352

Now the tabs are styled one way when the screen width is above 600 pixels, and another when the width is below 600 pixels.

I hope this example gives you a sense of what is possible when it comes to customization in the new theme. Planning your customizations for more than one screen width can be time-consuming, and lots of trial and error will be involved. The outcome, however, is a site which will be much more broadly usable.

7 Responses to “A New OPAC Theme: Bootstrap”

  1. SlyzertVoltrond Says:

    Thanks a lot for this detailed guide, Owen. Extremely helpful for a web noob like me.

  2. Viktor Says:

    Hi! Thanks for this great guide, and even more so for creating the awesome Boostrap theme!

    The tabs you showcase in the post made me think of the TinyCMS-functionality. Do you know if this is still a valid way of using Koha as a CMS with the Boostrap theme? Or should one rather resort to just creating pages using the standard Opac look with the required content, placing them on the server and linking those nice tabs to those pages?

    Kind regards/Viktor

  3. oleonard Says:

    Viktor, I don’t know much about Koha as a CMS. No one has done any development on that feature in quite a while, so I don’t know if it’s keeping up with all the other changes in Koha. It would be a good question to ask on the mailing list.

  4. Nicole Says:

    Owen,

    Is there a way to make it so that the tabs go away completely when on a mobile display? I know it sounds crazy, but let’s say the links are just to canned searches and you don’t want them cluttering up the small display – how would we have them disappear on mobile but be tabs on the regular screen?

    Thanks
    Nicole

  5. oleonard Says:

    Of course, Nicole. You just have to choose how to define “mobile” and apply the appropriate style for that pixel width:

    @media only screen and (max-width: 600px) {
    /* Screens below 600 pixels wide */
    #opacheader {
    display : none;
    }
    }

  6. Viktor Says:

    If someone drops by from a search engine – The CMS-functions I mentioned above is working quite well. Indrail Das Gupta has updated the instructions on the wiki to work with with Bootstrap and I can confirm that it’s working. Indrail seems to be working on a patch for cleaning things up so you can use an graphical editor for creating pages.

  7. Alyssa Gono Says:

    Hi..I had my koha bootstrap theme turn on. But why doesnt work in opacnav, opacnavright and opacmainuserblock. It only works in poacheader.

Leave a Reply


Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported.