System Preferences

From Koha Wiki

Principles

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 :

Serials:
   -
       - pref: RenewSerialAddsSuggestion
         choices:
             yes: Add
             no: "Don't add"
       - a suggestion for a biblio when its attached serial is renewed.
   -
       - pref: RoutingSerials
         choices:
             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 http://en.wikipedia.org/wiki/YAML

systemprefences table

System preferences take different values per Koha installation. Those values are stored in a DB table: systemepreferences. 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/sysprefs.sql
3. Update installer/data/mysql/updatedatabase.pl to insert your new pref in the systempreferences table. Search for FUNCTIONS in the file and add something similar to the code below just before that. Note the XXX. The release manager will be the one that assigns the correct DB version number. <<YOURINSERT>> should match the insert line you provided in installer/data/mysql/sysprefs.sql and <<YOURPREF>>, well, your new preference :-D

$DBversion = 'XXX';
if (C4::Context->preference("Version") < TransformToNum($DBversion)) {
   $dbh->do("<<YOURINSERT>>");
   print "Upgrade to $DBversion done (Add <<YOURPREF>> syspref)\n";
   SetVersion ($DBversion);
}

Translatability

System preferences are translatable via standard .po files. English .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.