Koha simple theming guide

How to theme Koha

This page is a simple guide on how to theme Koha's OPAC. It is intended to walk you through the process of changing the appearance of Koha's OPAC via system preferences. If you're looking for a more advanced guide to themeing via sysprefs please see the advanced themeing guide page.

Getting there

More > Administration > Global System Preferences > OPAC > Appearance

System preference options

The following is a list of preferences that you will be most likely to work with when themeing a Koha.

• OPACUserCSS - Appearance > OPACUserCSS, allows you to insert and edit inline CSS that will override any existing OPAC styles.
• OpacHeader - Appearance > OpacHeader, allows you to insert stuff such as images into the header region of the OPAC.
• opaccredits - Appearance > OpacCredits, allows you to insert stuff such as images into the footer region of the OPAC.
• OpacMainUserBlock - Appearance > OpacMainUserBlock, allows you to insert stuff such as images into the main section of the OPAC main page.
  • Since 20.05 OpacMainUserBlock system preference is a news block (23794).
• OpacNav, OpacNavBottom - Appearance > OpacNav or OpacNavBottom, typically used for inserting menus in different regions of the OPAC. OpacNav goes along the left and OpacNavBottom along the bottom.

Since Koha 19.05: About: OpacNavRight. [22318] Extend Koha news feature to include other content areas

This enhancement begins work to move system preferences that include displayed text to the ‘News’ module – this allows the user to define text in various languages and add ability for these preferences to show correctly in translated OPACs. Specifically, this patch set moves the ‘OPACNavRight’ preference into the ‘News’ module.

Themeing Koha - a walk through of a basic example

In this section I will walk through a basic example of themeing the OPAC's home page. To start make sure your working environment is set up correctly. If you are working through the kohadevbox environment make sure that in your terminal you are cd'd into your kohadevbox directory, and that vagrant is running and you have ssh'ed into it. Then in your browser navigate to localhost:8080 and 8081. If you are a client with external pages, navigate to your OPAC in one tab, and your staff client in another.

In your staff client navigate to the OPAC system preferences. If you are unsure on how to get there look at the path provided under Getting there. Once you have located the OPAC system preferences scroll down until you find OpacUserCSS. Click on it to expand.

Under OpacUserCSS open a tag for body and set the background to white:

body {
background:#ffffff;
}

Scroll up to OpacMainUserBlock and enter a heading tag with whatever text you want:

<h1>Hello World!</h1>

In OpacUserCSS style the heading you just entered under OpacMainUserBlock:

h1 {
color:black;
text-decoration:bold;
}

Next try changing the standard link colour:

a, a:visited {
color:#3366ff; /* this can be any colour*/
}

The a:visited means that the link will return to the standard colour set in the stylesheet even after it has been clicked on. To change the link colour on mouse over use a:hover

/*change link hover property*/
a:hover {
color:#001a4d;
}

Next we will style the footer - in order to get it to show there needs to be content inside so first up scroll to opaccredits and enter something along the lines of

<p>Insert footer content here</p>

. The footer is a good place to put copyright and contact information if you want to display that on the OPAC. Once you have entered something in opaccredits, return to OpacUserCSS and enter some styles for the footer.

