[2] | 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. |
---|