System Preferences

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: 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 an atomicupdate file (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. Create an atomicupdate file for deleting the preference from the systempreferences table (How to write an atomicupdate file)

Translatability

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

• Getting involved | Development workflow | Bug Reporting Guidelines | RFCs | Plugins | Plugin hooks
• Version Control Using Git | git bz | Commit messages | Sign off on patches | QA Test Tools | How to QA | Debugging in VIM
• Coding Guidelines | Koha Objects | Rest Api HowTo | Coding Guidelines - API | Unit Tests | Continuous Integration | Interface patterns | Database updates | Adding a syspref | Bootstrap and LESS
• Debian Packages | Building Debian Packages | Easy Package Building | Commands
• External: Dashboard | Bugzilla | Schema | perldoc | Jenkins