System Preferences

From Koha Wiki

Jump to: navigation, search
Koha > Technical > Development



Koha system preferences control the way Koha operates.

.pref files

They are defined in specific .pref files which are located in Koha templates hierarchy directory : koha-tmpl/intranet-tmpl/prog/en/modules/admin/preferences. Those are YAML files. There is a file per tab in Koha syspref editor. For example, admin.pref file for Administration preferences or circulation.pref file for circulation related preferences. In each tab, preferences are grouped by purpose. This grouping is defined in the YAML file. Each preference has :

  • A name, which has the same syntax as a variable
  • A type:
    • boolean
    • choices
    • to complete
  • A optional default value
  • A description in plain text which is translatable

Here is for example, a portion of serials.pref :

       - pref: RenewSerialAddsSuggestion
             yes: Add
             no: "Don't add"
       - a suggestion for a biblio when its attached serial is renewed.
       - pref: RoutingSerials
             yes: Add
             no: "Don't add"
       - received serials to the routing list.

Note that you must include a space after the : for values. If you want to use a : in a label, you must escape it by putting quotes around the entire value ( "Blah blah:" ). More at

systemprefences table

System preferences take different values per Koha installation. Those values are stored in a DB table: systempreferences. Here is its structure:

| Field       | Type        | Null | Key | Default | Extra |
| variable    | varchar(50) | NO   | PRI |         |       | 
| value       | text        | YES  |     | NULL    |       | 
| options     | mediumtext  | YES  |     | NULL    |       | 
| explanation | text        | YES  |     | NULL    |       | 
| type        | varchar(20) | YES  |     | NULL    |       | 

option, explanation and type fields are now (since 3.2) obsolete and replaced by .pref files definition.

Adding a new system preference

  1. Add your sysprefs to the appropriate koha-tmpl/intranet-tmpl/prog/en/modules/admin/preferences/foo.pref file.
  2. Add the appropriate sql to installer/data/mysql/mandatory/sysprefs.sql
  3. Create a new file in the installer/data/mysql/atomicupdate/ directory. Whatever its name it will be taken into account when the script will be executed. By convention, it would be something like bug_14242-add_mynewpref_syspref.sql . The release manager will move this code to when the bug is pushed. (How to write an atomicupdate file)

A good practice is to verify the existence of the syspref before you insert it. The easier way is to use the INSERT IGNORE INTO statement. This will avoid the webinstaller to complain if it already exists.

See: Database updates

Removing a system preference

When a system preference is to be deprecated this steps should be followed.

  1. Remove all code that uses the syspref.
  2. Remove all references to the syspref from koha-tmpl/intranet-tmpl/prog/en/modules/admin/preferences/*.pref
  3. Remove all references to the syspref from the file installer/data/mysql/sysprefs.sql.
  4. Add an update to deleting the preference from the systempreferences table.
$DBversion = 'XXX';
if ( CheckVersion($DBversion) ) {
   $dbh->do("DELETE FROM systempreferences WHERE variable='<<YOURPREF>>'");
   print "Upgrade to $DBversion done (Remove deprecated <<YOURPREF>> syspref)\n";
   SetVersion ($DBversion);


System preferences are translatable via standard .po files. English (United States) .pref files are the reference. Text to translate are extracted from .pref files and placed in <lang>-pref.po file.

To avoid difficulties for translators, preferences description must be chose appropriately:

  • Single quote (') and double quotes (") must not be used. Use glyphs: « » ‘ ’ “ ”
  • Any English idiotism should be avoided.
  • Convoluted sentences should be avoided.
  • To be completed by translators based on their experience.

Developer handbook

Personal tools