eGroupWare PHP Cross Reference Groupware Applications

Source: /admin/doc/adminconfig.lyx - 413 lines - 8816 bytes - Summary - Text - Print

   1  #LyX 1.1 created this file. For more info see http://www.lyx.org/
   2  \lyxformat 218
   3  \textclass docbook
   4  \language english
   5  \inputencoding auto
   6  \fontscheme default
   7  \graphics default
   8  \paperfontsize default
   9  \spacing single 
  10  \papersize Default
  11  \paperpackage a4
  12  \use_geometry 0
  13  \use_amsmath 0
  14  \paperorientation portrait
  15  \secnumdepth 3
  16  \tocdepth 3
  17  \paragraph_separation indent
  18  \defskip medskip
  19  \quotes_language english
  20  \quotes_times 2
  21  \papercolumns 1
  22  \papersides 1
  23  \paperpagestyle default
  24  
  25  \layout Title
  26  
  27  eGroupWare admin/config.php
  28  \layout Abstract
  29  
  30  A brief introduction to writing hooks and templates for any application
  31   to use this admin interface, by
  32  \layout Abstract
  33  
  34  Miles Lott <milosch@groupwhere.org> Dec 22, 2001.
  35  \layout Section
  36  
  37  Files
  38  \layout Subsection
  39  
  40  config.tpl (required)
  41  \layout Standard
  42  
  43  In your application/templates/default directory, create a new template file
  44   named 'config.tpl'.
  45   This will be included by config.php and used to draw the page.
  46   This template should include a POST method form.
  47   The following template tags may be used:
  48  \layout Enumerate
  49  
  50  {action_url} - A egw->link to config.php will be inserted.
  51  \layout Enumerate
  52  
  53  {title} - This will be parsed to display 'Site Configuration'.
  54  \layout Enumerate
  55  
  56  {th_bg},{th_text},{row_on},{row_off} - Replaced with the current theme colors.
  57  \layout Standard
  58  
  59  and the following special types:
  60  \layout Enumerate
  61  
  62  {lang_XXX} - Filled with lang('XXX').
  63  \layout Enumerate
  64  
  65  {value_XXX} - Filled with the current value of config item 'XXX'.
  66  \layout Enumerate
  67  
  68  {selected_XXX} - set to '', or ' selected' if an option value is current.
  69  \layout Enumerate
  70  
  71  {hook_XXX} - Calls a function named XXX (will be discussed later).
  72  \layout Standard
  73  
  74  Following is an example from the addressbook application:
  75  \layout Code
  76  
  77  <form method="POST" action="{action_url}">
  78  \layout Code
  79  
  80  <table border="0" align="center">
  81  \layout Code
  82  
  83   <tr bgcolor="{th_bg}">
  84  \layout Code
  85  
  86    <td colspan="2"><font color="{th_text}">&nbsp;<b>{title}</b></font></td>
  87  \layout Code
  88  
  89   </tr> <tr bgcolor="{th_err}">
  90  \layout Code
  91  
  92    <td colspan="2">&nbsp;<b>{error}</b></font></td>
  93  \layout Code
  94  
  95   </tr>
  96  \layout Code
  97  
  98  <!-- END header -->
  99  \layout Code
 100  
 101  <!-- BEGIN body -->
 102  \layout Code
 103  
 104   <tr bgcolor="{row_on}">
 105  \layout Code
 106  
 107    <td colspan="2">&nbsp;</td>
 108  \layout Code
 109  
 110   </tr>
 111  \layout Code
 112  
 113   <tr bgcolor="{row_off}">
 114  \layout Code
 115  
 116    <td colspan="2">&nbsp;<b>{lang_Addressbook}/{lang_Contact_Settings}</b></font>
 117  \layout Code
 118  
 119  </td>
 120  \layout Code
 121  
 122   </tr>
 123  \layout Code
 124  
 125   <tr bgcolor="{row_on}">
 126  \layout Code
 127  
 128    <td>{lang_Contact_application}:</td>
 129  \layout Code
 130  
 131    <td><input name="newsettings[contact_application]" value="{value_contact_appli
 132  cation}"></td>
 133  \layout Code
 134  
 135   </tr>
 136  \layout Code
 137  
 138  ...
 139  \layout Standard
 140  
 141  Note the fieldname, newsettings[contact_application].
 142   This array name must be used for the form values.
 143   Next, note the value setting for this form element, {value_contact_application}.
 144   This indicates that we want the current value of the config setting, 'contact_a
 145  pplication', to be set and displayed on the form.
 146   Lastly, look at the template element, {lang_Contact_application}.
 147   Here, the value from the lang db table will be inserted if available.
 148  \layout Standard
 149  
 150  Let's take a look at part of the preferences/default/config.tpl:
 151  \layout Code
 152  
 153   <tr bgcolor="{row_on}">
 154  \layout Code
 155  
 156    <td>{lang_Country_Selection} ({lang_Text_Entry}/{lang_SelectBox}):</td>
 157  \layout Code
 158  
 159    <td>
 160  \layout Code
 161  
 162     <select name="newsettings[countrylist]">
 163  \layout Code
 164  
 165  {hook_country_set}
 166  \layout Code
 167  
 168     </select>
 169  \layout Code
 170  
 171    </td>
 172  \layout Code
 173  
 174   </tr>
 175  \layout Standard
 176  
 177  Here, we are adding a new element, {hook_country_set}.
 178   This brings up the next file we will need to parse this value...
 179  \layout Subsection
 180  
 181  hook_config.inc.php (optional)
 182  \layout Standard
 183  
 184  At each invocation of config.php, a call to the common class function hook_single
 185  () is made.
 186   It attempts to include a file, hook_config.inc.php as a set of code for config.php
 187   to use.
 188   In the case of the preferences example above, using hook_country_set, here
 189   is the corresponding function in preferences/inc/hook_config.inc.php:
 190  \layout Code
 191  
 192  function country_set($config)
 193  \layout Code
 194  
 195  {
 196  \layout Code
 197  
 198      $country = array( 'user_choice' => 'Users Choice', 'force_select' =>
 199   'Force Selectbox' );
 200  \layout Code
 201  
 202      while (list ($key, $value) = each ($country))
 203  \layout Code
 204  
 205      {
 206  \layout Code
 207  
 208          if ($config['countrylist'] == $key)
 209  \layout Code
 210  
 211          {
 212  \layout Code
 213  
 214              $selected = ' selected';
 215  \layout Code
 216  
 217          } 
 218  \layout Code
 219  
 220          else
 221  \layout Code
 222  
 223          {
 224  \layout Code
 225  
 226              $selected = '';
 227  \layout Code
 228  
 229          }
 230  \layout Code
 231  
 232          $descr = lang($value);
 233  \layout Code
 234  
 235          $out .= '<option value="' .
 236   $key .
 237   '"' .
 238   $selected .
 239   '>' .
 240   $descr .
 241   '</option>' .
 242   "
 243  \backslash 
 244  n";
 245  \layout Code
 246  
 247      }
 248  \layout Code
 249  
 250      return $out;
 251  \layout Code
 252  
 253  }
 254  \layout Standard
 255  
 256  Note again the template value we used earlier, {hook_country_set}.
 257   This causes config.php to look for a function named country_set().
 258   Since we included the file with this function via the hook_single() call,
 259   this function is executed.
 260   It's return is a string, and the function prints nothing itself.
 261  \layout Subsection
 262  
 263  hook_config_validate.inc.php (optional)
 264  \layout Standard
 265  
 266  Once the admin clicks the submit button to post the form, we can optionally
 267   validate their input using one or many different functions.
 268   This is done by first making another call to hook_single() in the API common
 269   class.
 270   This time, the name config_validate is used, so common tries to include
 271   'application/inc/hook_config_validate.inc.php'.
 272  \layout Standard
 273  
 274  If this file exists, it sets a var to tell config.php it was found.
 275   Following then are functions named after each config we want to validate.
 276   The following example is for addressbook:
 277  \layout Code
 278  
 279      $GLOBALS['phpgw_info']['server']['found_validation_hook'] = True;
 280  \layout Code
 281  
 282  \layout Code
 283  
 284      /* Check a specific setting.
 285   Name must match the setting.
 286   */
 287  \layout Code
 288  
 289      function ldap_contact_context($value='')
 290  \layout Code
 291  
 292      {
 293  \layout Code
 294  
 295          if($value == $GLOBALS['phpgw_info']['server']['ldap_context'])
 296  \layout Code
 297  
 298          {
 299  \layout Code
 300  
 301              $GLOBALS['config_error'] = 'Contact context for ldap must be
 302   different from the context used for accounts';
 303  \layout Code
 304  
 305          }
 306  \layout Code
 307  
 308          elseif($value == $GLOBALS['phpgw_info']['server']['ldap_group_context'])
 309  \layout Code
 310  
 311          {
 312  \layout Code
 313  
 314              $GLOBALS['config_error'] = 'Contact context for ldap must be
 315   different from the context used for groups';
 316  \layout Code
 317  
 318          }
 319  \layout Code
 320  
 321          else
 322  \layout Code
 323  
 324          {
 325  \layout Code
 326  
 327              $GLOBALS['config_error'] = '';
 328  \layout Code
 329  
 330          }
 331  \layout Code
 332  
 333      }
 334  \layout Standard
 335  
 336  Here we created a function to check the entered value for the config item,
 337   ldap_contact_context.
 338   We want to make sure the admin did not set this value to one which would
 339   conflict with another config item, used for accounts or groups in eGroupWare.
 340  \layout Standard
 341  
 342  config.php calls this function, sending it the POSTed value.
 343   config.php continues, adding all other config items from the POSTed values.
 344  \layout Standard
 345  
 346  The variable $GLOBALS['config_error'] is parsed through lang(), then appended
 347   to the local variable, $error.
 348   If this has any value after the POSTed variables are checked, the form
 349   then has its {error} tag filled with this result.
 350   The form is displayed again, with the error.
 351   If $error has no value, config.php redirects to admin/index.php.
 352  \layout Standard
 353  
 354  However, there is one more function that may be included in hook_config_validate.
 355  inc.php:
 356  \layout Code
 357  
 358      /* Check all settings to validate input.
 359   Name must be 'final_validation' */
 360  \layout Code
 361  
 362      function final_validation($value='') 
 363  \layout Code
 364  
 365      {
 366  \layout Code
 367  
 368          if($value['contact_repository'] == 'ldap' && !$value['ldap_contact_dn'])
 369  \layout Code
 370  
 371          {
 372  \layout Code
 373  
 374              $GLOBALS['config_error'] = 'Contact dn must be set';
 375  \layout Code
 376  
 377          }
 378  \layout Code
 379  
 380          elseif($value['contact_repository'] == 'ldap' && !$value['ldap_contact_c
 381  ontext'])
 382  \layout Code
 383  
 384          {
 385  \layout Code
 386  
 387              $GLOBALS['config_error'] = 'Contact context must be set';
 388  \layout Code
 389  
 390          }
 391  \layout Code
 392  
 393          else
 394  \layout Code
 395  
 396          {
 397  \layout Code
 398  
 399              $GLOBALS['config_error'] = '';
 400  \layout Code
 401  
 402          }
 403  \layout Code
 404  
 405      }
 406  \layout Standard
 407  
 408  config.php checks for the existence of the function 'final_validation()'.
 409   This function can be used to check all form values at once.
 410   It gets sent the entire $newsettings array POSTed from the form.
 411   As with the other functions in this file, final_validation() should set
 412   $GLOBALS['config_error'] if there is a problem.
 413  \the_end

title

Description

title

Description

title

Description

title

title

Body