source: trunk/admin/doc/adminconfig.lyx @ 2

Revision 2, 8.6 KB checked in by niltonneto, 17 years ago (diff)

Removida todas as tags usadas pelo CVS ($Id, $Source).
Primeira versão no CVS externo.

  • Property svn:executable set to *
  • Property svn:mime-type set to application/octet-stream
Line 
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
27eGroupWare admin/config.php
28\layout Abstract
29
30A brief introduction to writing hooks and templates for any application
31 to use this admin interface, by
32\layout Abstract
33
34Miles Lott <milosch@groupwhere.org> Dec 22, 2001.
35\layout Section
36
37Files
38\layout Subsection
39
40config.tpl (required)
41\layout Standard
42
43In 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
59and 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
74Following 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
132cation}"></td>
133\layout Code
134
135 </tr>
136\layout Code
137
138...
139\layout Standard
140
141Note 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
145pplication', 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
150Let'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
177Here, 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
181hook_config.inc.php (optional)
182\layout Standard
183
184At 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
192function 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
244n";
245\layout Code
246
247    }
248\layout Code
249
250    return $out;
251\layout Code
252
253}
254\layout Standard
255
256Note 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
263hook_config_validate.inc.php (optional)
264\layout Standard
265
266Once 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
274If 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
336Here 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
342config.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
346The 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
354However, there is one more function that may be included in hook_config_validate.
355inc.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
381ontext'])
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
408config.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
Note: See TracBrowser for help on using the repository browser.