[6779] | 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}"> <b>{title}</b></font></td> |
---|
| 87 | \layout Code |
---|
| 88 | |
---|
| 89 | </tr> <tr bgcolor="{th_err}"> |
---|
| 90 | \layout Code |
---|
| 91 | |
---|
| 92 | <td colspan="2"> <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"> </td> |
---|
| 108 | \layout Code |
---|
| 109 | |
---|
| 110 | </tr> |
---|
| 111 | \layout Code |
---|
| 112 | |
---|
| 113 | <tr bgcolor="{row_off}"> |
---|
| 114 | \layout Code |
---|
| 115 | |
---|
| 116 | <td colspan="2"> <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 |
---|