source: trunk/phpgwapi/doc/index.html @ 2

Revision 2, 34.4 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<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2"http://www.w3.org/TR/html4/loose.dtd">
3
4<html>
5  <head>
6    <title>eGroupWare Application Development</title>
7
8    <style type="text/css">
9<!--
10h1 {
11        text-shadow: 3px 3px 5px;
12}
13h1:before {
14    content: counter(chapter) ". ";
15    counter-increment: chapter;  /* Add 1 to chapter */
16    counter-reset: section;      /* Set section to 0 */
17}
18h2:before {
19    content: counter(chapter) "." counter(section) " ";
20    counter-increment: section;
21}
22ol { counter-reset: item }
23lo { display: block }
24li:before { content: counters(item, "."); counter-increment: item }
25body, p, td {font-family: Verdana, Arial, Helvetica, sans-serif;}
26blockquote {text-align: center; font-style: italic;}
27//-->
28    </style>
29  </head>
30
31  <body>
32    <h1>eGroupWare Application Development</h1>
33
34    <blockquote>
35      This document explains eGroupWare's infrastructure and API,
36      along with what is required to integrate applications into
37      it.
38    </blockquote>
39
40    <h1>Contents</h1>
41
42    <ol>
43      <li><a href="#tth_sEc1">Introduction</a></li>
44
45      <li style="list-style: none">
46        <ol>
47          <li><a href="#tth_sEc1.1">Overview of application
48          writing</a></li>
49
50          <li><a href="#tth_sEc1.2">What does the eGroupWare API
51          provide?</a></li>
52        </ol>
53      </li>
54
55      <li><a href="#tth_sEc2">Guidelines</a></li>
56
57      <li style="list-style: none">
58        <ol>
59          <li><a href="#tth_sEc2.1">Requirements</a></li>
60
61          <li><a href="#tth_sEc2.2">Writing/porting your
62          application</a></li>
63        </ol>
64      </li>
65
66      <li><a href="#tth_sEc3">Installing your application</a></li>
67
68      <li style="list-style: none">
69        <ol>
70          <li><a href="#tth_sEc3.1">Overview</a></li>
71
72          <li><a href="#tth_sEc3.2">Automatic features</a></li>
73
74          <li><a href="#tth_sEc3.3">Adding files, directories and
75          icons.</a></li>
76
77          <li><a href="#tth_sEc3.4">Making eGroupWare aware of your
78          application</a></li>
79
80          <li><a href="#tth_sEc3.5">Hooking into Administration
81          page</a></li>
82
83          <li><a href="#tth_sEc3.6">Hooking into Preferences
84          page</a></li>
85        </ol>
86      </li>
87
88      <li><a href="#tth_sEc4">Infrastructure</a></li>
89
90      <li style="list-style: none">
91        <ol>
92          <li><a href="#tth_sEc4.1">Overview</a></li>
93
94          <li><a href="#tth_sEc4.2">Directory tree</a></li>
95
96          <li><a href="#tth_sEc4.3">Translations</a></li>
97        </ol>
98      </li>
99
100      <li><a href="#tth_sEc5">The API</a></li>
101
102      <li style="list-style: none">
103        <ol>
104          <li><a href="#tth_sEc5.1">Introduction</a></li>
105
106          <li><a href="#tth_sEc5.2">Basic functions</a></li>
107
108          <li><a href="#tth_sEc5.3">Application Functions</a></li>
109
110          <li><a href="#tth_sEc5.4">File functions</a></li>
111
112          <li><a href="#tth_sEc5.5">Email/NNTP Functions</a></li>
113        </ol>
114      </li>
115
116      <li><a href="#tth_sEc6">Configuration Variables</a></li>
117
118      <li style="list-style: none">
119        <ol>
120          <li><a href="#tth_sEc6.1">Introduction</a></li>
121
122          <li><a href="#tth_sEc6.2">User information</a></li>
123
124          <li><a href="#tth_sEc6.3">Group information</a></li>
125
126          <li><a href="#tth_sEc6.4">Server information</a></li>
127
128          <li><a href="#tth_sEc6.5">Database information</a></li>
129
130          <li><a href="#tth_sEc6.6">Mail information</a></li>
131
132          <li><a href="#tth_sEc6.7">NNTP information</a></li>
133
134          <li><a href="#tth_sEc6.8">Application
135          information</a></li>
136        </ol>
137      </li>
138
139      <li><a href="#tth_sEc7">Using Language Support</a></li>
140
141      <li style="list-style: none">
142        <ol>
143          <li><a href="#tth_sEc7.1">Overview</a></li>
144
145          <li><a href="#tth_sEc7.2">How to use lang
146          support</a></li>
147
148          <li><a href="#tth_sEc7.3">Common return codes</a></li>
149        </ol>
150      </li>
151
152      <li><a href="#tth_sEc8">Using Templates</a></li>
153
154      <li style="list-style: none">
155        <ol>
156          <li><a href="#tth_sEc8.1">Overview</a></li>
157
158          <li><a href="#tth_sEc8.2">How to use PHPLIB
159          templates</a></li>
160
161          <li><a href="#tth_sEc8.3">How to use eTemplate
162          templates</a></li>
163        </ol>
164      </li>
165
166      <li><a href="#tth_sEc9">About this document</a></li>
167
168      <li style="list-style: none">
169        <ol>
170          <li><a href="#tth_sEc9.1">New versions</a></li>
171
172          <li><a href="#tth_sEc9.2">Comments</a></li>
173
174          <li><a href="#tth_sEc9.3">History</a></li>
175
176          <li><a href="#tth_sEc9.4">Copyrights and
177          Trademarks</a></li>
178
179          <li><a href="#tth_sEc9.5">Acknowledgments and
180          Thanks</a></li>
181        </ol>
182      </li>
183    </ol>
184
185    <h2><a name="tth_sEc1">1</a>&nbsp;&nbsp;Introduction</h2>
186
187    <p>eGroupWare is a web based groupware application framework
188    (API), for writing applications. Integrated applications such
189    as email, calendar, todo list, address book, and file manager
190    are included.</p>
191
192    <h3><a name="tth_sEc1.1">1.1</a>&nbsp;&nbsp;Overview of
193    application writing</h3>
194
195    <p>We have attempted to make writing application for eGroupWare
196    as painless as possible. We hope any pain and suffering is
197    cause by making your application work, but not dealing with
198    eGroupWare itself.</p>
199
200    <h3><a name="tth_sEc1.2">1.2</a>&nbsp;&nbsp;What does the
201    eGroupWare API provide?</h3>
202
203    <p>The eGroupWare API handles session management, user/group
204    management, has support for multiple databases, using the
205    PHPLIB database abstraction method, we support templates using
206    the PHPLIB Templates class, a file system interface, and even a
207    network i/o interface.</p>
208
209    <p>On top of these standard functions, eGroupWare provides
210    several functions to give you the information you need about
211    the users environment, and to properly plug into
212    eGroupWare.</p>
213
214    <h2><a name="tth_sEc2">2</a>&nbsp;&nbsp;Guidelines</h2>
215
216    <h3><a name="tth_sEc2.1">2.1</a>&nbsp;&nbsp;Requirements</h3>
217
218    <p>These guidelines must be followed for any application that
219    wants considered for inclusion into eGroupWare deluxe:</p>
220
221    <ul>
222      <li>It must run on PHP4.1.0</li>
223
224      <li>SQL statements must be compatible with both MySQL,
225      PostgreSQL, M$ SQL Server and SAP-DB</li>
226
227      <li>It must use our default header.inc.php include.</li>
228
229      <li>It must use our $GLOBALS['phpgw']-&gt;link($url) for all
230      links (this is for session support).</li>
231
232      <li>It must use "POST" for form submit methods.</li>
233
234      <li>It must respect eGW group rights and eGW user
235      permissions.</li>
236
237      <li>It must use our directory structure, template support and
238      lang (multi-language) support.</li>
239
240      <li>Where possible it should run on both Unix and NT
241      platforms.</li>
242
243      <li>For applications that do not meet these requirements,
244      they can be available to users via the eGroupWare "3rd Party
245      Apps" listing on our website. If you need help converting
246      your application to templates and our lang support, we will
247      try to connect you with someone to help.</li>
248    </ul>
249
250    <h3><a name="tth_sEc2.2">2.2</a>&nbsp;&nbsp;Writing/porting
251    your application</h3>
252
253    <h4>Include files</h4>
254
255    <p>Each PHP page you write will need to include the
256    header.inc.php along with a few variables.<br>
257    This is done by putting this at the top of each PHP page.</p>
258<pre>
259&lt;?php
260$GLOBALS['phpgw_info']['flags']['currentapp'] = 'appname';
261include('../header.inc.php');
262?&gt;
263
264
265</pre>
266    Of course change application name to fit.<br>
267    This include will provide the following things:
268
269    <ul>
270      <li>The phpgwAPI - The eGroupWare API will be loaded.</li>
271
272      <li>The eGW navbar will be loaded (by default, but can be
273      disabled until a later point.</li>
274
275      <li>appname/inc/functions.inc.php - This file is loaded just
276      after the phpgwAPI and before any HTML code is generated.
277      This file should include all your application specific
278      functions.. You are welcome to include any additional files
279      you need from within this file.<br>
280      <b>Note:</b> Depricated and not used for OOP
281      (/index.php?menuaction=app.obj.method) calls.</li>
282
283      <li>appname/inc/header.inc.php - This file is loaded just
284      after the system header/navbar, and allows developers to use
285      it for whatever they need to load.<br>
286      <b>Note:</b> Depricated and not used for OOP
287      (/index.php?menuaction=app.obj.method) calls.</li>
288
289      <li>appname/inc/footer.inc.php - This file is loaded just
290      before the system footer, allowing developers to close
291      connections and whatever else they need.<br>
292      <b>Note:</b> Depricated and not used for OOP
293      (/index.php?menuaction=app.obj.method) calls.</li>
294
295      <li>The eGW footer will be loaded, which closes several
296      connections.</li>
297    </ul>
298
299    <h2><a name="tth_sEc3">3</a>&nbsp;&nbsp;Installing your
300    application</h2>
301
302    <h3><a name="tth_sEc3.1">3.1</a>&nbsp;&nbsp;Overview</h3>
303
304    <p>It is fairly simple to add and delete applications to/from
305    eGroupWare.</p>
306
307    <h3><a name="tth_sEc3.2">3.2</a>&nbsp;&nbsp;Automatic
308    features</h3>
309
310    <p>To make things easy for developers we go ahead and load the
311    following files.</p>
312
313    <ul>
314      <li>appname/inc/functions.inc.php - This file should include
315      all your application specific functions.<br>
316      <b>Note:</b> Depricated and not used for OOP
317      (/index.php?menuaction=app.obj.method) calls.</li>
318
319      <li>appname/inc/header.inc.php - This file is loaded by
320      $phpgw-&gt;common-&gt;header just after the system
321      header/navbar, and allows developers to use it for whatever
322      they need to load.<br>
323      <b>Note:</b> Depricated and not used for OOP
324      (/index.php?menuaction=app.obj.method) calls.</li>
325
326      <li>appname/inc/footer.inc.php - This file is loaded by
327      $phpgw-&gt;common-&gt;footer just before the system footer,
328      allowing developers to close connections and whatever else
329      they need.<br>
330      <b>Note:</b> Depricated and not used for OOP
331      (/index.php?menuaction=app.obj.method) calls.</li>
332    </ul>
333
334    <h3><a name="tth_sEc3.3">3.3</a>&nbsp;&nbsp;Adding files,
335    directories and icons.</h3>
336
337    <p>You will need to create the following directories for your
338    code<br>
339    (replace 'appname' with your application name)<br>
340    </p>
341<pre>
342--appname
343
344  +--inc
345
346  |   |--functions.inc.php
347
348  |   |--header.inc.php
349
350  |   |--hook_preferences.inc.php
351
352  |   |--hook_admin.inc.php
353
354  |   +--footer.inc.php
355
356  +--js
357
358  |   |--base
359
360  |   +--js_package_name
361
362  +--setup
363
364  |   |--default_records.inc.php
365
366  |   |--setup.inc.php
367
368  |   +--tables_current.inc.php
369
370  +--templates
371
372      +--default
373</pre>
374
375    <h3><a name="tth_sEc3.4">3.4</a>&nbsp;&nbsp;Making eGroupWare
376    aware of your application</h3>
377
378    <p>To make the application aware of your application, add your
379    application details to the applications table. This can be done
380    via the GUI administration screen, or via a SQL script. The
381    script below should only be used during initial development.
382    You should use the eGroupWare setup system for install and
383    updating the final version of your application.</p>
384<pre>
385INSERT INTO phpgw_applications (app_name, app_title, app_enabled)
386        VALUES('appname', 'The App name', 1);
387</pre>
388
389    <h3><a name="tth_sEc3.5">3.5</a>&nbsp;&nbsp;Hooking into
390    Administration page</h3>
391
392    <p>When a user goes to the Administration page, it starts
393    appname/inc/hook_admin.inc.php for each application that is
394    enabled, in alphabetical order of application title. If the
395    file exists, it is include()d in the hopes it will display a
396    selection of links to configure that application.</p>
397
398    <p>Simple Example:</p>
399<pre>
400&lt;?php
401// Old linear script style
402$file['Site Configuration'] = $GLOBALS['phpgw']-&gt;link('myapp/myAdminPage.php');
403// OR - OOP Style
404$file['Site Configuration'] = $GLOBALS['phpgw']-&gt;link('/index.php',
405                                        array(menuaction =&gt; 'myapp.uiobj.admin_method');
406display_section('myapp',$file);
407?&amp;#gt;
408</pre>
409    Look at headlines/inc/hook_admin.inc.php and
410    admin/inc/hook_admin.inc.php for more examples. Things to note:
411   
412
413    <ul>
414      <li>Links are relative to the admin/index.php file, not your
415      application's base directory. (so use "appname" in your
416      link() calls)</li>
417
418      <li>The file is brought in with include() so be careful to
419      not pollute the name-space too much</li>
420    </ul>
421    The standard $GLOBALS['phpgw'] and $GLOBALS['phpgw_info']
422    variables are in-scope, as is $appname which corresponds to the
423    application name in the path.
424
425    <h3><a name="tth_sEc3.6">3.6</a>&nbsp;&nbsp;Hooking into
426    Preferences page</h3>
427
428    <p>The mechanism to hook into the preferences page is identical
429    to the one used to hook into the administration page, however
430    it looks for appname/inc/hook_preferences.inc.php instead of
431    appname/inc/hook_admin.inc.php. The same functions and
432    variables are defined.</p>
433
434    <h2><a name="tth_sEc4">4</a>&nbsp;&nbsp;Infrastructure</h2>
435
436    <h3><a name="tth_sEc4.1">4.1</a>&nbsp;&nbsp;Overview</h3>
437
438    <p>eGroupWare attempts to provide developers with a sound
439    directory structure to work from.<br>
440    The directory layout may seem complex at first, but after some
441    use, you will see that it is designed to accommodate a large
442    number of applications and functions.</p>
443
444    <h3><a name="tth_sEc4.2">4.2</a>&nbsp;&nbsp;Directory tree</h3>
445<pre>
446--eGroupWare
447  |
448  +--admin
449  |
450  +--docs (installation docs)
451  |
452  +--files (<b>Note:</b> must be out of webserver document root!)
453  |   |
454  |   +--groups
455  |   |
456  |   +--homes
457  |   |
458  |   +--users
459  |
460  +--phpgwapi
461  |   |
462  |   +--cron (eGroupWare's optional daemons)
463  |   |
464  |   +--doc (developers docs)
465  |   |
466  |   +--inc
467  |   |   |
468  |   |   +--class.phpgw.inc.php
469  |   |   |
470  |   |   +--phpgw_info.inc.php
471  |   |   |
472  |   |   +--class.common.inc.php
473  |   |   |
474  |   |   +--etc..
475  |   |
476  |   +--js (javascript)
477  |   |   |
478  |   |   +--base
479  |   |   |
480  |   |   +--js_package_name
481  |   |
482  |   +--manual
483  |   |
484  |   +--setup
485  |   |   |
486  |   |   +--baseline.inc.php
487  |   |   |
488  |   |   +--default_records.inc.php
489  |   |   |
490  |   |   +--tables_current.inc.php
491  |   |   |
492  |   |   +--tables_update.inc.php
493  |   |
494  |   +--templates
495  |   |   |
496  |   |   +--default
497  |   |   |   |
498  |   |   |   +--images
499  |   |   |
500  |   |   +--verilak
501  |   |       |
502  |   |       +--images
503  |   |
504  |   +--themes
505  |       |
506  |       +--default.theme
507  |
508  +--preferences
509  |
510  +--setup
511</pre>
512
513    <h3><a name="tth_sEc4.3">4.3</a>&nbsp;&nbsp;Translations</h3>
514
515    <p>The translations are now being done thru the database, and
516    may be configurable to use other mechanisms in future
517    releases.</p>
518
519    <p>You can use the developer_tools translations application for
520    creating the "lang files", which will be installed through the
521    setup application. Alternatively you can edit the files
522    manually. The file naming convention for the lang files is
523    <tt>phpgw_&lt;langcode&gt;.lang</tt>. The files are stored in
524    the <tt>app/setup</tt> directory. The format of the files is as
525    follows:</p>
526<pre>
527english phrase in lower case    appname **      Translated phrase in desired case.
528</pre>
529    <b>Notes:</b>
530
531    <ul>
532      <li>replace ** with the desired language code, as used in the
533      filename</li>
534
535      <li>tabs are used to deliniate "columns"</li>
536    </ul>
537
538    <h2><a name="tth_sEc5">5</a>&nbsp;&nbsp;The API</h2>
539
540    <h3><a name="tth_sEc5.1">5.1</a>&nbsp;&nbsp;Introduction</h3>
541
542    <p>eGroupWare attempts to provide developers with a useful API
543    to handle common tasks.</p>
544
545    <p>To do this we have created a multi-dimensional class
546    $GLOBALS['phpgw']-&gt;.</p>
547
548    <p>This allows for terrific code organization, and help
549    developers easily identify the file that the function is in.
550    All the files that are part of this class are in the inc/core
551    directory and are named to match the sub-class.</p>
552
553    <p>Example: $phpgw-&gt;send-&gt;msg() is in the
554    inc/phpgwapi/class.send.inc.php file.</p>
555
556    <h3><a name="tth_sEc5.2">5.2</a>&nbsp;&nbsp;Basic
557    functions</h3>
558
559    <h4>$GLOBALS['phpgw']-&gt;link</h4>
560
561    <p>$GLOBALS['phpgw']-&gt;link($url, $args)<br>
562    Add support for session management. ALL links must use this,
563    that includes href's form actions and header location's.</p>
564
565    <p>If you are just doing a form action back to the same page,
566    you can use it without any parameters.</p>
567
568    <p>This function is right at the core of the class because it
569    is used so often, we wanted to save developers a few
570    keystrokes. Example:</p>
571<pre>
572&lt;form name=copy method=post action="&lt;?php echo $GLOBALS['phpgw']-&gt;link();?&gt;"&gt;
573/* If session management is done via passing url parameters */
574/* The the result would be */
575/* &lt;form name=copy method=post action="somepage.php?sessionid=87687693276?kp3=kjh98u80"&gt; */
576</pre>
577
578    <h3><a name="tth_sEc5.3">5.3</a>&nbsp;&nbsp;Application
579    Functions</h3>
580
581    <h4>$GLOBALS['phpgw']-&gt;common-&gt;phpgw_header</h4>
582
583    <p>$GLOBALS['phpgw']-&gt;phpgw_header()<br>
584    Print out the start of the HTML page, including the navigation
585    bar and includes appname/inc/header.php, if using deprecated
586    linear scripts style.</p>
587
588    <h4>$GLOBALS['phpgw']-&gt;common-&gt;phpgw_footer</h4>
589
590    <p>$GLOBALS['phpgw']-&gt;phpgw_footer()<br>
591    Prints the system footer, and includes
592    appname/inc/footer.php</p>
593
594    <h4>$GLOBALS['phpgw']-&gt;common-&gt;appsession</h4>
595
596    <p>$GLOBALS['phpgw']-&gt;common-&gt;appsession($data)<br>
597    Store important information session information that your
598    application needs.<br>
599    $GLOBALS['phpgw']-&gt;appsession will return the value of your
600    session data is you leave the parameter empty [i.e.
601    $GLOBALS['phpgw']-&gt;appsession()], otherwise it will store
602    whatever data you send to it.<br>
603    You can also store a comma delimited string and use explode()
604    to turn it back into an array when you receive the value
605    back.</p>
606
607    <p>Example:</p>
608<pre>
609$GLOBALS['phpgw']-&gt;common-&gt;appsession("/path/to/something");
610echo "Dir: " . $GLOBALS['phpgw']-&gt;common-&gt;appsession();
611</pre>
612
613    <h3><a name="tth_sEc5.4">5.4</a>&nbsp;&nbsp;File functions</h3>
614
615    <p>See <a href="vfs/vfs.html">Virtual File System (VFS)
616    Developers Guide</a> for more info.</p>
617
618    <h3><a name="tth_sEc5.5">5.5</a>&nbsp;&nbsp;Email/NNTP
619    Functions</h3>
620
621    <h4>$phpgw-&gt;send-&gt;msg</h4>
622
623    <p>$phpgw-&gt;msg-&gt;send($service, $to, $subject, $body,
624    $msgtype, $cc, $bcc)<br>
625    Send a message via email or NNTP and returns any error
626    codes.<br>
627    Example:</p>
628<pre>
629$to = 'someuser@domain.com';
630$subject = 'Hello buddy';
631$body = "Give me a call\n Been wondering what your up to.";
632$errors = $GLOBALS['phpgw']-&gt;msg-&gt;send('email', $to, $subject, $body);
633
634
635</pre>
636
637    <h2><a name="tth_sEc6">6</a>&nbsp;&nbsp;Configuration
638    Variables</h2>
639
640    <h3><a name="tth_sEc6.1">6.1</a>&nbsp;&nbsp;Introduction</h3>
641
642    <p>eGroupWare attempts to provide developers with as much
643    information about the user, group, server, and application
644    configuration as possible.</p>
645
646    <p>To do this we provide a multi-dimensional array called
647    "$GLOBALS['phpgw_info']", which includes all the information
648    about your environment.</p>
649
650    <p>Due to the multi-dimensional array approach. getting these
651    values is easy.</p>
652
653    <p>Here are some examples:</p>
654<pre>
655&lt;?php
656// To do a hello username
657echo "Hello " . $GLOBALS['phpgw_info']['user']['fullname'];
658//If username first name is John and last name is Doe, prints: 'Hello John Doe'
659?&gt;
660&lt;?php
661// To find out the location of the imap server
662echo 'IMAP Server is named: ' . $GLOBALS['phpgw_info']['server']['imap_server'];
663//If imap is running on localhost, prints: 'IMAP Server is named: localhost'
664?&gt;
665
666
667
668</pre>
669
670    <h3><a name="tth_sEc6.2">6.2</a>&nbsp;&nbsp;User
671    information</h3>
672    <tt><font size="-1">$GLOBALS['phpgw_info']['user']['userid'] =
673    The user ID.<br>
674     $GLOBALS['phpgw_info']['user']['sessionid'] = The session
675    ID<br>
676     $GLOBALS['phpgw_info']['user']['theme'] = Selected theme<br>
677     $GLOBALS['phpgw_info']['user']['private_dir'] = Users private
678    dir. Use eGroupWare core functions for access to the files.<br>
679     $GLOBALS['phpgw_info']['user']['firstname'] = Users first
680    name<br>
681     $GLOBALS['phpgw_info']['user']['lastname'] = Users last
682    name<br>
683     $GLOBALS['phpgw_info']['user']['fullname'] = Users Full
684    Name<br>
685     $GLOBALS['phpgw_info']['user']['groups'] = Groups the user is
686    a member of<br>
687     $GLOBALS['phpgw_info']['user']['app_perms'] = If the user has
688    access to the current application<br>
689     $GLOBALS['phpgw_info']['user']['lastlogin'] = Last time the
690    user logged in.<br>
691     $GLOBALS['phpgw_info']['user']['lastloginfrom'] = Where they
692    logged in from the last time.<br>
693    $GLOBALS['phpgw_info']['user']['lastpasswd_change'] = Last time
694    they changed their password.<br>
695    $GLOBALS['phpgw_info']['user']['passwd'] = Hashed password.<br>
696    $GLOBALS['phpgw_info']['user']['status'] = If the user is
697    enabled.<br>
698    $GLOBALS['phpgw_info']['user']['logintime'] = Time they logged
699    into their current session.<br>
700    $GLOBALS['phpgw_info']['user']['session_dla'] = Last time they
701    did anything in their current session<br>
702    $GLOBALS['phpgw_info']['user']['session_ip'] = Current IP
703    address<br>
704    </font></tt>
705
706    <h3><tt><a name="tth_sEc6.3">6.3</a>&nbsp;&nbsp;Group
707    information</tt></h3>
708    <tt><font size=
709    "-1">$GLOBALS['phpgw_info']['group']['group_names'] = List of
710    groups.</font></tt>
711
712    <h3><a name="tth_sEc6.4">6.4</a>&nbsp;&nbsp;Server
713    information</h3>
714    <tt><font size="-1">$phpgw_info[``server''][``server_root''] =
715    Main installation directory
716    $phpgw_info[``server''][``include_root''] = Location of the
717    'inc' directory. $phpgw_info[``server''][``temp_dir''] =
718    Directory that can be used for temporarily storing files
719    $phpgw_info[``server''][``files_dir''] = Directory er and group
720    files are stored
721    $phpgw_info[``server''][``common_include_dir''] = Location of
722    the core/shared include files.
723    $phpgw_info[``server''][``template_dir''] = Active template
724    files directory. This is defaulted by the server, and
725    changeable by the user.
726    $phpgw_info[``server''][``dir_separator''] = Allows
727    compatibility with WindowsNT directory format
728    $phpgw_info[``server''][``encrpytkey''] = Key used for
729    encryption functions $phpgw_info[``server''][``site_title''] =
730    Site Title will show in the title bar of each webpage.
731    $phpgw_info[``server''][``webserver_url''] = URL to eGroupWare
732    installation. $phpgw_info[``server''][``hostname''] = Name of
733    the server eGroupWare is installed upon.
734    $phpgw_info[``server''][``charset''] = default charset,
735    default:iso-8859-1 $phpgw_info[``server''][``version''] =
736    eGroupWare version.</font></tt>
737
738    <h3><tt><font size="-1"><a name=
739    "tth_sEc6.5">6.5</a>&nbsp;&nbsp;Database
740    information</font></tt></h3>
741
742    <p>It is unlikely you will need these, because
743    $GLOBALS['phpgw']-&gt;db will already be loaded as a database
744    for you to use.</p>
745    <tt><font size="-1">$phpgw_info[``server''][``db_host''] =
746    Address of the database server. Usually this is set to
747    localhost. $phpgw_info[``server''][``db_name''] = Database
748    name. $phpgw_info[``server''][``db_user''] = User name.
749    $phpgw_info[``server''][``db_pass''] = Password
750    $phpgw_info[``server''][``db_type''] = Type of database.
751    Currently MySQL and PostgreSQL are supported.</font></tt>
752
753    <h3><a name="tth_sEc6.6">6.6</a>&nbsp;&nbsp;Mail
754    information</h3>
755
756    <p>It is unlikely you will need these, because most email needs
757    are services thru core eGroupWare functions.</p>
758
759    <p><tt><font size="-1">$phpgw_info[``server''][``mail_server'']
760    = Address of the IMAP server. Usually this is set to
761    localhost.</font></tt></p>
762
763    <p><tt><font size=
764    "-1">$phpgw_info[``server''][``mail_server_type''] = IMAP or
765    POP3</font></tt></p>
766
767    <p><tt><font size=
768    "-1">$phpgw_info[``server''][``imap_server_type''] = Cyrus or
769    Uwash</font></tt></p>
770
771    <p><tt><font size="-1">$phpgw_info[``server''][``imap_port''] =
772    This is usually 143, and should only be changed if there is a
773    good reason.</font></tt></p>
774
775    <p><tt><font size="-1">$phpgw_info[``server''][``mail_suffix] =
776    This is the domain name, used to add to email
777    address</font></tt></p>
778
779    <p><tt><font size=
780    "-1">$phpgw_info[``server''][``mail_login_type''] = This adds
781    support for VMailMgr. Generally this should be set to
782    'standard'.</font></tt></p>
783
784    <p><tt><font size="-1">$phpgw_info[``server''][``smtp_server'']
785    = Address of the SMTP server. Usually this is set to
786    localhost.</font></tt></p>
787
788    <p><tt><font size="-1">$phpgw_info[``server''][``smtp_port''] =
789    This is usually 25, and should only be changed if there is a
790    good reason</font></tt></p>
791
792    <h3><a name="tth_sEc6.7">6.7</a>&nbsp;&nbsp;NNTP
793    information</h3>
794
795    <p><tt><font size="-1">$phpgw_info[``server''][``nntp_server'']
796    = Address of the NNTP server.</font></tt></p>
797
798    <p><tt><font size="-1">$phpgw_info[``server''][``nntp_port''] =
799    This is usually XX, and should only be changed if there is a
800    good reason.</font></tt></p>
801
802    <p><tt><font size="-1">$phpgw_info[``server''][``nntp_sender'']
803    = Unknown</font></tt></p>
804
805    <p><tt><font size=
806    "-1">$phpgw_info[``server''][``nntp_organization''] =
807    Unknown</font></tt></p>
808
809    <p><tt><font size="-1">$phpgw_info[``server''][``nntp_admin'']
810    = Unknown</font></tt></p>
811
812    <h3><a name="tth_sEc6.8">6.8</a>&nbsp;&nbsp;Application
813    information</h3>
814
815    <p>Each application has the following information
816    available.</p>
817
818    <p><tt><font size=
819    "-1">$phpgw_info[``apps''][``appname''][``title''] = The title
820    of the application.</font></tt></p>
821
822    <p><tt><font size=
823    "-1">$phpgw_info[``apps''][``appname''][``enabled''] = If the
824    application is enabled. True or False.</font></tt></p>
825
826    <p><tt><font size=
827    "-1">$phpgw_info[``server''][``app_include_dir''] = Location of
828    the current application include files.</font></tt></p>
829
830    <p><tt><font size=
831    "-1">$phpgw_info[``server''][``app_template_dir''] = Location
832    of the current application tpl files.</font></tt></p>
833
834    <p><tt><font size=
835    "-1">$phpgw_info[``server''][``app_lang_dir''] = Location of
836    the current lang directory.</font></tt></p>
837
838    <p><tt><font size="-1">$phpgw_info[``server''][``app_auth''] =
839    If the server and current user have access to current
840    application</font></tt></p>
841
842    <p><tt><font size="-1">$phpgw_info[``server''][``app_current'']
843    = name of the current application.</font></tt></p>
844
845    <h2><a name="tth_sEc7">7</a>&nbsp;&nbsp;Using Language
846    Support</h2>
847
848    <h3><a name="tth_sEc7.1">7.1</a>&nbsp;&nbsp;Overview</h3>
849
850    <p>eGroupWare is built using a multi-language support scheme.
851    This means the pages can be translated to other languages very
852    easily. Translations of text strings are stored in the
853    eGroupWare database, and can be modified by the eGroupWare
854    administrator.</p>
855
856    <h3><a name="tth_sEc7.2">7.2</a>&nbsp;&nbsp;How to use lang
857    support</h3>
858
859    <p>The lang() function is your application's interface to
860    eGroupWare's internationalization support.</p>
861
862    <p>While developing your application, just wrap all your text
863    output with calls to lang(), as in the following code:</p>
864<pre>
865$x = 42;
866echo lang("The counter is %1",$x)."&lt;br&gt;";
867</pre>
868    This will attempt to translate ``The counter is %1'', and
869    return a translated version based on the current application
870    and language in use. Note how the position that $x will end up
871    is controlled by the format string, <b>not</b> by building up
872    the string in your code. This allows your application to be
873    translated to languages where the actual number is not placed
874    at the end of the string.
875
876    <p>When a translation is not found, the original text will be
877    returned with a * after the string. This makes it easy to
878    develop your application, then go back and add missing
879    translations (identified by the *) later.</p>
880
881    <p>Without a specific translation in the lang table, the above
882    code will print:</p>
883<pre>
884The counter is 42*&lt;br&gt;
885</pre>
886    If the current user speaks Italian, they string returned may
887    instead be:
888<pre>
889il contatore &egrave; 42&lt;br&amp;#gt;
890</pre>
891
892    <h4>The lang function</h4>
893<pre>
894lang($key, $m1="", $m2="", $m3="", $m4="", $m5="",
895        $m6="", $m7="", $m8="", $m9="", $m10="")
896
897</pre>
898
899    <dl compact="compact">
900      <dd>
901        [$key&nbsp;]&nbsp;
902
903        <p>is the string to translate and may contain replacement
904        directives of the form %n.<br>
905        </p>
906      </dd>
907
908      <dd>
909        [$m1&nbsp;]&nbsp;
910
911        <p>is the first replacement value or may be an array of
912        replacement values (in which case $m2 and above are
913        ignored).</p>
914      </dd>
915
916      <dd>
917        [$m2&nbsp;-&nbsp;$m10&nbsp;]&nbsp;
918
919        <p>the 2nd through 10th replacement values if $m1 is not an
920        array.</p>
921      </dd>
922    </dl>
923    The database is searched for rows with a lang.message_id that
924    matches $key. If a translation is not found, the original $key
925    is used. The translation engine then replaces all tokens of the
926    form %N with the Nth parameter (either $m1[N] or $mN).
927
928    <h4>Adding translation data</h4>
929
930    <p>The <b>TranslationTools</b> (former developer_tools) allow easily create new translations of eGW applications.<br />
931        A developer also can use them to create the english lang-file by searching for new phrases in his sources.</p>
932
933    <h4>The lang table</h4>
934
935    <p>The translation class uses the lang table for all
936    translations. We are concerned with 4 of the columns to create
937    a translation:</p>
938
939    <dl compact="compact">
940      <dd>
941        [message_id&nbsp;]&nbsp;
942
943        <p>The key to identify the message (the $key passed to the
944        lang() function). This is written in English.</p>
945      </dd>
946
947      <dd>
948        [app_name&nbsp;]&nbsp;
949
950        <p>The application the translation applies to, or common if
951        it is common across multiple applications.</p>
952      </dd>
953
954      <dd>
955        [lang&nbsp;]&nbsp;
956
957        <p>The code for the language the translation is in.</p>
958      </dd>
959
960      <dd>
961        [content&nbsp;]&nbsp;
962
963        <p>The translated string.</p>
964      </dd>
965    </dl>
966
967    translating the content to reflect the message_id string in the
968    lang language. If the string is specific to your application,
969    put your application name in for app_name otherwise use the
970    name common. The message_id should be in lower case for a small
971    increase in speed.
972
973    <h3><a name="tth_sEc7.3">7.3</a>&nbsp;&nbsp;Common return
974    codes</h3>
975
976    <p>If you browse through the eGroupWare sources, you may notice
977    a pattern to the return codes used in the higher-level
978    functions. The codes used are partially documented in the
979    doc/developers/CODES file.</p>
980
981    <p>Codes are used as a simple way to communicate common error
982    and progress conditions back to the user. They are mapped to a
983    text string through the check_code() function, which passes the
984    strings through lang() before returning.</p>
985
986    <p>For example, calling</p>
987<pre>
988echo check_code(13);
989
990
991</pre>
992    Would print
993<pre>
994Your message has been sent
995
996
997</pre>
998    translated into the current language.
999
1000    <h2><a name="tth_sEc8">8</a>&nbsp;&nbsp;Using Templates</h2>
1001
1002    <h3><a name="tth_sEc8.1">8.1</a>&nbsp;&nbsp;Overview</h3>
1003
1004    <p>eGroupWare is built using a templates based design. This
1005    means the display pages, stored in tpl files, can be translated
1006    to other languages, made to look completely different.</p>
1007
1008    <h3><a name="tth_sEc8.2">8.2</a>&nbsp;&nbsp;How to use PHPLIB
1009    templates</h3>
1010
1011    <p>For Further info read the PHPLIBs documentation for their
1012    template class. <a href=
1013    "http://phplib.sanisoft.com"><tt>http://phplib.sanisoft.com</tt></a></p>
1014
1015    <h3><a name="tth_sEc8.3">8.3</a>&nbsp;&nbsp;How to use
1016    eTemplate templates</h3>
1017
1018    <p><b>eTemplate</b> is a new widget-based template system,
1019    which is used eg. for the InfoLog application.<br />
1020    There's a <a href="../../etemplate/doc/etemplate.html">Tutorial</a>
1021    and a <a href="../../etemplate/doc/referenz.html">Referenz
1022    documentation</a> availible.</p>
1023
1024    <h2><a name="tth_sEc9">9</a>&nbsp;&nbsp;About this
1025    document</h2>
1026
1027    <h3><a name="tth_sEc9.1">9.1</a>&nbsp;&nbsp;New versions</h3>
1028
1029    <p>The newest version of this document can be found on our
1030    website <a href=
1031    "http://www.eGroupWare.org/egroupware/phpgwapi/doc/"><tt>http://www.eGroupWare.org</tt></a>.</p>
1032
1033    <h3><a name="tth_sEc9.2">9.2</a>&nbsp;&nbsp;Comments</h3>
1034
1035    <p>Comments on this HOWTO should be directed to the <a href=
1036    "mailto:eGroupWare-developers%20-AT-%20lists.sourceforge.net">eGroupWare
1037    developers mailing list</a> (subscription at <a href=
1038    "http://www.sourceforge.net/egroupware/">www.sourceforge.net/egroupware/</a>).</p>
1039
1040    <h3><a name="tth_sEc9.3">9.3</a>&nbsp;&nbsp;History</h3>
1041
1042    <p>This document was written by Dan Kuykendall.</p>
1043
1044    <p>2000-09-25 documentation on lang(), codes, administration
1045    and preferences extension added by Steve Brown.</p>
1046
1047    <p>2001-01-08 fixed directory structure, minor layout changes,
1048    imported to lyx source - Darryl VanDorp</p>
1049
1050    <p>2001-01-08 fixed directory structure, minor layout changes,
1051    imported to lyx source - Darryl VanDorp</p>
1052
1053    <p>2004-02-22 imported skwashd's changes and adapted for
1054    eGroupWare - Ralf Becker</p>
1055
1056    <h3><a name="tth_sEc9.4">9.4</a>&nbsp;&nbsp;Copyrights and
1057    Trademarks</h3>
1058
1059    <p>Copyright &copy; Free Software Foundarion. Permission is
1060    granted to copy, distribute and/or modify this document under
1061    the terms of the GNU Free Documentation License, Version 1.1 or
1062    any later version published by the Free Software
1063    Foundation.</p>
1064
1065    <p>A copy of the license is available at <a href=
1066    "http://www.gnu.org/copyleft/gpl.html"><tt>http://www.gnu.org/copyleft/gpl.html</tt></a></p>
1067
1068    <h3><a name="tth_sEc9.5">9.5</a>&nbsp;&nbsp;Acknowledgments and
1069    Thanks</h3>
1070
1071    <p>Thanks to Joesph Engo for starting eGroupWare (at the time
1072    called webdistro). Thanks to all the developers and users who
1073    contribute to making eGroupWare such a success.<br>
1074    <br>
1075    </p>
1076    <hr>
1077
1078    <p>$Id: index.html,v 1.5 2004/02/23 00:24:21 ralfbecker Exp
1079    $</p>
1080  </body>
1081</html>
1082
Note: See TracBrowser for help on using the repository browser.