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}"> <b>{title}</b></font></td> |
---|
36 | </tr> <tr bgcolor="{th_err}"> |
---|
37 | <td colspan="2"> <b>{error}</b></font></td> |
---|
38 | </tr> |
---|
39 | <!-- END header --> |
---|
40 | |
---|
41 | <!-- BEGIN body --> |
---|
42 | <tr bgcolor="{row_on}"> |
---|
43 | <td colspan="2"> </td> |
---|
44 | </tr> |
---|
45 | <tr bgcolor="{row_off}"> |
---|
46 | <td colspan="2"> <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. |
---|