[Sommaire] [Imprimer]

   1  
   2  eGroupWare admin/config.php
   3  
   4  Abstract
   5  
   6  A brief introduction to writing hooks and templates for any application to use
   7  this admin interface, by Miles Lott <milosch@groupwhere.org> Dec 22, 2001.
   8  
   9  1 Files
  10  
  11  1.1 config.tpl (required)
  12  
  13  In your application/templates/default directory, create a
  14  new template file named 'config.tpl'. This will be included
  15  by config.php and used to draw the page. This template should
  16  include a POST method form. The following template tags
  17  may be used:
  18  
  19  1. {action_url} - A phpgw->link to config.php will be inserted.
  20  2. {title} - This will be parsed to display 'Site Configuration'.
  21  3. {th_bg},{th_text},{row_on},{row_off} - Replaced with the current theme colors.
  22  
  23  and the following special types:
  24  
  25  1. {lang_XXX} - Filled with lang('XXX').
  26  2. {value_XXX} - Filled with the current value of config item 'XXX'.
  27  3. {selected_XXX} - set to '', or ' selected' if an option value is current.
  28  4. {hook_XXX} - Calls a function named XXX (will be discussed later).
  29  
  30  Following is an example from the addressbook application:
  31  
  32  <form method="POST" action="{action_url}">
  33  <table border="0" align="center">
  34   <tr bgcolor="{th_bg}">
  35    <td colspan="2"><font color="{th_text}">&nbsp;<b>{title}</b></font></td>
  36   </tr> <tr bgcolor="{th_err}">
  37    <td colspan="2">&nbsp;<b>{error}</b></font></td>
  38   </tr>
  39  <!-- END header -->
  40  
  41  <!-- BEGIN body -->
  42   <tr bgcolor="{row_on}">
  43    <td colspan="2">&nbsp;</td>
  44   </tr>
  45   <tr bgcolor="{row_off}">
  46    <td colspan="2">&nbsp;<b>{lang_Addressbook}/{lang_Contact_Settings}</b></font>
  47  </td>
  48   </tr>
  49   <tr bgcolor="{row_on}">
  50    <td>{lang_Contact_application}:</td>
  51    <td><input name="newsettings[contact_application]" value="{value_contact_application}"></td>
  52   </tr>
  53  ...
  54  
  55  Note the fieldname, newsettings[contact_application]. This
  56  array name must be used for the form values. Next, note
  57  the value setting for this form element, {value_contact_application}.
  58  This indicates that we want the current value of the config
  59  setting, 'contact_application', to be set and displayed
  60  on the form. Lastly, look at the template element, {lang_Contact_application}.
  61  Here, the value from the lang db table will be inserted
  62  if available.
  63  
  64  Let's take a look at part of the preferences/default/config.tpl:
  65  
  66   <tr bgcolor="{row_on}">
  67    <td>{lang_Country_Selection} ({lang_Text_Entry}/{lang_SelectBox}):</td>
  68    <td>
  69     <select name="newsettings[countrylist]">
  70  {hook_country_set}
  71     </select>
  72    </td>
  73   </tr>
  74  
  75  Here, we are adding a new element, {hook_country_set}. This
  76  brings up the next file we will need to parse this value...
  77  
  78  1.2 hook_config.inc.php (optional)
  79  
  80  At each invocation of config.php, a call to the common class
  81  function hook_single() is made. It attempts to include a
  82  file, hook_config.inc.php as a set of code for config.php
  83  to use. In the case of the preferences example above, using
  84  hook_country_set, here is the corresponding function in
  85  preferences/inc/hook_config.inc.php:
  86  
  87  function country_set($config)
  88  {
  89      $country = array( 'user_choice' => 'Users Choice', 'force_select' => 'Force Selectbox' );
  90      while (list ($key, $value) = each ($country))
  91      {
  92          if ($config['countrylist'] == $key)
  93          {
  94              $selected = ' selected';
  95          } 
  96          else
  97          {
  98              $selected = '';
  99          }
 100          $descr = lang($value);
 101          $out .= '<option value="' . $key . '"' . $selected . '>' . $descr . '</option>' . "\n";
 102      }
 103      return $out;
 104  }
 105  
 106  Note again the template value we used earlier, {hook_country_set}.
 107  This causes config.php to look for a function named country_set().
 108  Since we included the file with this function via the hook_single()
 109  call, this function is executed. It's return is a string,
 110  and the function prints nothing itself.
 111  
 112  1.3 hook_config_validate.inc.php (optional)
 113  
 114  Once the admin clicks the submit button to post the form,
 115  we can optionally validate their input using one or many
 116  different functions. This is done by first making another
 117  call to hook_single() in the API common class. This time,
 118  the name config_validate is used, so common tries to include
 119  'application/inc/hook_config_validate.inc.php'.
 120  
 121  If this file exists, it sets a var to tell config.php it
 122  was found. Following then are functions named after each
 123  config we want to validate. The following example is for
 124  addressbook:
 125  
 126      $GLOBALS['phpgw_info']['server']['found_validation_hook'] = True;
 127  
 128      /* Check a specific setting. Name must match the setting. */
 129  
 130      function ldap_contact_context($value='')
 131      {
 132          if($value == $GLOBALS['phpgw_info']['server']['ldap_context'])
 133          {
 134              $GLOBALS['config_error'] = 'Contact context for ldap must be different from the context used for accounts';
 135          }
 136          elseif($value == $GLOBALS['phpgw_info']['server']['ldap_group_context'])
 137          {
 138              $GLOBALS['config_error'] = 'Contact context for ldap must be different from the context used for groups';
 139          }
 140          else
 141          {
 142              $GLOBALS['config_error'] = '';
 143          }
 144      }
 145  
 146  Here we created a function to check the entered value for
 147  the config item, ldap_contact_context. We want to make sure
 148  the admin did not set this value to one which would conflict
 149  with another config item, used for accounts or groups in
 150  eGroupWare.
 151  
 152  config.php calls this function, sending it the POSTed value.
 153  config.php continues, adding all other config items from
 154  the POSTed values.
 155  
 156  The variable $GLOBALS['config_error'] is parsed through lang(),
 157  then appended to the local variable, $error. If this has
 158  any value after the POSTed variables are checked, the form
 159  then has its {error} tag filled with this result. The form
 160  is displayed again, with the error. If $error has no value,
 161  config.php redirects to admin/index.php.
 162  
 163  However, there is one more function that may be included
 164  in hook_config_validate.inc.php:
 165  
 166      /* Check all settings to validate input. Name must be 'final_validation' */
 167      function final_validation($value='') 
 168      {
 169          if($value['contact_repository'] == 'ldap' && !$value['ldap_contact_dn'])
 170          {
 171              $GLOBALS['config_error'] = 'Contact dn must be set';
 172          }
 173          elseif($value['contact_repository'] == 'ldap' && !$value['ldap_contact_context'])
 174          {
 175              $GLOBALS['config_error'] = 'Contact context must be set';
 176          }
 177          else
 178          {
 179              $GLOBALS['config_error'] = '';
 180          }
 181      }
 182  
 183  config.php checks for the existence of the function 'final_validation()'.
 184  This function can be used to check all form values at once.
 185  It gets sent the entire $newsettings array POSTed from the
 186  form. As with the other functions in this file, final_validation()
 187  should set $GLOBALS['config_error'] if there is a problem.