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

Revision 2, 6.5 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:eol-style set to native
  • Property svn:executable set to *
Line 
1
2eGroupWare admin/config.php
3
4Abstract
5
6A brief introduction to writing hooks and templates for any application to use
7this admin interface, by Miles Lott <milosch@groupwhere.org> Dec 22, 2001.
8
91 Files
10
111.1 config.tpl (required)
12
13In your application/templates/default directory, create a
14new template file named 'config.tpl'. This will be included
15by config.php and used to draw the page. This template should
16include a POST method form. The following template tags
17may be used:
18
191. {action_url} - A phpgw->link to config.php will be inserted.
202. {title} - This will be parsed to display 'Site Configuration'.
213. {th_bg},{th_text},{row_on},{row_off} - Replaced with the current theme colors.
22
23and the following special types:
24
251. {lang_XXX} - Filled with lang('XXX').
262. {value_XXX} - Filled with the current value of config item 'XXX'.
273. {selected_XXX} - set to '', or ' selected' if an option value is current.
284. {hook_XXX} - Calls a function named XXX (will be discussed later).
29
30Following 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
55Note the fieldname, newsettings[contact_application]. This
56array name must be used for the form values. Next, note
57the value setting for this form element, {value_contact_application}.
58This indicates that we want the current value of the config
59setting, 'contact_application', to be set and displayed
60on the form. Lastly, look at the template element, {lang_Contact_application}.
61Here, the value from the lang db table will be inserted
62if available.
63
64Let'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
75Here, we are adding a new element, {hook_country_set}. This
76brings up the next file we will need to parse this value...
77
781.2 hook_config.inc.php (optional)
79
80At each invocation of config.php, a call to the common class
81function hook_single() is made. It attempts to include a
82file, hook_config.inc.php as a set of code for config.php
83to use. In the case of the preferences example above, using
84hook_country_set, here is the corresponding function in
85preferences/inc/hook_config.inc.php:
86
87function 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
106Note again the template value we used earlier, {hook_country_set}.
107This causes config.php to look for a function named country_set().
108Since we included the file with this function via the hook_single()
109call, this function is executed. It's return is a string,
110and the function prints nothing itself.
111
1121.3 hook_config_validate.inc.php (optional)
113
114Once the admin clicks the submit button to post the form,
115we can optionally validate their input using one or many
116different functions. This is done by first making another
117call to hook_single() in the API common class. This time,
118the name config_validate is used, so common tries to include
119'application/inc/hook_config_validate.inc.php'.
120
121If this file exists, it sets a var to tell config.php it
122was found. Following then are functions named after each
123config we want to validate. The following example is for
124addressbook:
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
146Here we created a function to check the entered value for
147the config item, ldap_contact_context. We want to make sure
148the admin did not set this value to one which would conflict
149with another config item, used for accounts or groups in
150eGroupWare.
151
152config.php calls this function, sending it the POSTed value.
153config.php continues, adding all other config items from
154the POSTed values.
155
156The variable $GLOBALS['config_error'] is parsed through lang(),
157then appended to the local variable, $error. If this has
158any value after the POSTed variables are checked, the form
159then has its {error} tag filled with this result. The form
160is displayed again, with the error. If $error has no value,
161config.php redirects to admin/index.php.
162
163However, there is one more function that may be included
164in 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
183config.php checks for the existence of the function 'final_validation()'.
184This function can be used to check all form values at once.
185It gets sent the entire $newsettings array POSTed from the
186form. As with the other functions in this file, final_validation()
187should set $GLOBALS['config_error'] if there is a problem.
Note: See TracBrowser for help on using the repository browser.