Interface patterns

From Koha Wiki

Jump to: navigation, search
Koha > Technical > Development

The staff interface to Koha is complex, with over five hundred templates which are used to display an even greater number of distinct pages. With so many different kinds of interfaces it can be hard to stay consistent. There are, however, some established patterns which template creators and editors try to follow. This document elaborates on these.


The header

Almost every page in the staff client includes the same elements at the top of the page, all contained within a region we can call the header, highlighted in this screenshot:


The header menu

At the top of the header is the header menu, a fixed set of menu items on the left and user/login information on the right:


While it is possible to customize this menu by adding additional links, the contents of the menu are not context-sensitive, staying the same no matter what page you're on.

The header search

Below the header menu is a region common to almost all staff client pages which contains the Koha logo and the header search form:


The header search form contains two or more different search options depending on where you are in the staff client. On pages for which there is no relevant search, a default set of options should be used: Check out, Check in, and Search the catalog (currently in an include called Other sections of the staff client show a different set of search options based on search tools available for that section. On patron related pages a different patron search option is included:


On cataloging pages the assumption is made that circulation functions are less important than a search specific to the cataloging module:


On the system preferences page a search of system preferences is offered:


Note that one of the goals in selecting which searches are offered is to avoid ambiguity. The cataloging search form omits the standard catalog search because the focus is the cataloging search.

"Check out" and "Catalog search" are often the fallback options for pages which include another module-specific search as the primary search option, but they are not required. Other sections omit those options in favor of a set of completely module-specific options. For instance in Acquisitions where "Vendor Search" and "Orders Search" are the only options.

In practice the primary module-specific search is usually placed first and highlighted. In some cases you might find the same set of search options (e.g. Check out, Check in, and Search the catalog) but find that different options are highlighted by default on different pages: Check out is highlighted on circulation-related pages, but Search the catalog is highlighted on some pages, like Tools, where the search form is in not in a "module-specific" state.

Another factor to consider when designing a header search form is simplicity. In the past we have tried to limit the number of search options to three options which seem most relevant to module the user is in. This has expanded to four in some cases (like the patron module). Current practice in Koha's template design is to make the choice to eliminate the least relevant default search option in order to make room for a module-specific search option: "Check in" is omitted in favor of "Search system preferences" in the system preferences interface.


The last element in the header region is the breadcrumbs menu. The breadcrumbs menu provides two functions: First, it orients the user to their "location" in the staff client. It should show where they are (with a repetition of the page title) and what module they're in. In some cases it is possible to offer breadcrumb links to intermediate steps in the user's process. In these cases the menu fulfills the second function, offering users direct links to other pages which may be previous pages in a linear workflow or other relevant pages in the module.


The breadcrumbs does not (and cannot) show the user exactly the links they have taken to arrive at any particular page. Since breadcrumbs are hard-coded for each template, an asumption must be made about a logical hierarchy of links to offer. In acquisitions, the user may have used an order search to find a particular basket, but the breadcrumbs can't know to show a link back to the order search when viewing the basket. Instead it shows links to a hierarchy of pages related to the basket:


When designing breadcrumbs keep in mind paths the user might want to take which are not offered by any other navigation in the interface. Improvements to breadcrumbs menus are often made based on specific usage patterns which are not accommodated.

Errors and messages

When Koha needs to communicate something directly to the user it usually takes one of two forms: an informational message or an error message. Each type is used for specific categories of communications, and each has its own global style.

Informational messages

When Koha needs to communicate information to the user about a transaction, status, or some other non-critical event the information should be displayed using the message style. The markup looks like this:

<div class="dialog message">
  Informational message here

The "dialog" class gives the message its basic orientation and size. The "message" class adds the color which distinguishes it from an error message. Informational messages convey information to the user which does not require action. An informational message doesn't ask the user a question.


An information message displayed when there are no existing authorised values to view.

A message shown when the user follows a link for a bibliographic record which doesn't exist

Error messages

When Koha needs to ask the user a question or block an action an error message should be used. Error messages should be used when Koha requires that the user stop and make a decision or when Koha must stop an operation that the user has initiated. Error message markup looks like this:

<div class="dialog alert">
   Error message here

Again, the "dialog" class gives the message box the same basic style as the information message, but the "alert" class adds a style specific to this type of message.





As defined above an information message conveys "non-blocking" information to the user while error messages display information which blocks an operation or requires the user's input. Not all instances of each type of message are currently consistent with these guidelines, so the templates have room for improvement.

The screenshot snippet below is a good example of the two types of messages displayed in combination:

Screenshot showing example of error and informational messages together

These messages appeared in a situation where a number of things were happening at once. The "Cannot place hold" error message conveys the blocking information: that the hold cannot be placed.  The other, informational messages convey information which may be relevant to the user but which does not interfere with the user being able to complete the task at hand.

Views and Actions

Many of the interactions in the Koha staff client can be divided up into two very general categories: Views and actions. The categories determine how the action is displayed in the interface: in a sidebar tab or in a toolbar.

  • Views are ways of looking at information about a record.
  • Actions are things you can do to a record.

These distinctions are the best defined when looking at patrons or bibliographic records.

Bibliographic Records
Change password
Circ history

Here's a highlighted screenshot as an example:


The distinction between views and actions is a good one to keep in mind when deciding whether to use a link or a button for certain types of interaction. If the interaction can fit into one of those two categories you can group them with existing options.

Page layouts

The Koha staff client uses an older version (2.3.0) of YUI Grids for layout. A newer, more modern grid system would be preferable, but the large number of staff client templates makes a conversion a complicated task.

Common page layouts

YUI grids start with a container that has an ID to define the width:

    1. doc - 750px centered (good for 800x600)
    2. doc2 - 950px centered (good for 1024x768)
    3. doc3 - 100% fluid (good for everybody)
    4. doc4 - 974px fluid (good for 1024x768)

The container also has a class to define how and where a column or sidebar should appear:

  • .yui-t1 - Two columns, narrow on left, 160px
  • .yui-t2 - Two columns, narrow on left, 180px
  • .yui-t3 - Two columns, narrow on left, 300px
  • .yui-t4 - Two columns, narrow on right, 180px
  • .yui-t5 - Two columns, narrow on right, 240px
  • .yui-t6 - Two columns, narrow on right, 300px

Fluid-width page with fixed left-hand sidebar

Examples: Circulation, Patrons, Search results

            <div id="doc3" class="yui-t2"> <!-- 100% width container with 180px left sidebar -->
                <div id="bd">
                    <div id="yui-main">
                        <div class="yui-b">
                            <!-- Main body of the page -->
                    <div class="yui-b">
                        <!-- Left-hand sidebar -->

Variations: <div id="doc3" class="yui-t1"></div>, A 100% width container with 160px sidebar. Examples: Patron details, Saved reports, Calendar.

Fixed-width centered page with no sidebars

Examples: Patron entry, Advanced search, the basic MARC editor

            <div id="doc" class="yui-t7"> <!-- 750px centered container with no sidebar -->
                <div id="bd">
                    <!-- Main body of the page -->

Variations: <div id="doc2" class="yui-t7"></div>, A 950px centered container with no sidebar.

Fluid-width page with no sidebar

Examples: About page, Holds awaiting pickup

            <div id="doc3" class="yui-t7"> <!-- 100% width container with no sidebar -->
                <div id="bd">
                    <div id="yui-main">
                        <!-- Main body of the page -->

Grids within pages

The YUI Grid facilitates grids within the main page layout

  • .yui-g - Standard half grid (and nest again for quarters).
  • .yui-gb - Special grid, 1/3 - 1/3 - 1/3
  • .yui-gc - Special grid, 2/3 - 1/3
  • .yui-gd - Special grid, 1/3 - 2/3
  • .yui-ge - Special grid, 3/4 - 1/4
  • .yui-gf - Special grid, 1/4 - 3/4

Inside the div with a "yui-g" class you add two or more divs with a "yui-u" class:

    <div class="yui-g">
        <div class="yui-u">
            <!-- A 50% width container -->
        <div class="yui-u first">
            <!-- A 50% width container -->

The div with the "first" class will appear first (reading left to right) regardless of source order.

For example, to add a nested 3-column grid in the body of a page with a left-hand sidebar, add a div with a "yui-g" class:

    <div id="doc3" class="yui-t2"> <!-- 100% width container with 180px left sidebar -->
        <div id="bd">
            <div id="yui-main">
                <div class="yui-b">
                    <!-- Main body of the page -->
                    <div class="yui-gb">
                        <div class="yui-u">
                            <!-- A 33% width container -->
                        <div class="yui-u first">
                            <!-- A 33% width container appearing first -->
                        <div class="yui-u">
                            <!-- A 33% width container -->
            <div class="yui-b">
                <!-- Left-hand sidebar -->

Common interface patterns

Many interfaces in Koha follow a similar pattern where data is shown initially in a table. Links are provided for edit and delete views. A toolbar provides additional actions like "New."

The data list view

Using Administration -> Cities and towns as an example, the initial view shows all existing cities in a table:

Screenshot showing the Cities and Towns data list view

Note the order of the elements:

  1. Toolbar
  2. Heading
  3. Table

A suggested revision to the standard for this view: Use Bootstrap-styled buttons when there are only two choices (usually 'Edit' and 'Delete'):

Screenshot showing a data list view with proposed new standard buttons for 'Edit' and 'Delete' actions.

If there are more than two "actions" available in the data list view those actions might be combined in a menu. For example, in Administration -> Funds:

Screenshot showing a pop-up menu of actions in an item list view.

If there is no data to list, a message will be shown:

Screenshot of the message which is shown if there are no cities defined.

In cases like this where the user has the ability to create a new instance of whatever kind of record is to be displayed, a link to the "New" entry form can be displayed in the message.

The 'New' entry form

The data list view will typically include a toolbar with a 'New' button to link to an entry form for creating a new instance of whatever kind of record is being managed. In the Cities and Towns example, this is a new city:

Screenshot showing the Cities and Towns new city entry form.

In this view the toolbar is not displayed, because the user is expected to either submit a completed form or choose the 'Cancel' link to abort the process of creating a new entry.

Form markup

<form class="validated" method="post" action="/cgi-bin/koha/admin/">
    <input type="hidden" value="add_validate" name="op">
    <input type="hidden" value="" name="cityid">
    <fieldset class="rows">
                <label class="required" for="city_name">City: </label>
                <input type="text" class="required" required="required" value="" maxlength="100" size="80" id="city_name" name="city_name">
                <span class="required">Required</span>
                <label for="city_state">State: </label>
                <input type="text" value="" maxlength="100" size="80" id="city_state" name="city_state">
                <label class="required" for="city_zipcode">ZIP/Postal code: </label>
                <input type="text" class="required" required="required" value="" maxlength="20" size="20" id="city_zipcode" name="city_zipcode"> <span class="required">Required</span>
                <label for="city_country">Country: </label>
                <input type="text" value="" maxlength="100" size="80" id="city_country" name="city_country">
    <fieldset class="action">
        <input type="submit" value="Submit">
        <a href="/cgi-bin/koha/admin/" class="cancel">Cancel</a>

The style of this form is created by using a "rows" class on the fieldset element and putting form fields inside an ordered list.

The maxlength attribute should be used when the corresponding table column has a character limit.

Form fields which are required are styled as such:

  • <label> tags have a "required" class: <label class="required" for="city_name">City: </label>
  • <input> and <select> tags have a "required" class and a "required" attribute: <input type="text" class="required" required="required" id="city_name" name="city_name">
  • Required fields are followed by a "Required" hint: <span class="required">Required</span>. Users should not be expected to rely on the color of the label to tell them which fields are required. We do not use an asterisk to denote required fields.

The form is followed by a submit button and a cancel link. Currently most forms in Koha use "Submit" as the label for all submit buttons rather than a label which is tied to specific action, for example "Save city" or "Update city."

Submit buttons are typically standard inputs with type "submit" and no special styling or icons. The cancel link has a "cancel" class which currently adds no style except some extra padding.

The 'Edit' entry form

The edit view displays a form for editing one of the items shown in the data list view. The edit view is typically a separate page showing only the edit form:

Screenshot showing the Cities and Towns edit view.

This view is identical to the 'New' view except that existing data is shown in the form. Note that the first line in the edit form shows data which cannot be edited. Instead of the typical pair of <label> and <input> there is a <span> styled like a label: <span class="label"> followed by the existing data.

Radio buttons and checkboxes

There are two different options for displaying form rows with radio buttons or checkboxes. In the first, the form controls are displayed without a label in the left-hand column:

Screenshot showing the gender selection radio buttons on the patron edit page.

<fieldset class="rows">
        <li class="radio">
            <label><input type="radio" /> Choice 1</label>
            <label><input type="radio" /> Choice 2</label>
            <label><input type="radio" /> Choice 3</label>

In the second version, there is a general label which identifies the choices in the radio buttons or checkboxes:

This screenshot snippet shows the vendor edit form's active and inactive choices.

<fieldset class="rows">
            <label>General label:</label>
            <label class="radio">
                Specific label 1 <input type="radio" />
            <label class="radio">
                Specific label 2 <input type="radio" />

Deletion confirmation

In some interfaces clicking the "Delete" link or button from the data list view will take you to a deletion confirmation page. On this page an "alert" style dialog asks the user to confirm the deletion:

Screenshot of the confirmation dialog shown when deleting a city.

In other interfaces clicking the "Delete" link will trigger a JavaScript confirmation:

JavaScript confirmation shown when deleting a list.

If the user confirms, the entry will be deleted without being taken to a deletion confirmation page.


There are several general categories of buttons in the Koha staff client (including link, input and button elements):

Toolbar buttons

Toolbar buttons are styled using the default Bootstrap style, often with the inclusion of a Font Awesome icon.

The toolbar on the staff client bibliographic detail page.

Buttons in a toolbar might be any combination of inputs, buttons, or links.

A simple example from this toolbar is the "Print" buton:

    <a class="btn btn-default btn-sm" id="printbiblio">
        <i class="fa fa-print"></i> Print

The "btn" class makes the <a> element look like a button. The "btn-default" say it's a standard button. The "btn-sm" class makes the button smaller than the Bootstrap default. The <i> element creates the icon.

See Bootstrap documentation for more.

As covered in #Views_and_Actions, Toolbar buttons should be used for "actions," rather than "views."

Dialog buttons

When the staff client interface displays a (non-JavaScript) dialog, as shown in #Deletion_confirmation, buttons have a distinct style which stems from the container they are in. Dialog buttons do not have Bootstrap classes applied to them. Font Awesome icons should be used to give an indication of the kind of action being performed:

A selection of a confirmation dialog showing example buttons.

<button type="submit" class="deny">
    <i class="fa fa-times"></i> Ignore

Submit buttons

The least "specialized" button in the staff client interface is the generic submit button. This is commonly found at the end of data entry forms, for example in the form for adding a library in Administration -> Libraries and Groups:

The default submit button style in a typical form.

<input type="submit" value="Submit">

The default submit button style in a header search form.

Often the generic submit button has a "submit" class:

<input type="submit" value="Submit" class="submit">

The "submit" class doesn't add any special style. The intention was that consistently adding a "submit" class to submit buttons would aid in customization.

Action buttons in tables

When displaying tabular data, there are often actions associated with each line of data: Edit and delete for instance. As of this writing we are in the process of applying a consistent style to these actions using the Bootstrap button "btn-xs" class:

Action buttons repeated for each table row.

<td class="actions">
    <a class="btn btn-default btn-xs" href="#"><i class="fa fa-pencil"></i> Edit</a>
    <a class="btn btn-default btn-xs" href="#"><i class="fa fa-trash"></i> Delete</a>


Sometimes is useful to display some information in modal dialog, for example short forms or record previews.

We are using modals from Bootstrap 3, see full documentation here.


Basic HTML markup for modals, please note we are class closebtn for close button:

<div class="modal fade" tabindex="-1" role="dialog">
  <div class="modal-dialog" role="document">
    <div class="modal-content">
      <div class="modal-header">
        <button type="button" class="closebtn" data-dismiss="modal" aria-hidden="true">×</button>
        <h4 class="modal-title">Modal title</h4>
      <div class="modal-body">
        <p>Modal body</p>
      <div class="modal-footer">
        <button type="button" class="btn btn-default approve">Save changes</button>
        <button type="button" class="btn btn-default deny" data-dismiss="modal">Cancel</button>
    </div><!-- /.modal-content -->
  </div><!-- /.modal-dialog -->
</div><!-- /.modal -->


Koha uses the jQueryUI tabs widget to create tabbed interfaces.


The markup for a set of tabs includes two main parts: A list of links which will form the tabs and a corresponding set of <div>s which will form the tab contents.

<div id="mytabs" class="toptabs">
            <a href="#first">First</a>
            <a href="#second">Second</a>
            <a href="#third">Third</a>
    <div id="first">
        Tab one content.
    <div id="second">
        Tab one content.
    <div id="third">
        Tab one content.

In the tabs, the links must match the id attribute of the corresponding <div>. The "toptabs" class is required.

In the JavaScript for that template, initialize the tabs this way:

        $(document).ready(function() {

Developer handbook

Personal tools