#opaccredits {
background: #84bc01;
background: -moz-linear-gradient(-180deg, #84bc01 0%, #7aae09 32%, #73a30f 64%, #658d1b 100%);
background: -webkit-gradient(left top, right bottom, color-stop(0%, #84bc01), color-stop(32%, #7aae09), color-stop(64%, #73a30f), color-stop(100%, #658d1b));
background: -webkit-linear-gradient(-180deg, #84bc01 0%, #7aae09 32%, #73a30f 64%, #658d1b 100%);
background: -o-linear-gradient(-180deg, #84bc01 0%, #7aae09 32%, #73a30f 64%, #658d1b 100%);
background: -ms-linear-gradient(-180deg, #84bc01 0%, #7aae09 32%, #73a30f 64%, #658d1b 100%);
background: linear-gradient(180deg, #84bc01 0%, #7aae09 32%, #73a30f 64%, #658d1b 100%);
filter: progid:DXImageTransform.Microsoft.gradient( startColorstr='#84bc01', endColorstr='#658d1b', GradientType=1 );
padding: 20px;
color:#fff;
}

I'm using a gradient background here, but a solid colour works just as well. Because the background comes out at a dark green I've changed the font colour to white. The padding just bulks out the footer a bit.

Next style the search box, by removing the background and changing the label colour.

/*style search box*/
.mastheadsearch {
background:none;
}

.mastheadsearch label {
color:#001a4d;
}

Finally, we will change the colour of the top header/navbar.

#header-region, .navbar-inverse .navbar-inner {
background:#5bad3f;
}

You might notice that the dividers keeping the text nicely spaced on the header are still black like the header background was before we changed the colour.

.navbar-inverse .divider-vertical {
    border-left-color: #5bad3f;
    border-right-color: #5bad3f;
}

The text on the header is also now unreadable so we need to change the font colour in order to make in readable.

.cartlabel, .listslabel {
  color: #FFFFFF;
}

#members a {
    color: #fff;
}

I've also chosen to make the logout link a darker red.

#members a.logout {
color:#b30000;
}

final stylesheet

body {
background:#ffffff;
}

h1 {
color:black;
text-decoration:bold;
}

a, a:visited {
color:#3366ff;
}

/*change link hover property*/
a:hover {
color:#001a4d;
}


#opaccredits {
background: #84bc01;
background: -moz-linear-gradient(-180deg, #84bc01 0%, #7aae09 32%, #73a30f 64%, #658d1b 100%);
background: -webkit-gradient(left top, right bottom, color-stop(0%, #84bc01), color-stop(32%, #7aae09), color-stop(64%, #73a30f), color-stop(100%, #658d1b));
background: -webkit-linear-gradient(-180deg, #84bc01 0%, #7aae09 32%, #73a30f 64%, #658d1b 100%);
background: -o-linear-gradient(-180deg, #84bc01 0%, #7aae09 32%, #73a30f 64%, #658d1b 100%);
background: -ms-linear-gradient(-180deg, #84bc01 0%, #7aae09 32%, #73a30f 64%, #658d1b 100%);
background: linear-gradient(180deg, #84bc01 0%, #7aae09 32%, #73a30f 64%, #658d1b 100%);
filter: progid:DXImageTransform.Microsoft.gradient( startColorstr='#84bc01', endColorstr='#658d1b', GradientType=1 );
padding: 20px;
color:#fff;

}

.mastheadsearch {
background:none;
}

.mastheadsearch label {
color:#001a4d;
}

#opacheader {
background:none;
}

#header-region, .navbar-inverse .navbar-inner {
background:#5bad3f;
}

.navbar-inverse .divider-vertical {
    border-left-color: #5bad3f;
    border-right-color: #5bad3f;
}

.cartlabel, .listslabel {
  color: #FFFFFF;
}

#members a {
    color: #fff;
}

#members a.logout {
color:#b30000;
}

Final result

Error creating thumbnail: Unable to save thumbnail to destination

Tips & Tricks

• Inspect element is your friend - if you're not sure about what element you're supposed to be styling use inspect element to take a look at figure it out. Right click > inspect element or F12. Also useful for troubleshooting CSS issues

• Use ctrl+A if you need to select everything

• Use ctrl+F within a system preference instead of scrolling through all the content to find something

• If you want to use a gradient background then it can be helpful to use a generator which helps you to sort your colours, the direction of the gradient and get a look at it before implementing it in your stylesheet. I mostly use http://www.cssmatic.com/gradient-generator but there are heaps of great ones out there.

• If you are changing colours in CSS and you want to use a colour that isn't one of the basic ones I recommend using a hex code/ html colour code picker. W3schools has a good one: http://www.w3schools.com/colors/colors_picker.asp

See also

• OPAC regions
• HTML & CSS Library