Bootstrap

Both the Koha staff client and OPAC use Bootstrap, a "frontend toolkit." We use a number of different components provided by Bootstrap, including grids, menus, modals, buttons, etc. As of version 24.11 Koha uses Bootstrap v5.3.3. Bootstrap's documentation is extensive and should be considered the first source for information on its use. Keeping that in mind, this page will cover common usage of Bootstrap components where we might differ from Bootstrap defaults.

Layout

Koha's page layouts use standard Bootstrap breakpoints and the Bootstrap grid in unmodified form. Responsive behavior should be taken into account when designing pages.

Components

Accordion

Bootstrap's Accordion component is used to build vertically collapsing accordions. Examples can be found in Administration on the Table settings page, and in Patrons on the Patrons requesting modifications page.

Accordions in Koha should use the built-in WRAPPER syntax which allows us to centralize the supporting markup. This simplifies Bootstrap upgrades by having only one include file (html_helpers.inc).

<!-- The whole accordion is wrapped in a WRAPPER with a unique ID -->
[% WRAPPER accordion panelgroup_id="accordion container id" %]
    <!-- Each collapsible section is wrapped in an 'accordion_item' WRAPPER -->
    [% WRAPPER accordion_item %]
        <!-- Each collapsible section has its own heading WRAPPER, the content of which is the clickable region -->
        [% WRAPPER accordion_heading panel_id = "panel id" %]
            <!-- The contents of the accordion section heading should be wrapped in <span> to facilitate translation -->
            <span>Clickable panel heading text</span>
        [% END %]
        [% WRAPPER accordion_panel panel_id = "panel id" %]
            <!-- The contents of the accordion section content should be wrapped in markup to facilitate translation -->
            <div>The content of the collapsible panel</div>
        [% END %]
    [% END %]
[% END %]

By default Bootstrap accordions appear with all panels collapsed. If you want to expand a panel on page load you can do so using the ID of the panel (not the heading) to be expanded. In the following example, the page has been designed so that a parameter can be passed to the page for use in expanding a particular panel. The value of the "active" variable in this example would match the "panel_id" in the WRAPPER markup above.

$(document).ready(function(){
    [%- IF ( active ) -%]
        <!-- The template variable "active" containing a unique ID, has been passed -->
        $("#panel-" + [% active | html %] + "_panel").collapse("show");
    [%- ELSE -%]
        <!-- No active section was defined, so we expand the first panel -->
        $(".panel-collapse:eq(0)").collapse("show");
    [%- END -%]
});

Alerts

Bootstrap's Alert component is used to show static messages to the user.

<!-- An informational message uses the "alert-info" class. -->
<div class="alert alert-info">
  Informational message here
</div>

<!-- An error or warning message uses the "alert-warning" class. -->
<div class="alert alert-warning">
   Error message here
</div>

See errors and messages.

Badge

Bootstrap's Badge component is most commonly used to display a count associated with a link. For example, on the bibliographic detail page when there are holds on the record:

<span class="results_summary">
    <span class="label">Holds:</span>
    <!-- An informational badge uses the color class "text-bg-info" -->
    <span class="badge text-bg-info">
        <!-- A badge will often be the link taking the user to the relevant information -->
        <a href="/cgi-bin/koha/reserve/request.pl?biblionumber=123">4</a>
    </span>
</span>

Badges can use any of Bootstrap's theme color class names

Breadcrumb

Bootstrap's Breadcrumb component is used on almost every page in Koha. Like the Accordion component, we have a Template Toolkit WRAPPER defined for it:

<!-- The breadcrumb wrapper is always wrapped in the 'sub-header' include -->
[% WRAPPER 'sub-header.inc' %]
    <!-- We don't pass any parameters to the top-level breadcrumb wrapper. It always has 'breadcrumbs' as the ID -->
    [% WRAPPER breadcrumbs %]
        <!-- Each item in the breadcrumbs menu is wrapped separately -->
        [% WRAPPER breadcrumb_item %]
            <a href="/path/to/module">Module link</a>
        [% END %]
        [% WRAPPER breadcrumb_item %]
            <a href="/path/to/module/page"> Secondary page link </a>
        [% END %]
        <!-- The wrapper for the current page passes the "bc_active" parameter. The text of the breadcrumb is not wrapped in a link -->
        [% WRAPPER breadcrumb_item bc_active= 1 %]
            <span>Current page name</span>
        [% END %]
    [% END #/ WRAPPER breadcrumbs %]
[% END #/ WRAPPER sub-header.inc %]

Buttons

Bootstrap's Button component is used throughout Koha in many different contexts and in many different variations. The "btn" class can be added to <a>, <button>, and <input>.

Page toolbars

The main toolbar on a page has buttons with the class "btn btn-default" and will generally have a Font Awesome icon.

<a class="btn btn-default" id="receive" href="#">
    <i class="fa fa-inbox"></i> Receive shipments
</a>

<button type="button" class="btn btn-default">
    <i class="fa fa-trash-can"></i> Delete vendor
</button>

Submit buttons

The main submit button on a form has the class "btn btn-primary" and will usually not have a Font Awesome icon.

<input type="submit" class="btn btn-primary" value="Submit" />

Table action buttons

Tables of information in the staff interface will often have an "Actions" column in last place in the table for displaying controls. These buttons have the class "btn btn-default btn-xs". The buttons will typically have a Font Awesome icon.

<td class="actions noExport">
    <a class="btn btn-default btn-xs" href="#">
        <i class="fa-solid fa-pencil" aria-hidden="true"></i> Edit
    </a>
    <button type="submit" class="btn btn-default btn-xs">
        <i class="fa fa-trash-can" aria-hidden="true"></i> Delete
    </button>
</td>

Progress

Tooltips