jPref: using application preferences - Jelix 1.5 Manual

− Table of content

jPref
- Configuration
- Usage
Admin interface for jPref

jPref ¶

jPref is a simple class allowing to save and retrieve some preferences by your application. By "preferences", we mean some options that can be changed by the user or that can be change during the life of the application. Options of defaultconfig.ini.php and other are technical preferences that don't supposed to change.

Configuration ¶

jPref is a class provided by the "jpref" module. Activate it in your configuration:


[modules]
jpref.access = 1

And run the application installer.

jPref is a class that use jKVDb. So to use jPref, you just have to define a profile for jkvdb, having "jpref" as name.

In your profiles.ini.php:


[jkvdb:jpref]

To know more about configuration of jKvdb, see its documentation.

Usage ¶

jPref::get($key): to retrieve a preference.
jPref::set($key, $value, $ttl): so modify/save a preference.

Example :



jPref::set('nb.items.per.page', 20);

$val = jPref::get('nb.items.per.page');
// $val contains 20

Admin interface for jPref ¶

A module jpref_admin is provided, to manage preferences from the administration interface. Pages are directly accessible from the "System" menu of master_admin.

However you should fill the file var/config/preferences.ini.php to add preferences that are editable, and how : their label, default value, rights to read and modify...

Declaring a preference ¶

You need to declare the preference only if you want to manage it from jpref_admin (it is the case most of time, or consider to put the parameter into defaultconfig.ini.php).

In the preferences.ini.php, you have a section for each preferences, with the prefix "pref:" :


[pref:preference.name]
; "string" | "integer" | "boolean" | "decimal" (défaut string)
type =
; locale key for the label
locale =
; preference group (see below)
group =
; jAcl2 subject corresponding to the right to read the preference value
read_acl_subject =
; jAcl2 subject corresponding to the right to modify the preference value
write_acl_subject =
; default value
default_value =

Note: each parameters are optional.

read_acl_subject and write_acl_subject allow to restrict the access to preferences. Some preferences may not be accessible only by administrator of the web site for example. So you should defines some rights in jAcl2, and indicate here the corresponding "subjects". If read_acl_subject and write_acl_subject are not filled, the preference can be modified by any user (except if the user has not the right "jprefs.prefs.list").

Declaring a preferences group ¶

Your preferences can be grouped, so it can be easier to manage them. You can have a group per module for example.

In your preferences.ini.php, declare a section with a prefix "group:". A section contains the label of the group, and an order value.


[group:nom.syteme.de.la.pref]
; locale key of the label
locale =
; display order
order =