Community wiki

Community wiki
How to hook into Admin and Preferences


Preferences are are used to store settings on a per user basis.
Admins can give defaults and force preferences to certain values (the users can't change and does not get shown).
Preferences can have more descriptive helptexts which get shown when the user clicks on [Help] or has helptexts as default enabled in his prefs.

How to enable an app to use preferences and specialy the user/default/forced tabs ?

You need to setup 2 files / hooks for your applications:

1. <app>/inc/ This file defines a Section for your app in the users preferences.
// Only Modify the $file variables.....
$file = array(
'Preferences' => $GLOBALS['phpgw']->link('/preferences/preferences.php','appname='.$appname),
'Grant Access' => $GLOBALS['phpgw']->link('/index.php','menuaction=preferences.uiaclprefs.index&acl_app='.$appname),
'Edit Categories' => $GLOBALS['phpgw']->link('/index.php','menuaction=preferences.uicategories.index&cats_app=' . $appname . &cats_level=True&global_cats=True')
//Do not modify below this line
Cause you can skip the Grant Access and Edit Categories sections, if you dont use ACL and/or Categories.
Please note the display_section-call has only 2 parameters from 0.9.16 on, as the app-title is generated by the applications class and placed in $GLOBALS['phpgw_info']['apps'][<app>]['title'] to be accessed by all apps.

2. <app>/inc/ This file defines the certain input-fields with labels, helptexts, names and defaults for your preferences.

The 3 types of prefs (user/default/forced) are handled by the preferences-app, you dont have to care.
All input-fields have min. two necessary and more optional parameters:
  1. label is displayed in front of the input field. Dont use a lang()-call on it, thats done by the prefs itself.
  2. name is a string under which u will later find the preference in $GLOBALS['phpgw_info']['user']['preferences'][<app>][<name>]
  3. helptext optional, if helptexts are availible, a button is shown for the user to switch them on/off
  4. default a default-value (only for the user-prefs and not for passwords)
Some input types have more params availible, see there.

This are the types of input-fields availible:
  • Inputboxes: The are for entering strings and can have 2 optional parameters length and max-length
create_input_box('Enter prefix (max. 40 chars)','prefix','long help text','phpgw_',20,40);
  • Checkboxes: The value is either '1' or '0' which evaluates to True and False in php. You can't have '' as this cant be set as default or forced preference !
create_check_box('Show on main screen','homeShowEvents','long help text',1);
  • Selectboxes: Beside the 4 standard params, the selectboxes have a 5 prameter which is an array with value - label pairs.
The label is shown in the selectbox and the value is returned as preference when the label is selected.
create_select_box('Default Filter for InfoLog','defaultFilter',array('own' => 'own Items','others' => 'other peoples stuff'),'long help text','own');
(Please note the array with the options is the 3. parameter, helptext and default are following as 4. and 5. parameter !!!)
  • Textarea: The are for entering a bigger, multiline Text. They have 2 extra parameters rows and cols:
create_text_area('Signature','sig','long help text','--',4,40);
  • Passwordbox: it hides its content by displaying asterixes while entering and an empty field (which is not saved) while updateing.
create_password_box('Password (max. 12 chars)','password','choose a good one',12,12);
  • Headers: You can have one or more header-lines with a descriptive text as a kind of paragraph headings. They are in the table-header-color and in bold writeing. To do so call the function show_list(lang('Headertext')); after (!) each paragraph. If you dont call it, it is called automaticaly at the end and displays and empty header-line.

3. As all hooks they have to be registered in <app>/setup/ (only the hooks part is shown here):
$setup_info[<app>]['hooks'][] = 'preferences';
$setup_info[<app>]['hooks'][] = 'settings';
Hooks get installed whit the app by setup or when you manualy call Admin / Find and Register all Application Hooks.

Proposal: Changes for Preferences

In short: A new column app_name should be add to phpgw_preferences, to allow apps to set defaults and forced prefs (to not show all possible prefs after a new install) via their <app>/setup/

Administration / Site configuration

The Site configuration stores site-wide applications settings and is only accessible by Admins.
The format is the same as for the hook_preferences, but its called <app>/inc/ Here is an example:
   $file = Array(
      'Site configuration' => $GLOBALS['phpgw']->link('/index.php',array(
         'menuaction' => 'admin.uiconfig.admin',
         'appname'    => $appname
      'Global Categories'  => $GLOBALS['phpgw']->link('/index.php',array(
         'menuaction' => 'admin.uicategories.index',
         'appname'    => $appname,
         'global_cats'=> 'True'
   //Do not modify below this line

Again you dont need the Global Categories if your app does not use Categories and you can use your own function if for the site-config if your app has special requirements, you can realice with the existing with uiconfig which uses a old phplib-template (atm. you should look for the config.tpl of one of the apps).
Please note the display_section-call has only 2 parameters from 0.9.16 on, as the app-title is generated by the applications class.

If you have addition please add them here or mail them to ralfbecker

Back to eGroupWare / DeveloperDocs
You are here