Koha Templates Style Guide

Koha Templates Style Guide

The following is a style guide for interface design in Koha (creating and maintaining templates).

It addresses both 'Koha Interface Design Theory' and technical questions of how to mark up your HTML code using the 'Koha Conventions'.

References

Jenifer Tidwell Designing Interfaces

Krug, Don't make me think!

Quick Definitions

Just a few definitions so we have some jargon with which to discuss interface design principles:

idiom - an interface 'type' or 'style' that is 'familiar' to users (text editors, forms, games, command lines, spreadsheets). Idioms allow us to design with a familiar set of conventions rather than start from scratch, and users have a head start on understanding the interface because they've seen it before

widget - a small-scale idiom that covers a specific 'control' … say a 'submit' button, or a 'filter at top of page'

pattern - a group of idioms and widgets that show up again and again in the interface

intuitive - when we say something is 'intuitive', we mean it's 'familiar'. “Applications that are easy to use are designed to be familiar” Tidwell, xiii

Finding your way around the Koha templates system

Koha's template system offers a rich environment to make major or minor changes to the look and feel of your Koha system. Understanding the various parts of the system is key to being effective in template creation, modification and maintenance. Templates in Koha are stored in:

koha/koha-tmpl/<interface>-tmpl/<theme>/<language>/

So, for example, the 'prog' templates for the 'staff client' in English language would be located:

koha/koha-tmpl/intranet-tmpl/prog/en/

modules

The modules directory contains the templates parsed by HTML::Template for every module:

<template><language>/modules/

includes

The includes directory stores all includes parsed by HTML::Template

<theme><language>/includes/

Notable, are the new conventions for representing css, js, and xslt files as includes (useful if you need to pass TMPL_VARs to one of these files)

<theme><language>/includes/*.css.inc 
<theme><language>/includes/*.js.inc
<theme><language>/includes/*.xsl.inc

overriding Includes

Several koha users have added support for 'overrides'. The recommended convention is to place overides in the overrides/

css, js, xsl, img, etc.

CSS, JavaScript, XSL and images (anything not parsed by HTML::Template and available in the document root) can be found in:

<theme><language>/css
<theme><language>/js
<theme><language>/xsl
<theme>/img

external libraries

External libraries, such as yui, the 'calendar' code, ext-js, etc, are stored in:

<theme>/lib

TODO: split up themelang into 'theme' and 'lang' variables to distinguish between theme-level and lang-level elements.

typical page markup

Every page contains a standard set of markup elements:


<!-- TMPL_INCLUDE NAME="doc-head-open.inc" -->

<title>Page Title</title>

<!-- TMPL_INCLUDE NAME="doc-head-close.inc" -->

<script type="javascript">Optional embedded javascript</script>

<link rel="stylesheet" type="text/css" href="Optional page-specific styles" />

</head>
<body>

<!-- TMPL_INCLUDE NAME="header.inc" --> (contains top-level navigation, login info, help)

< resident search box > (optional. ex: check out to, search patrons, catalog search, etc)
< breadcrumb navigation > (always begins with "Home &rsaquo;")
< body layout scheme (YUI Grids divs) >

Main body content

< /body layout scheme >

<!-- TMPL_INCLUDE NAME="mainmenu.inc" --> (contains left-hand navigation, facets, or section-specific menu)
<!-- TMPL_INCLUDE NAME="intranet-bottom.inc" -->

The Koha Cascade

This code block illustrates the way that the cascade of CSS (and JavaScript) is applied in Koha


<!-- CSS -->
<!-- LAYOUT -->
<libs>
staff-global.css
<module>
<page>
<widgets>

<!-- COLOR -->
staff-colors.css

<!-- JAVASCRIPT -->
<libs>
staff-global.js
<module>
<page>
<widgets>

Global Search, Subnav/Views, and Toolbars

Circulation

Global Search: circ (active), catalog

Circ-Subnav: (everywhere in this module)

Check In
Transfer
irc reports (it's a list, I don't have it handy)

Patron-Subnav: (only on patron-specific pages)

reading record
holds
fines
details (goes to members page)
modification log

Toolbar:

new (child)
edit (contact, etc.)
add note/message
change password
set permissions
print slip/page (maybe attached to table instead)
renew account
delete

Patrons

Global Search: patrons (active), catalog, circ

Subnav:

Toolbar:

new (drop-down), adult, child, institution, professional

Catalogue

Global Search: none

Subnav:

Toolbar:

Cataloging

Global Search: cataloging search (active), authorities (maybe), serials (maybe)

Subnav:

Toolbar:

new (bib record, pick a framework)

Acquisitions

Global Search: vendors (active), order history

Subnav:

late orders
history search
manage suggestions
parameters

Toolbar:

new supplier

Reports

Global Search: catalog (active), circ

Subnav:

acquisitions wizard
patrons wizard
catalogue wizard
circulation wizard

the rest of the list of reports

Toolbar:

eventually the guided reports will be a wrapper for the reports module and we'll have 'new', etc., tools for reports

Tools

Global Search: tool-specific (active), catalog, circ

Subnav:

the list of tools

Toolbar:

new

Administration

Global Search: admin-specific (active, catalog, circ

Subnav:

the list of admin subnav

Toolbar:

General Markup Guidelines

Dos

Use semantically meaningful XHTML-compliant markup wherever possible:

Close all tags: <input />, <img />, <link />, etc.
Quote all attributes: <input type=“submit” value=“Submit” />
Use lower-case for all tags and attributes
Encode the & symbol as &
Wrap embedded <script> content: <script type=“text/javascript”> / /<![CDATA[ /* embedded script */ / /]]></script>

