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

Progress

Tooltips