Bootstrap OPAC

As of Koha 3.14 there is a new OPAC theme, known in the staff client's system preferences as bootstrap. This is a responsive theme based on the Bootstrap framework. As of Oct. 2013 we use version 2.3.1. The theme is responsive in that the layout of the OPAC adapts fluidly to changes in the browser viewport size, making it usable on devices with varying screen sizes.

Update: From Koha 20.11 Upgrade Notes: [20168] Update of the OPAC bootstrap template to bootstrap v4

How it works

The theme works by using CSS media queries. The Koha bootstrap theme extends the number of breakpoints included by default in the Bootstrap framework to make it work well with Koha's page layouts. Media queries allow the CSS to define specific styling rules based on the viewport size:

@media only screen and (min-width: 0px) and (max-width: 304px) {
    /* Screens between 0 and 304 pixels wide */
    input,
    select,
    textarea {
        width : auto;
        max-width : 11em;
    }
}

This CSS rule applies only when the browser viewport is between 0 and 304 pixels wide. In this case 304 pixels is the breakpoint, the point at which the styling rules change. The bootstrap theme has several major breakpoints:

• Between 0 and 390 pixels
• Between 342 and 479 pixels
• Between 480 and 608 pixels
• Between 608 and 767 pixels
• Between 768 and 984 pixels
• Above 984 pixels

These breakpoints were not designed to work with any particular hardware screen size. Instead, they are intended to make the OPAC layout look correct at varying sizes. There are a few other finer-grained breakpoints defined in the CSS but the ones listed above are the major ones.

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>

There are built-in CSS directives to add debugging output to the screen for testing purposes.

Using media queries in customizations

If you add HTML content to any of the various system preferences you may need to use media queries to make that content flow nicely among varying screen sizes. Whichever OPAC CSS customization option you use ( opaccolorstylesheet, opaclayoutstylesheet, or OPACUserCSS), you might want to use this boilerplate set of media queries to help you:

@media only screen and (min-width: 0px) and (max-width: 390px){
    /* Screens between 0 and 390 pixels wide */
    /* Add custom CSS here */
}
@media only screen and (min-width: 342px) and (max-width: 479px) {
    /* Screens between 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 */
}

You will not necessarily need to define special rules for each of those circumstances. Add as little custom CSS as is required to get the result you want.

Layout options

The Bootstrap framework offers some built-in CSS grid options for creating flexible layouts in areas like opacheader and OpacMainUserBlock. The Bootstrap scaffolding page offers a good quick introduction to the markup. To get a sense for what is possible you can try adding this block of HTML to your OpacMainUserBlock system preference:

<style type="text/css">.showgrid { padding:1em;background-color:#EEE;border:1px solid #CCC; } </style>
  <div class="row-fluid">
    <div class="span3"><div class="showgrid">3</div></div>
    <div class="span3"><div class="showgrid">3</div></div>
    <div class="span3"><div class="showgrid">3</div></div>
    <div class="span3"><div class="showgrid">3</div></div>
  </div>

  <div class="row-fluid">
    <div class="span4"><div class="showgrid">4</div></div>
    <div class="span4"><div class="showgrid">4</div></div>
    <div class="span4"><div class="showgrid">4</div></div>
  </div>

  <div class="row-fluid">
    <div class="span6"><div class="showgrid">6</div></div>
    <div class="span6"><div class="showgrid">6</div></div>
  </div>

  <div class="row-fluid">
    <div class="span12"><div class="showgrid">12</div></div>
  </div>

The <style> block is used there to make the grid elements clear in the example. Note that even in this block of HTML which is embedded within the page's existing grid, the grid offers 12 columns which can be combined into various sets adding up to 12.

While testing your OPAC with this HTML in OpacMainUserBlock, note that as you change the size of your browser window or view the page in smaller-screened devices the grid columns change from being side by side on larger viewports to one after the other on smaller screens. This flow is controled by the default Bootstrap framework's grid CSS and is unrelated to the bootstrap theme's CSS.