source: companies/celepar/admin/doc/adminconfig.sgml @ 763

Revision 763, 9.3 KB checked in by niltonneto, 15 years ago (diff)

Importação inicial do Expresso da Celepar

Line 
1<!doctype article public "-//OASIS//DTD DocBook V3.1//EN">
2
3<article lang="en">
4<!-- DocBook file was created by LyX 1.1
5  See http://www.lyx.org/ for more information -->
6  <artheader>
7   <title>
8   eGroupWare admin/config.php
9  </title>
10  <abstract>
11  <para>
12   A brief introduction to writing hooks and templates for any application to use this admin interface, by
13  </para>
14  <para>
15   Miles Lott &lt;milosch@groupwhere.org&gt; Dec 22, 2001.
16  </para>
17  </abstract>
18  </artheader>
19  <sect1>
20   <title>
21   Files
22  </title>
23   <sect2>
24    <title>
25    config.tpl (required)
26   </title>
27   <para>
28    In your application/templates/default directory, create a new template file named 'config.tpl'. This will be included by config.php and used to draw the page. This template should include a POST method form. The following template tags may be used:
29   </para>
30   <orderedlist>
31    <listitem>
32    <para>
33    &lcub;action_url&rcub; - A egw-&gt;link to config.php will be inserted.
34    </para>
35   </listitem>
36    <listitem>
37    <para>
38    &lcub;title&rcub; - This will be parsed to display 'Site Configuration'.
39    </para>
40   </listitem>
41    <listitem>
42    <para>
43    &lcub;th_bg&rcub;,&lcub;th_text&rcub;,&lcub;row_on&rcub;,&lcub;row_off&rcub; - Replaced with the current theme colors.
44    </para>
45   </listitem>
46   </orderedlist>
47   <para>
48    and the following special types:
49   </para>
50   <orderedlist>
51    <listitem>
52    <para>
53    &lcub;lang_XXX&rcub; - Filled with lang('XXX').
54    </para>
55   </listitem>
56    <listitem>
57    <para>
58    &lcub;value_XXX&rcub; - Filled with the current value of config item 'XXX'.
59    </para>
60   </listitem>
61    <listitem>
62    <para>
63    &lcub;selected_XXX&rcub; - set to '', or ' selected' if an option value is current.
64    </para>
65   </listitem>
66    <listitem>
67    <para>
68    &lcub;hook_XXX&rcub; - Calls a function named XXX (will be discussed later).
69    </para>
70   </listitem>
71   </orderedlist>
72   <para>
73    Following is an example from the addressbook application:
74   </para>
75   <programlisting>
76<![ CDATA [<form method="POST" action="{action_url}">
77]]><![ CDATA [<table border="0" align="center">
78]]><![ CDATA [ <tr bgcolor="{th_bg}">
79]]><![ CDATA [  <td colspan="2"><font color="{th_text}">&nbsp;<b>{title}</b></font></td>
80]]><![ CDATA [ </tr> <tr bgcolor="{th_err}">
81]]><![ CDATA [  <td colspan="2">&nbsp;<b>{error}</b></font></td>
82]]><![ CDATA [ </tr>
83]]><![ CDATA [<!-- END header -->
84]]><![ CDATA [<!-- BEGIN body -->
85]]><![ CDATA [ <tr bgcolor="{row_on}">
86]]><![ CDATA [  <td colspan="2">&nbsp;</td>
87]]><![ CDATA [ </tr>
88]]><![ CDATA [ <tr bgcolor="{row_off}">
89]]><![ CDATA [  <td colspan="2">&nbsp;<b>{lang_Addressbook}/{lang_Contact_Settings}</b></font>
90]]><![ CDATA [</td>
91]]><![ CDATA [ </tr>
92]]><![ CDATA [ <tr bgcolor="{row_on}">
93]]><![ CDATA [  <td>{lang_Contact_application}:</td>
94]]><![ CDATA [  <td><input name="newsettings[contact_application]" value="{value_contact_application}"></td>
95]]><![ CDATA [ </tr>
96]]><![ CDATA [...
97]]>   </programlisting>
98   <para>
99    Note the fieldname, newsettings&lsqb;contact_application&rsqb;. This array name must be used for the form values. Next, note the value setting for this form element, &lcub;value_contact_application&rcub;. This indicates that we want the current value of the config setting, 'contact_application', to be set and displayed on the form. Lastly, look at the template element, &lcub;lang_Contact_application&rcub;. Here, the value from the lang db table will be inserted if available.
100   </para>
101   <para>
102    Let's take a look at part of the preferences/default/config.tpl:
103   </para>
104   <programlisting>
105<![ CDATA [ <tr bgcolor="{row_on}">
106]]><![ CDATA [  <td>{lang_Country_Selection} ({lang_Text_Entry}/{lang_SelectBox}):</td>
107]]><![ CDATA [  <td>
108]]><![ CDATA [   <select name="newsettings[countrylist]">
109]]><![ CDATA [{hook_country_set}
110]]><![ CDATA [   </select>
111]]><![ CDATA [  </td>
112]]><![ CDATA [ </tr>
113]]>   </programlisting>
114   <para>
115    Here, we are adding a new element, &lcub;hook_country_set&rcub;. This brings up the next file we will need to parse this value...
116   </para>
117   </sect2>
118   <sect2>
119    <title>
120    hook_config.inc.php (optional)
121   </title>
122   <para>
123    At each invocation of config.php, a call to the common class function hook_single() is made. It attempts to include a file, hook_config.inc.php as a set of code for config.php to use. In the case of the preferences example above, using hook_country_set, here is the corresponding function in preferences/inc/hook_config.inc.php:
124   </para>
125   <programlisting>
126<![ CDATA [function country_set($config)
127]]><![ CDATA [{
128]]><![ CDATA [    $country = array( 'user_choice' => 'Users Choice', 'force_select' => 'Force Selectbox' );
129]]><![ CDATA [    while (list ($key, $value) = each ($country))
130]]><![ CDATA [    {
131]]><![ CDATA [        if ($config['countrylist'] == $key)
132]]><![ CDATA [        {
133]]><![ CDATA [            $selected = ' selected';
134]]><![ CDATA [        }
135]]><![ CDATA [        else
136]]><![ CDATA [        {
137]]><![ CDATA [            $selected = '';
138]]><![ CDATA [        }
139]]><![ CDATA [        $descr = lang($value);
140]]><![ CDATA [        $out .= '<option value="' . $key . '"' . $selected . '>' . $descr . '</option>' . "\n";
141]]><![ CDATA [    }
142]]><![ CDATA [    return $out;
143]]><![ CDATA [}
144]]>   </programlisting>
145   <para>
146    Note again the template value we used earlier, &lcub;hook_country_set&rcub;. This causes config.php to look for a function named country_set(). Since we included the file with this function via the hook_single() call, this function is executed. It's return is a string, and the function prints nothing itself.
147   </para>
148   </sect2>
149   <sect2>
150    <title>
151    hook_config_validate.inc.php (optional)
152   </title>
153   <para>
154    Once the admin clicks the submit button to post the form, we can optionally validate their input using one or many different functions. This is done by first making another call to hook_single() in the API common class. This time, the name config_validate is used, so common tries to include 'application/inc/hook_config_validate.inc.php'.
155   </para>
156   <para>
157    If this file exists, it sets a var to tell config.php it was found. Following then are functions named after each config we want to validate. The following example is for addressbook:
158   </para>
159   <programlisting>
160<![ CDATA [    $GLOBALS['phpgw_info']['server']['found_validation_hook'] = True;
161]]><![ CDATA [
162]]><![ CDATA [    /* Check a specific setting. Name must match the setting. */
163]]><![ CDATA [    function ldap_contact_context($value='')
164]]><![ CDATA [    {
165]]><![ CDATA [        if($value == $GLOBALS['phpgw_info']['server']['ldap_context'])
166]]><![ CDATA [        {
167]]><![ CDATA [            $GLOBALS['config_error'] = 'Contact context for ldap must be different from the context used for accounts';
168]]><![ CDATA [        }
169]]><![ CDATA [        elseif($value == $GLOBALS['phpgw_info']['server']['ldap_group_context'])
170]]><![ CDATA [        {
171]]><![ CDATA [            $GLOBALS['config_error'] = 'Contact context for ldap must be different from the context used for groups';
172]]><![ CDATA [        }
173]]><![ CDATA [        else
174]]><![ CDATA [        {
175]]><![ CDATA [            $GLOBALS['config_error'] = '';
176]]><![ CDATA [        }
177]]><![ CDATA [    }
178]]>   </programlisting>
179   <para>
180    Here we created a function to check the entered value for the config item, ldap_contact_context. We want to make sure the admin did not set this value to one which would conflict with another config item, used for accounts or groups in eGroupWare.
181   </para>
182   <para>
183    config.php calls this function, sending it the POSTed value. config.php continues, adding all other config items from the POSTed values.
184   </para>
185   <para>
186    The variable &dollar;GLOBALS&lsqb;'config_error'&rsqb; is parsed through lang(), then appended to the local variable, &dollar;error. If this has any value after the POSTed variables are checked, the form then has its &lcub;error&rcub; tag filled with this result. The form is displayed again, with the error. If &dollar;error has no value, config.php redirects to admin/index.php.
187   </para>
188   <para>
189    However, there is one more function that may be included in hook_config_validate.inc.php:
190   </para>
191   <programlisting>
192<![ CDATA [    /* Check all settings to validate input. Name must be 'final_validation' */
193]]><![ CDATA [    function final_validation($value='')
194]]><![ CDATA [    {
195]]><![ CDATA [        if($value['contact_repository'] == 'ldap' && !$value['ldap_contact_dn'])
196]]><![ CDATA [        {
197]]><![ CDATA [            $GLOBALS['config_error'] = 'Contact dn must be set';
198]]><![ CDATA [        }
199]]><![ CDATA [        elseif($value['contact_repository'] == 'ldap' && !$value['ldap_contact_context'])
200]]><![ CDATA [        {
201]]><![ CDATA [            $GLOBALS['config_error'] = 'Contact context must be set';
202]]><![ CDATA [        }
203]]><![ CDATA [        else
204]]><![ CDATA [        {
205]]><![ CDATA [            $GLOBALS['config_error'] = '';
206]]><![ CDATA [        }
207]]><![ CDATA [    }
208]]>   </programlisting>
209   <para>
210    config.php checks for the existence of the function 'final_validation()'. This function can be used to check all form values at once. It gets sent the entire &dollar;newsettings array POSTed from the form. As with the other functions in this file, final_validation() should set &dollar;GLOBALS&lsqb;'config_error'&rsqb; if there is a problem.
211   </para>
212   </sect2>
213  </sect1>
214
215
216</article>
Note: See TracBrowser for help on using the repository browser.