For block elements, use <div>, not <p>.

For inline elements, use <span>.

Use <li> for all lists of items (navigation, subnav, etc.)

Use tables for tabular data.

Use CSS, not <p> and <br /> to create visual whitespace.

Explicitly state <form> action.

Dont's

Don't use the fieldset tag inappropriately. The fieldset tag is used to group related form elements together with a caption and labels. The caption is created using the legend tag. Don't use the fieldset tag for anything other than form elements.

Don't use the label tag for non-form content. Label tags should reference a specific <input> using this method: <label for=“input-id-attribute”>Label text:</label>. This method allows the user to click the label to place cursor focus in the input field.

Don't embed CSS (via <link> or <style>) anywhere but in the <head>.

Don't use tables for layout purposes, adhere to tableless design except in the case of tabular data.

Avoid embedded Javascript controls via methods like onclick, onfocus, onload, onblur, etc. Events should be established using a javascript library like jquery or YUI based on element ID, class, etc.

If you must use a method like onlick or onfocus, make sure the attribute is in all-lowercase.

StyleSheets

Global Stylesheet

The global stylesheet defines global elements: site title, login info, branch, page color, some table styles for border collapse, padding for table cells and headers, font weight bold for table headers

It also includes styles for global widgets such as:

warning - something you get before you do something (e.g., you must set up budgets before using acquisitions)
error - something you get after you do something (e.g., your login failed)
message - system highlighting information (a note to a patron's account)
dialog - system requires input from user (e.g., do you want to cancel this reserve (after checking a book in))

Breadcrumbs are globally present, but defined at the page level. Their style is specified in the global stylesheet and they appear directly below the global navigation

Global navigation contains the following links: 'Circulation', 'Patrons', 'Catalog', 'More'. Clicking on 'More' reveals a JavaScript drop-down that contains the rest of the modules. 'More' degrades as a link to the mainpage, where a full list of modules is available.

Idioms

two-panel selector

Two side-by-side panels. In one, list of items that can be selected or 'clicked', in the other, the content associated with that item.

Examples:

faceted panel in the catalog search with results list in the right-hand panel

horizontal toolbar

vertical toolbar

iconic palette plus panel

Iconic palette inside of or next to a panel; user clicks on the palette buttons to perform actions on the panel

card stack

Examples:

tabs on the OPAC detail screen

Page Patterns

A pattern is a combination of idioms and widgets, as well as definitions for things like the number of columns in a page and their size. The goal with defining patterns is to identify all of the similar paradigms within Koha that should share markup and stylesheet conventions.

login pattern

Examples:

installer login screen installer/
normal login - auth.tmpl

Global Layout: ?Different than rest of Koha?
Global Color: Same as rest of Koha
Module: None
Page: One Column
Widget: Login Widget

wizard pattern

Examples:

installer
report generator
member entry (can exit after first page?)
? acquisitions: placing an order ?

Global Layout: Same as rest of Koha
Global Color: Same as rest of Koha
Module: Dependent on context
Page: One Column
Widget: ?

Notes: forms with input boxes, buttons

filter + table pattern

Page-defined toolbar for adding new rows, editing rows, deleting rows

Filter at top of page:

should be multi-page to deal with large lists instead of crashing browser
can use a 'browse by alphabet' widget if useful ( like in the case of member entry)
Use an input prompt idiom for the filter input box to create a sentence explaining the purpose of the filter:
- Search by <> for: <input box> sort by: <sort by> <Search Button>

When results come back, original filter still displays at top of page with the term or phrase entered.

Inside the table:

Filter tables should allow resort for some columns, this can be done in javascript using page markup
Each row has a checkbox for selecting that row, or multiple rows, rows that are selected are actionable by clicking on the appropriate action button in the toolbar
- when you click delete, messaging 'are you sure' in javascript … it should degrade but it won't for every page
- don't want duplicate warning
Each row has three actions: view, edit, delete – these are represented using icons inline in the table. The icons have tooltips when you rollover 'Edit' will display, for example

Examples:

advanced search page
viewlog.pl
some canned reports
itemslost.pl (belongs in reports)
cleanborrowers.pl (but no table)
inventory.pl (but extra piece, for uploading)
letters.pl (default page, should be in admin, rename)
news.pl (default page, not a tool, filter needs fixed)
z3950 server (table with filter, actions per row, add button)
printers (do we need?)
authorities-home.pl and cataloging.pl

Note:

Patron and circ searching for patrons will visually look the same (table), the link to detail will go to patron detail if you're in the patron module, and to the issues screen if you're in circulation

form submit

Basic Label/Input pairs grouped into fieldsets
- export MARC record (download form)
- new patron category

Label on top of input (emphasis is on viewing existing content in the input box)
- Personal Information Update on OPAC
- Login form
- Quick Add for Patron Entry Form
- Main Patron Entry Form
- Entering a supplier in Acquisitions
- Enter a new virtual shelf

Two-columns Label/Input (for long, complex forms)

Transaction Forms
- checkin, checkout, transfers

Top-most Search/Filter Form (resident on most pages)

Complex Forms: Advanced Search Form / Reports Form

Forms that have WYSIWYGs

MARC Editor Form → Two flavors one is MARC-based, one has no MARC, skipping for now

Potential Types of Fields:

Boolean
Date/Time Field
File Upload Field
Fixed-Point Field
Integer Field
Label Field
Multi-select Field
Password Field
Rich Label Field
Rich Text Field
Save Data Adapter
Selection Field
String Field
Text Field

Notes on the Patron Entry Form:

  * Salutation should be an authorized value like 'Road Type'

  * Move Flags and Messages to own form

  * Use format date jquery instead of calendar (calendar is too hard to use) (maybe use server-side?), say format of date in tooltip

  * We seem to need two patron entry forms:

'quick add' for libraries like NPL that do member entry on circ desk. This form only has:

  * Name
  * PatronCatagory
  * Username/password
  * Cardnumber

Offer the user the option to complete in the long add

Koha 'long add':

Personal Information
  |-> Identity (Name, DOB, etc.)
  |-> Type

Contact Information
  |-> Address -> Main, Alternate
  |-> Contact -> phone, email, sms, etc.

Library information

* road types * overduerules.pl (should be in admin, should warn if no letter defined) * letters.pl add letter (should be in admin, rename) * news.pl add news * import.pl (belongs in cataloging, upload form, needs enhancements!!) * export.pl (download form) * edit system preferences * z3950 servers (add) * printers (add)

Unfinished Page Patterns

parameters + action + content

* label

calendar select

* holidays.pl (has a filter, chart with legend)

one window drilldown

all frameworks (need breadcrumbs at each level) * authtypes.pl (main page)

matrix

fines and circulation rules

to remove

koha2marclinks.pl ? (should be able to view, but not edit?)

split screen (federated search, and edit)

catalog maintenance (search catalog, reservoir, other targets)

add delete edit

MARC View

authorities detail page, detail page for records, etc.

dashboard

acquisitions home

culdesac

need a back button

* about

two-panel selector

search results page (facets, results)

card stack

system preferences

default MARC editor

Style and Script Controls

There are ways to trigger certain CSS and JavaScript includes by adding their locations to a given perl script. Alternatively, they can be directly included in the template itself (which may be a more readable method).

In each script, there's a section that looks like the following:


my ( $template, $loggedinuser, $cookie ) = get_template_and_user(
    {   
        template_name   => "about.tmpl",
        query           => $query,
        type            => "intranet",
        authnotrequired => 0,
        flagsrequired   => { parameters => 1 },
        debug           => 1,

To use style and script controls on a given page, add the following as needed to the perl script after the above:

        # looks in <themelang>/
        css_libs        =>  [
                                { lib => 'test/path1/lib.css' },
                                { lib => 'test/path2/lib.css' },          
                            ],

        # looks in <themelang>/css/modules/
        css_module      => 'css/modules/<module>.css',

        # looks in <themelang>/css/pages/
        css_page        => '<page>.css', 

        # looks in <themelang>/
        css_widgets     =>  [   
                                { widget => 'test/path1/widget.css' },
                                { widget => 'test/path1/widget.css' },
                            ],

        # looks in <themelang>/
        js_libs         =>  [
                                { lib => 'test/path1/lib.js' },
                                { lib => 'test/path2/lib.js' },
                            ],

        # looks in <themelang>/js/modules/
        js_module       => '<module>.js',

        # looks in <themelang>/js/pages/
        js_page         => '<page>.js',

        # looks in <themelang>/
        js_widgets      =>  [
                                { widget => 'test/path1/widget.js' },
                                { widget => 'test/path2/widget.js' },
                            ],

You can then add the relevant js or css files to the appropriate location for use when the page is loaded. Javascript and CSS can also be linked or embedded in the page <head> by adding it directly to the template. This method should be chosen if the script must reference HTML::Template-processed data.