Added documentation on hook facility for preferences and admin pages.

Added docs on the DB based lang() function, and the standard return codes.
Ran the whole thing through aspell to clean up typos.

doc/developers/phpGW_Developers-HOWTO-1.html

@@ -25,7 +25,7 @@ We hope any pain and suffering is cause by making your application work, but not
 </H2>
 
 <P>The phpGroupWare API handles session management, user/group management, has support for multiple databases, using the PHPLIB database abstraction method, we support templates using the PHPLIB Templates class, a file system interface, and even a network i/o interface.<BR>
-On top of these standard functions, phpgroupWare provides several functions to give you the information you need about the users environment, and to properly plug into phpgroupWare.
+On top of these standard functions, phpGroupWare provides several functions to give you the information you need about the users environment, and to properly plug into phpGroupWare.
 <HR>
 <A HREF="phpGW_Developers-HOWTO-2.html">Next</A>
 Previous

doc/developers/phpGW_Developers-HOWTO-2.html

@@ -26,7 +26,7 @@ It must use "post" for forms.<BR>
 It must respect phpGW group rights and phpGW user permissions.<BR>
 It must use our directory structure, template support and lang (multi-language) support.<BR>
 Where possible it should run on both Unix and NT platforms.
-<P>For applications that do not meet these requirements, they can be avalible to users via the phpGroupWare Apps project, or whatever means the developers decide.<BR>
+<P>For applications that do not meet these requirements, they can be available to users via the phpGroupWare Apps project, or whatever means the developers decide.<BR>
 If you need help converting your application to templates and our lang support, we will try to connect you with someone to help.
 <H2><A NAME="ss2.2">2.2 Writing/porting your application</A>
 </H2>
@@ -49,9 +49,9 @@ This include will provide the following things:
 <UL>
 <LI> The phpgwAPI - The phpGroupWare API will be loaded.</LI>
 <LI> The phpGW navbar will be loaded (by default, but can be disabled until a later point.</LI>
-<LI> appname/inc/functions.inc.php - This file is loaded just after the phpgwAPI and before any html code is generated. This file should include all your application specific functions.. You are welcome to include any additional files you need from within this file.</LI>
+<LI> appname/inc/functions.inc.php - This file is loaded just after the phpgwAPI and before any HTML code is generated. This file should include all your application specific functions.. You are welcome to include any additional files you need from within this file.</LI>
 <LI> appname/inc/header.inc.php - This file is loaded just after the system header/navbar, and allows developers to use it for whatever they need to load.</LI>
-<LI> appname/inc/footer.inc.php - This file is loaded just before the system footer, allowing developers to close connections and whetever else they need.</LI>
+<LI> appname/inc/footer.inc.php - This file is loaded just before the system footer, allowing developers to close connections and whatever else they need.</LI>
 <LI> The phpGW footer will be loaded, which closes several connections.</LI>
 </UL>
 <P>

doc/developers/phpGW_Developers-HOWTO-3.html

@@ -25,7 +25,7 @@
 <UL>
 <LI> appname/inc/functions.inc.php - This file should include all your application specific functions.</LI>
 <LI> appname/inc/header.inc.php - This file is loaded just after the system header/navbar, and allows developers to use it for whatever they need to load.</LI>
-<LI> appname/inc/footer.inc.php - This file is loaded just before the system footer, allowing developers to close connections and whetever else they need.</LI>
+<LI> appname/inc/footer.inc.php - This file is loaded just before the system footer, allowing developers to close connections and whatever else they need.</LI>
 </UL>
 <H2><A NAME="ss3.3">3.3 Adding files, directories and icons.</A>
 </H2>
@@ -39,7 +39,9 @@
       `-- inc
       |   |-- functions.inc.php
       |   |-- header.inc.php
-      |   `-- footer.inc.php
+      |   |-- footer.inc.php
+      |   |-- preferences.inc.php
+      |   `-- admin.inc.php
       `-- templates
           `-- default
   
@@ -47,10 +49,59 @@
 <H2><A NAME="ss3.4">3.4 Making phpGroupWare aware of your application</A>
 </H2>
 
-<P>To make the application aware of your application, add your application details to the applications table. This can be done via the GUI administration screen, or via a sql script.
+<P>To make the application aware of your application, add your application details to the applications table. This can be done via the GUI administration screen, or via a SQL script.
 <PRE>
   insert into applications (app_name, app_title, app_enabled) values ('appname', 'The App name', 1);
 </PRE>
+<H2><A NAME="ss3.5">3.5 Hooking into Administration page</A>
+</H2>
+
+<P>When a user goes to the Administration page, it stats appname/inc/admin.inc.php
+for each application that is enabled, in alphabetical order of application title.
+If the file exists, it is include()d in the hopes it will display a selection of
+links to configure that application.
+<P>Simple Example:
+<HR>
+<PRE>
+&lt;?php
+  $img = "/" . $appname . "/images/navbar.gif";
+  section_start("My Application",$img);
+  echo "&lt;a HREF=\"" . $phpgw->link("myAdminPage.php") . "\"&gt;";
+  echo lang("Change myApp settings") . "&lt;/a&gt;";
+  section_end();
+?>
+</PRE>
+<HR>
+
+Look at headlines/inc/admin.inc.php and admin/inc/admin.inc.php for more examples.
+<P>Things to note:
+<UL>
+<LI>Links are relative to the admin/index.php file, not your application's
+base directory. (so use <CODE>$appname</CODE> in your <CODE>link()</CODE> calls)</LI>
+<LI>The file is brought in with include() so be careful to not pollute the name-space too much</LI>
+</UL>
+
+The standard $phpgw and $phpgw_info variables are in-scope, as is $appname
+which corresponds to the application name in the path.
+<P>There are 2 functions to coordinate the display of each application's links,
+section_start() and section_end()
+<H3>section_start</H3>
+
+<P><CODE>section_start($title,$icon_url)</CODE>
+starts the section for your application. <CODE>$title</CODE> is passed through <CODE>lang()</CODE>
+for you. <CODE>$icon_url</CODE> should be page-relative to admin/index.php or an absolute URL.
+<P>
+<H3>section_end</H3>
+
+<P><CODE>section_end()</CODE> closes the section that was started with section_start().
+<P>
+<H2><A NAME="ss3.6">3.6 Hooking into Preferences page</A>
+</H2>
+
+<P>The mechanism to hook into the preferences page is identical to the one used to
+hook into the administration page, however it looks for 
+<CODE>appname/inc/preferences.inc.php</CODE> instead of 
+<CODE>appname/inc/admin.inc.php</CODE>. The same functions and variables are defined.
 <HR>
 <A HREF="phpGW_Developers-HOWTO-4.html">Next</A>
 <A HREF="phpGW_Developers-HOWTO-2.html">Previous</A>

doc/developers/phpGW_Developers-HOWTO-4.html

@@ -2,7 +2,7 @@
 <HTML>
 <HEAD>
  <META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
- <TITLE>  phpGroupWare Application Development: Infastructure</TITLE>
+ <TITLE>  phpGroupWare Application Development: Infrastructure</TITLE>
  <LINK HREF="phpGW_Developers-HOWTO-5.html" REL=next>
  <LINK HREF="phpGW_Developers-HOWTO-3.html" REL=previous>
  <LINK HREF="phpGW_Developers-HOWTO.html#toc4" REL=contents>
@@ -12,13 +12,13 @@
 <A HREF="phpGW_Developers-HOWTO-3.html">Previous</A>
 <A HREF="phpGW_Developers-HOWTO.html#toc4">Contents</A>
 <HR>
-<H2><A NAME="s4">4. Infastructure</A></H2>
+<H2><A NAME="s4">4. Infrastructure</A></H2>
 
 <H2><A NAME="ss4.1">4.1 Overview</A>
 </H2>
 
 <P>phpGroupWare attempts to provide developers with a sound directory structure to work from.<BR>
-The directory layout may seem complex at first, but after some use, you will see that it is designed to accommidate a large number of applications and functions.
+The directory layout may seem complex at first, but after some use, you will see that it is designed to accommodate a large number of applications and functions.
 <H2><A NAME="ss4.2">4.2 Directory tree</A>
 </H2>
 
@@ -39,7 +39,8 @@ The directory layout may seem complex at first, but after some use, you will see
 |   `-- inc
 |   |   |-- functions.inc.php
 |   |   |-- header.inc.php
-|   |   `-- footer.inc.php
+|   |   |-- footer.inc.php
+|   |   `-- admin.inc.php
 |   `-- templates
 |       `-- default
 |-- calendar
@@ -59,7 +60,9 @@ The directory layout may seem complex at first, but after some use, you will see
 |   `-- inc
 |   |   |-- functions.inc.php
 |   |   |-- header.inc.php
-|   |   `-- footer.inc.php
+|   |   |-- footer.inc.php
+|   |   |-- preferences.inc.php
+|   |   `-- admin.inc.php
 |   `-- templates
 |       `-- default
 |-- filemanager
@@ -68,9 +71,9 @@ The directory layout may seem complex at first, but after some use, you will see
 |   `-- users
 |-- inc
 |   |-- phpgwapi
-    |   |-- phpgw.inc.php
+|   |   |-- phpgw.inc.php
-    |   |-- phpgw_info.inc.php
+|   |   |-- phpgw_info.inc.php
-    |   |-- phpgw_common.inc.php
+|   |   |-- phpgw_common.inc.php
 |   |   `-- etc...
 |   `-- templates
 |       |-- default
@@ -94,7 +97,8 @@ The directory layout may seem complex at first, but after some use, you will see
 |   `-- inc
 |   |   |-- functions.inc.php
 |   |   |-- header.inc.php
-|   |   `-- footer.inc.php
+|   |   |-- footer.inc.php
+|   |   `-- preferences.inc.php
 |   `-- templates
 |       `-- default
 |-- themes
@@ -114,7 +118,7 @@ The directory layout may seem complex at first, but after some use, you will see
 
 <P>The translations are now being done thru the database, and will be configurable to use other mechanisms.<BR>
 We are completing a program called Transy, which will provide developers/translators a nice GUI for building and updating translations.<BR>
-In the mean time you will need to create a sql script yourself and name it lang.sql. You can copy the one in doc/lang.sql and use it as a template.  
+In the mean time you will need to create a SQL script yourself and name it lang.sql. You can copy the one in doc/lang.sql and use it as a template.  
 <HR>
 <A HREF="phpGW_Developers-HOWTO-5.html">Next</A>
 <A HREF="phpGW_Developers-HOWTO-3.html">Previous</A>

doc/developers/phpGW_Developers-HOWTO-5.html

@@ -20,7 +20,7 @@
 <P>phpGroupWare attempts to provide developers with a useful API to handle common tasks.<BR>
 To do this we have created a multi-dimensional class $phpgw->.<BR>
 This allows for terrific code organization, and help developers easily identify the file that the function is in.
-All the files that are patr of this class are in the inc/core directory and are named to match the sub-class.<BR>
+All the files that are part of this class are in the inc/core directory and are named to match the sub-class.<BR>
 Example:
 <CODE>$phpgw->send->msg()</CODE> is in the <CODE>inc/phpgwapi/phpgw_send.inc.php</CODE> file.
 <H2><A NAME="ss5.2">5.2 Basic functions</A>
@@ -30,13 +30,13 @@ Example:
 
 <P><CODE>$phpgw->link($url)</CODE><BR>
 Add support for session management. ALL links must use this, that includes href's form actions and header location's.<BR>
-If you are just doing a form action back to the same page, you can use it without any paramaters.<BR>
+If you are just doing a form action back to the same page, you can use it without any parameters.<BR>
 This function is right at the core of the class because it is used so often, we wanted to save developers a few keystrokes.
 Example:
 <HR>
 <PRE>
 &lt;form name=copy method=post action="&lt;?php echo $phpgw->link();?>">
-/* If session management is done via passing url paramaters */
+/* If session management is done via passing url parameters */
 /* The the result would be */
 /* &lt;form name=copy method=post action="somepage.php?sessionid=87687693276?kp3=kjh98u80"> */
 </PRE>
@@ -49,8 +49,8 @@ Example:
 
 <P><CODE>$phpgw->common->appsession($data)</CODE><BR>
 Store important information session information that your application needs.<BR>
-<CODE>$phpgw->appsession</CODE> will return the value of your session data is you leave the paramater enmpty [i.e. <CODE>$phpgw->appsession("")</CODE>], otherwise it will store whatever data you send to it.<BR>
+<CODE>$phpgw->appsession</CODE> will return the value of your session data is you leave the parameter empty [i.e. <CODE>$phpgw->appsession("")</CODE>], otherwise it will store whatever data you send to it.<BR>
-You can also store a comma delimited string and use <CODE>explode()</CODE> to turn it back into an array when you recieve the value back.<BR>
+You can also store a comma delimited string and use <CODE>explode()</CODE> to turn it back into an array when you receive the value back.<BR>
 Example:
 <HR>
 <PRE>

doc/developers/phpGW_Developers-HOWTO-6.html

@@ -42,7 +42,7 @@ Here are some examples:
 <P><CODE>$phpgw_info["user"]["userid"] = </CODE>The user ID.<BR>
 <CODE>$phpgw_info["user"]["sessionid"] = </CODE>The session ID<BR>
 <CODE>$phpgw_info["user"]["theme"] = </CODE>Selected theme<BR>
-<CODE>$phpgw_info["user"]["private_dir"] = </CODE>Users private dir. Use phpgroupware core functions for access to the files.<BR>
+<CODE>$phpgw_info["user"]["private_dir"] = </CODE>Users private dir. Use phpGroupWare core functions for access to the files.<BR>
 <CODE>$phpgw_info["user"]["firstname"] = </CODE>Users first name<BR>
 <CODE>$phpgw_info["user"]["lastname"] = </CODE>Users last name<BR>
 <CODE>$phpgw_info["user"]["fullname"] = </CODE>Users Full Name<BR>
@@ -92,7 +92,7 @@ Here are some examples:
 <CODE>$phpgw_info["server"]["imap_server_type"] = </CODE>Cyrus or Uwash<BR>
 <CODE>$phpgw_info["server"]["imap_port"] = </CODE>This is usually 143, and should only be changed if there is a good reason.<BR>
 <CODE>$phpgw_info["server"]["mail_suffix] = </CODE>This is the domain name, used to add to email address<BR>
-<CODE>$phpgw_info["server"]["mail_login_type"] = </CODE>This adds support for VMailMgr. Generally this hsould be set to '<CODE>standard</CODE>'.<BR>
+<CODE>$phpgw_info["server"]["mail_login_type"] = </CODE>This adds support for VMailMgr. Generally this should be set to '<CODE>standard</CODE>'.<BR>
 <CODE>$phpgw_info["server"]["smtp_server"] = </CODE>Address of the SMTP server. Usually this is set to localhost.<BR>
 <CODE>$phpgw_info["server"]["smtp_port"] = </CODE>This is usually 25, and should only be changed if there is a good reason.<BR>
 <H2><A NAME="ss6.7">6.7 NNTP information</A>
@@ -102,11 +102,11 @@ Here are some examples:
 <CODE>$phpgw_info["server"]["nntp_port"] = </CODE>This is usually XX, and should only be changed if there is a good reason.<BR>
 <CODE>$phpgw_info["server"]["nntp_sender"] = </CODE>Unknown<BR>
 <CODE>$phpgw_info["server"]["nntp_organization"] = </CODE>Unknown<BR>
-<CODE>$phpgw_info["server"]["nntp_admin"] = </CODE>Uknown<BR>
+<CODE>$phpgw_info["server"]["nntp_admin"] = </CODE>Unknown<BR>
 <H2><A NAME="ss6.8">6.8 Application information</A>
 </H2>
 
-<P>Each application has the following information avalible.
+<P>Each application has the following information available.
 <CODE>$phpgw_info["apps"]["appname"]["title"] = </CODE>The title of the application.<BR>
 <CODE>$phpgw_info["apps"]["appname"]["enabled"] = </CODE>If the application is enabled. True or False.<BR>
 <CODE>$phpgw_info["server"]["app_include_dir"] = </CODE>Location of the current application include files.<BR>

doc/developers/phpGW_Developers-HOWTO-7.html

@@ -17,44 +17,117 @@
 <H2><A NAME="ss7.1">7.1 Overview</A>
 </H2>
 
-<P>phpGroupWare is built using a multi-language support scheme. This means the pages can be translated to other languages
+<P>phpGroupWare is built using a multi-language support scheme. This means the pages can be 
-very easily. It is done thru a series of lang files, which can be translated and selected by the user.
+translated to other languages very easily. Translations of text strings are
+stored in the phpGroupWare database, and can be modified by the phpGroupWare
+administrator.
 <H2><A NAME="ss7.2">7.2 How to use lang support</A>
 </H2>
 
-<P>Some instructions on using the lang files.<BR>
+<P>The <CODE>lang()</CODE> function is your application's interface to phpGroupWare's
-Under inc/lang there needs to be a sub-directory for each langague.  Inside the
+internationalization support. 
-directory there are a number of files for each application.  There is one common file
+<P>While developing your application, just wrap all your text output with calls to
-which contains a list of words that all applications use.  ie, add, delete, edit, etc...<BR>
+lang(), as in the following code:
-Words that are specific to a application should be stored with that applications include file.
 <HR>
 <PRE>
-  function lang_todo($message, $m1 = "", $m2 = "", $m3 = "", $m4 = "")
+  $x = 42;
-  {
+  echo lang("The counter is %1",$x)."&lt;br&gt;";
-    $message = strtolower($message);
-    switch($message)
-    {
-       case "urgency": $s = "Urgency"; break;
-       case "completed": $s = "completed"; break;
-       [ snip ]
-       default: $s = "&lt;b&gt;*&lt;/b&gt; " . $message;
-    }
-    return $s;
-  }
-  
 </PRE>
 <HR>
 
-The list of words in the left column should always be written in english.  The
+This will attempt to translate "The counter is %1", and return a translated version
-second column is used to return those words in that includes language.  <CODE>$m1, $m2,
+based on the current application and language in use. Note how the position that
-$m3, and $m4</CODE> are used to pass extra data to be place in the middle of a sentence.<BR>
+<CODE>$x</CODE> will end up is controlled by the format string, <B>not</B> by
-For example:
+building up the string in your code. This allows your application to be translated
+to languages where the actual number is not placed at the end of the string.
+<P>When a translation is not found, the original text will be returned with a * after 
+the string.  This makes it easy to develop your application, then go back and 
+add missing translations (identified by the *) later. 
+<P>Without a specific translation in the lang table, the above code will print:
 <PRE>
-You have 29 new messages!
+The counter is 42*&lt;br&gt; 
 </PRE>
 
-The default should return a bold faced * and the word that wasn't found. This allows users to notice that something is missing in the files and make changes if
+If the current user speaks Italian, they string returned may instead be:
-necessary.
+<PRE>
+il contatore è 42&lt;br&gt;
+</PRE>
+<H3>The lang function</H3>
+
+<P>
+<PRE>
+lang($key, $m1="", $m2="", $m3="", $m4="", $m5="", 
+             $m6="", $m7="", $m8="", $m9="", $m10="")
+</PRE>
+
+<DL>
+<DT><B>$key</B><DD><P>is the string to translate and may contain replacement directives of the form <CODE>%n</CODE>.<BR>
+<DT><B>$m1</B><DD><P>is the first replacement value or may be an array of replacement values 
+(in which case $m2 and above are ignored).
+<DT><B>$m2 - $m10</B><DD><P>the 2nd through 10th replacement values if $m1 is not an array.
+</DL>
+
+The database is searched for rows with a <CODE>lang.message_id</CODE> that matches <CODE>$key</CODE>.
+If a translation is not found, the original <CODE>$key</CODE> is used. The translation engine then replaces
+all tokens of the form <CODE>%N</CODE> with the Nth parameter (either <CODE>$m1[N]</CODE> or <CODE>$mN</CODE>).
+<H3>Adding translation data</H3>
+
+<P>An application called <B>Transy</B> is being developed to make this easier, until then you can create
+the translation data manually.
+<P>
+<H3>The lang table</H3>
+
+<P>The translation class uses the lang table for all translations. 
+We are concerned with 4 of the columns to create a translation:
+<DL>
+<DT><B>message_id</B><DD><P>The key to identify the message (the <CODE>$key</CODE> passed
+to the <CODE>lang()</CODE> function). This is written in English.
+<DT><B>app_name</B><DD><P>The application the translation applies to, or 
+<CODE>common</CODE> if it is common across multiple applications.
+<DT><B>lang</B><DD><P>The code for the language the translation is in.
+<DT><B>content</B><DD><P>The translated string.
+</DL>
+<H3>lang.sql</H3>
+
+<P>Currently all applications, and the core phpGroupWare source tree
+have a <CODE>lang.sql</CODE> file. This is the place to add translation
+data. Just add lines of the form:
+<HR>
+<PRE>
+REPLACE INTO lang (message_id, app_name, lang, content) 
+VALUES( 'account has been deleted','common','en','Account has been deleted');
+</PRE>
+<HR>
+
+translating the <CODE>content</CODE> to reflect the <CODE>message_id</CODE> string in the <CODE>lang</CODE> language.
+If the string is specific to your application, put your application name in for <CODE>app_name</CODE>
+otherwise use the name <CODE>common</CODE>. The <CODE>message_id</CODE> should be in lower case for a small
+increase in speed.
+<H2><A NAME="ss7.3">7.3 Common return codes</A>
+</H2>
+
+<P>If you browse through the phpGroupWare sources, you may notice
+a pattern to the return codes used in the higher-level functions.
+The codes used are partially documented in the <CODE>doc/developers/CODES</CODE> 
+file. 
+<P>Codes are used as a simple way to communicate common error and progress
+conditions back to the user. They are mapped to a text string through the
+<CODE>check_code()</CODE> function, which passes the strings through
+<CODE>lang()</CODE> before returning.
+<P>For example, calling 
+<HR>
+<PRE>
+echo check_code(13);
+</PRE>
+<HR>
+
+Would print
+<PRE>
+Your message has been sent
+</PRE>
+
+translated into the current language.
+<P>
 <HR>
 <A HREF="phpGW_Developers-HOWTO-8.html">Next</A>
 <A HREF="phpGW_Developers-HOWTO-6.html">Previous</A>

doc/developers/phpGW_Developers-HOWTO-9.html

@@ -28,6 +28,7 @@ Next
 </H2>
 
 <P>This document was written by Dan Kuykendall.
+<P>2000-09-25 documentation on lang(), codes, administration and preferences extension added by Steve Brown.
 <H2><A NAME="ss9.4">9.4 Copyrights and Trademarks </A>
 </H2>
 
@@ -37,7 +38,7 @@ under the terms of the GNU Free Documentation License, Version 1.1
 or any later version published by the Free Software Foundation
 <P>A copy of the license is available at
 <A HREF="http://www.gnu.org/copyleft/fdl.txt">GNU Free Documentation License</A>.
-<H2><A NAME="ss9.5">9.5 Acknowledgements and Thanks </A>
+<H2><A NAME="ss9.5">9.5 Acknowledgments and Thanks </A>
 </H2>
 
 <P>Thanks to Joesph Engo for starting phpGroupWare (at the time called webdistro). 

doc/developers/phpGW_Developers-HOWTO.html

@@ -16,7 +16,7 @@ Contents
 
 <H2>Dan Kuykendall &lt;dan@kuykendall.org&gt;</H2>  v0.5, 09 September 2000
 <P><HR>
-<EM>  This document explains phpGroupWare's infastructure and API, along with what is required to integrate applications into it.</EM>
+<EM>  This document explains phpGroupWare's infrastructure and API, along with what is required to integrate applications into it.</EM>
 <HR>
 <P>
 <H2><A NAME="toc1">1.</A> <A HREF="phpGW_Developers-HOWTO-1.html">Introduction</A></H2>
@@ -40,9 +40,11 @@ Contents
 <LI><A HREF="phpGW_Developers-HOWTO-3.html#ss3.2">3.2 Automatic features</A>
 <LI><A HREF="phpGW_Developers-HOWTO-3.html#ss3.3">3.3 Adding files, directories and icons.</A>
 <LI><A HREF="phpGW_Developers-HOWTO-3.html#ss3.4">3.4 Making phpGroupWare aware of your application</A>
+<LI><A HREF="phpGW_Developers-HOWTO-3.html#ss3.5">3.5 Hooking into Administration page</A>
+<LI><A HREF="phpGW_Developers-HOWTO-3.html#ss3.6">3.6 Hooking into Preferences page</A>
 </UL>
 <P>
-<H2><A NAME="toc4">4.</A> <A HREF="phpGW_Developers-HOWTO-4.html">Infastructure</A></H2>
+<H2><A NAME="toc4">4.</A> <A HREF="phpGW_Developers-HOWTO-4.html">Infrastructure</A></H2>
 
 <UL>
 <LI><A HREF="phpGW_Developers-HOWTO-4.html#ss4.1">4.1 Overview</A>
@@ -78,6 +80,7 @@ Contents
 <UL>
 <LI><A HREF="phpGW_Developers-HOWTO-7.html#ss7.1">7.1 Overview</A>
 <LI><A HREF="phpGW_Developers-HOWTO-7.html#ss7.2">7.2 How to use lang support</A>
+<LI><A HREF="phpGW_Developers-HOWTO-7.html#ss7.3">7.3 Common return codes</A>
 </UL>
 <P>
 <H2><A NAME="toc8">8.</A> <A HREF="phpGW_Developers-HOWTO-8.html">Using Templates</A></H2>
@@ -94,7 +97,7 @@ Contents
 <LI><A HREF="phpGW_Developers-HOWTO-9.html#ss9.2">9.2 Comments </A>
 <LI><A HREF="phpGW_Developers-HOWTO-9.html#ss9.3">9.3 History </A>
 <LI><A HREF="phpGW_Developers-HOWTO-9.html#ss9.4">9.4 Copyrights and Trademarks </A>
-<LI><A HREF="phpGW_Developers-HOWTO-9.html#ss9.5">9.5 Acknowledgements and Thanks </A>
+<LI><A HREF="phpGW_Developers-HOWTO-9.html#ss9.5">9.5 Acknowledgments and Thanks </A>
 </UL>
 <HR>
 <A HREF="phpGW_Developers-HOWTO-1.html">Next</A>

doc/developers/phpGW_Developers-HOWTO.sgml

@@ -1,6 +1,14 @@
 <!doctype linuxdoc system>
 
 <!-- LinuxDoc file was created by hand by <Dan Kuykendall> 7 July 2000 -->
+<!--
+$Log$
+Revision 1.5  2000/09/26 15:56:24  sjb4891
+Added documentation on hook facility for preferences and admin pages.
+Added docs on the DB based lang() function, and the standard return codes.
+Ran the whole thing through aspell to clean up typos.
+
+-->
 <article>
 <title>
   phpGroupWare Application Development
@@ -12,7 +20,7 @@
   v0.5, 09 September 2000
 </date>
 <abstract>
-  This document explains phpGroupWare's infastructure and API, along with what is required to integrate applications into it.
+  This document explains phpGroupWare's infrastructure and API, along with what is required to integrate applications into it.
 </abstract>
 
 <toc>
@@ -29,7 +37,7 @@
 <sect1>What does the phpGroupWare API provide?
 <p>
   The phpGroupWare API handles session management, user/group management, has support for multiple databases, using the PHPLIB database abstraction method, we support templates using the PHPLIB Templates class, a file system interface, and even a network i/o interface.<newline>
-  On top of these standard functions, phpgroupWare provides several functions to give you the information you need about the users environment, and to properly plug into phpgroupWare.
+  On top of these standard functions, phpGroupWare provides several functions to give you the information you need about the users environment, and to properly plug into phpGroupWare.
 </p>
 <sect>Guidelines
 <sect1>Requirements
@@ -47,7 +55,7 @@
   Where possible it should run on both Unix and NT platforms.
 </p>
 <p>
-  For applications that do not meet these requirements, they can be avalible to users via the phpGroupWare Apps project, or whatever means the developers decide.<newline>
+  For applications that do not meet these requirements, they can be available to users via the phpGroupWare Apps project, or whatever means the developers decide.<newline>
   If you need help converting your application to templates and our lang support, we will try to connect you with someone to help.
 </P>
 <sect1>Writing/porting your application
@@ -66,9 +74,9 @@
   <itemize>
   <item> The phpgwAPI - The phpGroupWare API will be loaded.
   <item> The phpGW navbar will be loaded (by default, but can be disabled until a later point.
-  <item> appname/inc/functions.inc.php - This file is loaded just after the phpgwAPI and before any html code is generated. This file should include all your application specific functions.. You are welcome to include any additional files you need from within this file.
+  <item> appname/inc/functions.inc.php - This file is loaded just after the phpgwAPI and before any HTML code is generated. This file should include all your application specific functions.. You are welcome to include any additional files you need from within this file.
   <item> appname/inc/header.inc.php - This file is loaded just after the system header/navbar, and allows developers to use it for whatever they need to load.
-  <item> appname/inc/footer.inc.php - This file is loaded just before the system footer, allowing developers to close connections and whetever else they need.
+  <item> appname/inc/footer.inc.php - This file is loaded just before the system footer, allowing developers to close connections and whatever else they need.
   <item> The phpGW footer will be loaded, which closes several connections.
   </itemize>
   
@@ -85,7 +93,7 @@
   <itemize>
   <item> appname/inc/functions.inc.php - This file should include all your application specific functions.
   <item> appname/inc/header.inc.php - This file is loaded just after the system header/navbar, and allows developers to use it for whatever they need to load.
-  <item> appname/inc/footer.inc.php - This file is loaded just before the system footer, allowing developers to close connections and whetever else they need.
+  <item> appname/inc/footer.inc.php - This file is loaded just before the system footer, allowing developers to close connections and whatever else they need.
   </itemize>
 </p>
 <sect1>Adding files, directories and icons.
@@ -99,24 +107,72 @@
       `-- inc
       |   |-- functions.inc.php
       |   |-- header.inc.php
-      |   `-- footer.inc.php
+      |   |-- footer.inc.php
+      |   |-- preferences.inc.php
+      |   `-- admin.inc.php
       `-- templates
           `-- default
   </verb>
 </p>
 <sect1>Making phpGroupWare aware of your application
 <p>
-  To make the application aware of your application, add your application details to the applications table. This can be done via the GUI administration screen, or via a sql script.
+  To make the application aware of your application, add your application details to the applications table. This can be done via the GUI administration screen, or via a SQL script.
 <verb>
   insert into applications (app_name, app_title, app_enabled) values ('appname', 'The App name', 1);
 </verb>
 </p>
 
-<sect>Infastructure
+<sect1>Hooking into Administration page
+<P>
+When a user goes to the Administration page, it stats appname/inc/admin.inc.php
+for each application that is enabled, in alphabetical order of application title.
+If the file exists, it is include()d in the hopes it will display a selection of
+links to configure that application.
+
+Simple Example:
+<code>
+&lt;?php
+  $img = "/" . $appname . "/images/navbar.gif";
+  section_start("My Application",$img);
+  echo "&lt;a HREF=\"" . $phpgw->link("myAdminPage.php") . "\"&gt;";
+  echo lang("Change myApp settings") . "&lt;/a&gt;";
+  section_end();
+?>
+</code>
+Look at headlines/inc/admin.inc.php and admin/inc/admin.inc.php for more examples.
+
+Things to note:
+<itemize>
+<item>Links are relative to the admin/index.php file, not your application's
+   base directory. (so use <tt>$appname</tt> in your <tt>link()</tt> calls)</item>
+<item>The file is brought in with include() so be careful to not pollute the name-space too much</item>
+</itemize>
+The standard $phpgw and $phpgw_info variables are in-scope, as is $appname
+which corresponds to the application name in the path.
+
+There are 2 functions to coordinate the display of each application's links,
+section_start() and section_end()
+<sect2>section_start
+<P>
+<tt>section_start($title,$icon_url)</tt>
+starts the section for your application. <tt>$title</tt> is passed through <tt>lang()</tt>
+for you. <tt>$icon_url</tt> should be page-relative to admin/index.php or an absolute URL.
+
+<sect2>section_end
+<P>
+<tt>section_end()</tt> closes the section that was started with section_start().
+
+<sect1>Hooking into Preferences page
+<P>
+The mechanism to hook into the preferences page is identical to the one used to
+hook into the administration page, however it looks for 
+<tt>appname/inc/preferences.inc.php</tt> instead of 
+<tt>appname/inc/admin.inc.php</tt>. The same functions and variables are defined.
+<sect>Infrastructure
 <sect1>Overview
 <P>
   phpGroupWare attempts to provide developers with a sound directory structure to work from.<newline>
-  The directory layout may seem complex at first, but after some use, you will see that it is designed to accommidate a large number of applications and functions.
+  The directory layout may seem complex at first, but after some use, you will see that it is designed to accommodate a large number of applications and functions.
 </p>
 <sect1>Directory tree
 <p>
@@ -136,7 +192,8 @@
 |   `-- inc
 |   |   |-- functions.inc.php
 |   |   |-- header.inc.php
-|   |   `-- footer.inc.php
+|   |   |-- footer.inc.php
+|   |   `-- admin.inc.php
 |   `-- templates
 |       `-- default
 |-- calendar
@@ -156,7 +213,9 @@
 |   `-- inc
 |   |   |-- functions.inc.php
 |   |   |-- header.inc.php
-|   |   `-- footer.inc.php
+|   |   |-- footer.inc.php
+|   |   |-- preferences.inc.php
+|   |   `-- admin.inc.php
 |   `-- templates
 |       `-- default
 |-- filemanager
@@ -165,9 +224,9 @@
 |   `-- users
 |-- inc
 |   |-- phpgwapi
-    |   |-- phpgw.inc.php
+|   |   |-- phpgw.inc.php
-    |   |-- phpgw_info.inc.php
+|   |   |-- phpgw_info.inc.php
-    |   |-- phpgw_common.inc.php
+|   |   |-- phpgw_common.inc.php
 |   |   `-- etc...
 |   `-- templates
 |       |-- default
@@ -191,7 +250,8 @@
 |   `-- inc
 |   |   |-- functions.inc.php
 |   |   |-- header.inc.php
-|   |   `-- footer.inc.php
+|   |   |-- footer.inc.php
+|   |   `-- preferences.inc.php
 |   `-- templates
 |       `-- default
 |-- themes
@@ -210,7 +270,7 @@
 <p>
   The translations are now being done thru the database, and will be configurable to use other mechanisms.<newline>
   We are completing a program called Transy, which will provide developers/translators a nice GUI for building and updating translations.<newline>
-  In the mean time you will need to create a sql script yourself and name it lang.sql. You can copy the one in doc/lang.sql and use it as a template.  
+  In the mean time you will need to create a SQL script yourself and name it lang.sql. You can copy the one in doc/lang.sql and use it as a template.  
 </p>
 <sect>The API
 <sect1>Introduction
@@ -218,7 +278,7 @@
   phpGroupWare attempts to provide developers with a useful API to handle common tasks.<newline>
   To do this we have created a multi-dimensional class $phpgw->.<newline>
   This allows for terrific code organization, and help developers easily identify the file that the function is in.
-  All the files that are patr of this class are in the inc/core directory and are named to match the sub-class.<newline>
+  All the files that are part of this class are in the inc/core directory and are named to match the sub-class.<newline>
   Example:
   <tt>$phpgw->send->msg()</tt> is in the <tt>inc/phpgwapi/phpgw_send.inc.php</tt> file.
 <sect1>Basic functions
@@ -227,12 +287,12 @@
 <p>
 <tt>$phpgw->link($url)</tt><newline>
 Add support for session management. ALL links must use this, that includes href's form actions and header location's.<newline>
-If you are just doing a form action back to the same page, you can use it without any paramaters.<newline>
+If you are just doing a form action back to the same page, you can use it without any parameters.<newline>
 This function is right at the core of the class because it is used so often, we wanted to save developers a few keystrokes.
 Example:
 <code>
 <form name=copy method=post action="<?php echo $phpgw->link();?>">
-/* If session management is done via passing url paramaters */
+/* If session management is done via passing url parameters */
 /* The the result would be */
 /* <form name=copy method=post action="somepage.php?sessionid=87687693276?kp3=kjh98u80"> */
 </code>
@@ -243,8 +303,8 @@ Example:
 <p>
 <tt>$phpgw->common->appsession($data)</tt><newline>
 Store important information session information that your application needs.<newline>
-<tt>$phpgw->appsession</tt> will return the value of your session data is you leave the paramater enmpty [i.e. <tt>$phpgw->appsession("")</tt>], otherwise it will store whatever data you send to it.<newline>
+<tt>$phpgw->appsession</tt> will return the value of your session data is you leave the parameter empty [i.e. <tt>$phpgw->appsession("")</tt>], otherwise it will store whatever data you send to it.<newline>
-You can also store a comma delimited string and use <tt>explode()</tt> to turn it back into an array when you recieve the value back.<newline>
+You can also store a comma delimited string and use <tt>explode()</tt> to turn it back into an array when you receive the value back.<newline>
 Example:
 <code>
   $phpgw->common->appsession("/path/to/something");
@@ -344,7 +404,7 @@ $errors = $phpgw->msg->send("email", $to, $subject, $body);
   <tt>$phpgw_info["user"]["userid"] = </tt>The user ID.<newline>
   <tt>$phpgw_info["user"]["sessionid"] = </tt>The session ID<newline>
   <tt>$phpgw_info["user"]["theme"] = </tt>Selected theme<newline>
-  <tt>$phpgw_info["user"]["private_dir"] = </tt>Users private dir. Use phpgroupware core functions for access to the files.<newline>
+  <tt>$phpgw_info["user"]["private_dir"] = </tt>Users private dir. Use phpGroupWare core functions for access to the files.<newline>
   <tt>$phpgw_info["user"]["firstname"] = </tt>Users first name<newline>
   <tt>$phpgw_info["user"]["lastname"] = </tt>Users last name<newline>
   <tt>$phpgw_info["user"]["fullname"] = </tt>Users Full Name<newline>
@@ -394,7 +454,7 @@ $errors = $phpgw->msg->send("email", $to, $subject, $body);
   <tt>$phpgw_info["server"]["imap_server_type"] = </tt>Cyrus or Uwash<newline>
   <tt>$phpgw_info["server"]["imap_port"] = </tt>This is usually 143, and should only be changed if there is a good reason.<newline>
   <tt>$phpgw_info["server"]["mail_suffix] = </tt>This is the domain name, used to add to email address<newline>
-  <tt>$phpgw_info["server"]["mail_login_type"] = </tt>This adds support for VMailMgr. Generally this hsould be set to '<tt>standard</tt>'.<newline>
+  <tt>$phpgw_info["server"]["mail_login_type"] = </tt>This adds support for VMailMgr. Generally this should be set to '<tt>standard</tt>'.<newline>
   <tt>$phpgw_info["server"]["smtp_server"] = </tt>Address of the SMTP server. Usually this is set to localhost.<newline>
   <tt>$phpgw_info["server"]["smtp_port"] = </tt>This is usually 25, and should only be changed if there is a good reason.<newline>
 </p>
@@ -404,11 +464,11 @@ $errors = $phpgw->msg->send("email", $to, $subject, $body);
   <tt>$phpgw_info["server"]["nntp_port"] = </tt>This is usually XX, and should only be changed if there is a good reason.<newline>
   <tt>$phpgw_info["server"]["nntp_sender"] = </tt>Unknown<newline>
   <tt>$phpgw_info["server"]["nntp_organization"] = </tt>Unknown<newline>
-  <tt>$phpgw_info["server"]["nntp_admin"] = </tt>Uknown<newline>
+  <tt>$phpgw_info["server"]["nntp_admin"] = </tt>Unknown<newline>
 </p>
 <sect1>Application information
 <p>
-  Each application has the following information avalible.
+  Each application has the following information available.
   <tt>$phpgw_info["apps"]["appname"]["title"] = </tt>The title of the application.<newline>
   <tt>$phpgw_info["apps"]["appname"]["enabled"] = </tt>If the application is enabled. True or False.<newline>
   <tt>$phpgw_info["server"]["app_include_dir"] = </tt>Location of the current application include files.<newline>
@@ -420,40 +480,108 @@ $errors = $phpgw->msg->send("email", $to, $subject, $body);
 <sect>Using Language Support
 <sect1>Overview
 <P>
-  phpGroupWare is built using a multi-language support scheme. This means the pages can be translated to other languages
+  phpGroupWare is built using a multi-language support scheme. This means the pages can be 
-  very easily. It is done thru a series of lang files, which can be translated and selected by the user.
+translated to other languages very easily. Translations of text strings are
+stored in the phpGroupWare database, and can be modified by the phpGroupWare
+administrator.
 </p>
 <sect1>How to use lang support
 <p>
-  Some instructions on using the lang files.<newline>
+  The <tt>lang()</tt> function is your application's interface to phpGroupWare's
-  Under inc/lang there needs to be a sub-directory for each langague.  Inside the
+internationalization support. 
-  directory there are a number of files for each application.  There is one common file
+  
-  which contains a list of words that all applications use.  ie, add, delete, edit, etc...<newline>
+  While developing your application, just wrap all your text output with calls to
-  Words that are specific to a application should be stored with that applications include file.
+  lang(), as in the following code:
-  <code>
+<code>
-  function lang_todo($message, $m1 = "", $m2 = "", $m3 = "", $m4 = "")
+  $x = 42;
-  {
+  echo lang("The counter is %1",$x)."&lt;br&gt;";
-    $message = strtolower($message);
+</code>
-    switch($message)
+  This will attempt to translate "The counter is %1", and return a translated version
-    {
+  based on the current application and language in use. Note how the position that
-       case "urgency": $s = "Urgency"; break;
+  <tt>$x</tt> will end up is controlled by the format string, <bf>not</bf> by
-       case "completed": $s = "completed"; break;
+  building up the string in your code. This allows your application to be translated
-       [ snip ]
+  to languages where the actual number is not placed at the end of the string.
-       default: $s = "&lt;b&gt;*&lt;/b&gt; " . $message;
+
-    }
+  When a translation is not found, the original text will be returned with a * after 
-    return $s;
+  the string.  This makes it easy to develop your application, then go back and 
-  }
+  add missing translations (identified by the *) later. 
-  </code>
+
-The list of words in the left column should always be written in english.  The
+  Without a specific translation in the lang table, the above code will print:
-second column is used to return those words in that includes language.  <tt>$m1, $m2,
-$m3, and $m4</tt> are used to pass extra data to be place in the middle of a sentence.<newline>
-For example:
 <verb>
-You have 29 new messages!
+The counter is 42*&lt;br&gt; 
 </verb>
-The default should return a bold faced * and the word that wasn't found. This allows users to notice that something is missing in the files and make changes if
+If the current user speaks Italian, they string returned may instead be:
-necessary.
+<verb>
+il contatore è 42&lt;br&gt;
+</verb>
+<sect2>The lang function
+<p>
+  <verb>lang($key, $m1="", $m2="", $m3="", $m4="", $m5="", 
+             $m6="", $m7="", $m8="", $m9="", $m10="")</verb>
+  <descrip>
+  <tag/$key/ is the string to translate and may contain replacement directives of the form <tt>%n</tt>.<newline>
+  <tag/$m1/ is the first replacement value or may be an array of replacement values 
+   (in which case $m2 and above are ignored).
+  <tag/$m2 - $m10/ the 2nd through 10th replacement values if $m1 is not an array.
+  </descrip>
+  The database is searched for rows with a <tt>lang.message_id</tt> that matches <tt>$key</tt>.
+If a translation is not found, the original <tt>$key</tt> is used. The translation engine then replaces
+all tokens of the form <tt>%N</tt> with the Nth parameter (either <tt>$m1[N]</tt> or <tt>$mN</tt>).
 </p>
+<sect2>Adding translation data
+<p>
+An application called <bf>Transy</bf> is being developed to make this easier, until then you can create
+the translation data manually.
+
+<sect3>The lang table
+<P>
+The translation class uses the lang table for all translations. 
+We are concerned with 4 of the columns to create a translation:
+<descrip>
+<tag/message_id/The key to identify the message (the <tt>$key</tt> passed
+to the <tt>lang()</tt> function). This is written in English.
+<tag/app_name/The application the translation applies to, or 
+<tt>common</tt> if it is common across multiple applications.
+<tag/lang/The code for the language the translation is in.
+<tag/content/The translated string.
+</descrip>
+<sect3>lang.sql
+<P>
+Currently all applications, and the core phpGroupWare source tree
+have a <tt>lang.sql</tt> file. This is the place to add translation
+data. Just add lines of the form:
+<code>
+REPLACE INTO lang (message_id, app_name, lang, content) 
+VALUES( 'account has been deleted','common','en','Account has been deleted');
+</code>
+translating the <tt>content</tt> to reflect the <tt>message_id</tt> string in the <tt>lang</tt> language.
+If the string is specific to your application, put your application name in for <tt>app_name</tt>
+otherwise use the name <tt>common</tt>. The <tt>message_id</tt> should be in lower case for a small
+increase in speed.
+</p>
+
+<sect1>Common return codes
+<P>
+If you browse through the phpGroupWare sources, you may notice
+a pattern to the return codes used in the higher-level functions.
+The codes used are partially documented in the <tt>doc/developers/CODES</tt> 
+file. 
+
+Codes are used as a simple way to communicate common error and progress
+conditions back to the user. They are mapped to a text string through the
+<tt>check_code()</tt> function, which passes the strings through
+<tt>lang()</tt> before returning.
+
+For example, calling 
+<code>
+echo check_code(13);
+</code>
+Would print
+<verb>
+Your message has been sent
+</verb>
+translated into the current language.
+
 <sect>Using Templates
 <sect1>Overview
 <P>
@@ -478,6 +606,8 @@ necessary.
 <sect1>History 
 <p>
   This document was written by Dan Kuykendall.
+
+  2000-09-25 documentation on lang(), codes, administration and preferences extension added by Steve Brown.
 </p>
 <sect1>Copyrights and Trademarks 
 <p>
@@ -490,7 +620,7 @@ necessary.
   A copy of the license is available at
   <url url="http://www.gnu.org/copyleft/fdl.txt" name="GNU Free Documentation License">.
 </p>
-<sect1>Acknowledgements and Thanks 
+<sect1>Acknowledgments and Thanks 
 <p>
   Thanks to Joesph Engo for starting phpGroupWare (at the time called webdistro). 
   Thanks to all the developers and users who contribute to making phpGroupWare such a success.

doc/developers/phpGW_Developers-HOWTO.txt

@@ -2,7 +2,7 @@
   Dan Kuykendall <dan@kuykendall.org>
   v0.5, 09 September 2000
 
-  This document explains phpGroupWare's infastructure and API, along
+  This document explains phpGroupWare's infrastructure and API, along
   with what is required to integrate applications into it.
   ______________________________________________________________________
 
@@ -81,8 +81,12 @@
      3.2 Automatic features
      3.3 Adding files, directories and icons.
      3.4 Making phpGroupWare aware of your application
+     3.5 Hooking into Administration page
+        3.5.1 section_start
+        3.5.2 section_end
+     3.6 Hooking into Preferences page
 
-  4. Infastructure
+  4. Infrastructure
 
      4.1 Overview
      4.2 Directory tree
@@ -119,9 +123,13 @@
 
      7.1 Overview
      7.2 How to use lang support
+        7.2.1 The lang function
+        7.2.2 Adding translation data
+           7.2.2.1 The lang table
+           7.2.2.2 lang.sql
+     7.3 Common return codes
 
   8. Using Templates
-
      8.1 Overview
      8.2 How to use templates
 
@@ -131,7 +139,7 @@
      9.2 Comments
      9.3 History
      9.4 Copyrights and Trademarks
-     9.5 Acknowledgements and Thanks
+     9.5 Acknowledgments and Thanks
 
 
   ______________________________________________________________________
@@ -156,9 +164,9 @@
   database abstraction method, we support templates using the PHPLIB
   Templates class, a file system interface, and even a network i/o
   interface.
-  On top of these standard functions, phpgroupWare provides several
+  On top of these standard functions, phpGroupWare provides several
   functions to give you the information you need about the users
-  environment, and to properly plug into phpgroupWare.
+  environment, and to properly plug into phpGroupWare.
 
   22..  GGuuiiddeelliinneess
 
@@ -179,23 +187,21 @@
   Where possible it should run on both Unix and NT platforms.
 
   For applications that do not meet these requirements, they can be
-  avalible to users via the phpGroupWare Apps project, or whatever means
+  available to users via the phpGroupWare Apps project, or whatever
-  the developers decide.
+  means the developers decide.
   If you need help converting your application to templates and our lang
   support, we will try to connect you with someone to help.
 
   22..22..  WWrriittiinngg//ppoorrttiinngg yyoouurr aapppplliiccaattiioonn
 
+
+
   22..22..11..  IInncclluuddee ffiilleess
 
   Each PHP page you write will need to include the header.inc.php along
   with a few variables.
   This is done by putting this at the top of each PHP page.
 
-
-
-
-
   ______________________________________________________________________
     <?php
     $phpgw_info["flags"]["currentapp"] = "appname";
@@ -213,7 +219,7 @@
      until a later point.
 
   +o  appname/inc/functions.inc.php - This file is loaded just after the
-     phpgwAPI and before any html code is generated. This file should
+     phpgwAPI and before any HTML code is generated. This file should
      include all your application specific functions.. You are welcome
      to include any additional files you need from within this file.
 
@@ -223,7 +229,7 @@
 
   +o  appname/inc/footer.inc.php - This file is loaded just before the
      system footer, allowing developers to close connections and
-     whetever else they need.
+     whatever else they need.
 
   +o  The phpGW footer will be loaded, which closes several connections.
 
@@ -249,26 +255,22 @@
 
   +o  appname/inc/footer.inc.php - This file is loaded just before the
      system footer, allowing developers to close connections and
-     whetever else they need.
+     whatever else they need.
 
   33..33..  AAddddiinngg ffiilleess,, ddiirreeccttoorriieess aanndd iiccoonnss..
 
   You will need to create the following directories for your code
   (replace 'appname' with your application name)
 
-
-
-
-
-
-
     `-- appname
         `-- images
         |   `-- navbar.gif
         `-- inc
         |   |-- functions.inc.php
         |   |-- header.inc.php
-        |   `-- footer.inc.php
+        |   |-- footer.inc.php
+        |   |-- preferences.inc.php
+        |   `-- admin.inc.php
         `-- templates
             `-- default
 
@@ -279,20 +281,81 @@
 
   To make the application aware of your application, add your
   application details to the applications table. This can be done via
-  the GUI administration screen, or via a sql script.
+  the GUI administration screen, or via a SQL script.
 
     insert into applications (app_name, app_title, app_enabled) values ('appname', 'The App name', 1);
 
 
 
-  44..  IInnffaassttrruuccttuurree
+  33..55..  HHooookkiinngg iinnttoo AAddmmiinniissttrraattiioonn ppaaggee
+
+  When a user goes to the Administration page, it stats
+  appname/inc/admin.inc.php for each application that is enabled, in
+  alphabetical order of application title.  If the file exists, it is
+  include()d in the hopes it will display a selection of links to
+  configure that application.
+
+  Simple Example:
+
+  ______________________________________________________________________
+  <?php
+    $img = "/" . $appname . "/images/navbar.gif";
+    section_start("My Application",$img);
+    echo "<a HREF=\"" . $phpgw->link("myAdminPage.php") . "\">";
+    echo lang("Change myApp settings") . "</a>";
+    section_end();
+  ?>
+  ______________________________________________________________________
+
+
+  Look at headlines/inc/admin.inc.php and admin/inc/admin.inc.php for
+  more examples.
+
+  Things to note:
+
+  +o  Links are relative to the admin/index.php file, not your
+     application's base directory. (so use $appname in your link()
+     calls)
+
+  +o  The file is brought in with include() so be careful to not pollute
+     the name-space too much
+
+     The standard $phpgw and $phpgw_info variables are in-scope, as is
+     $appname which corresponds to the application name in the path.
+
+  There are 2 functions to coordinate the display of each application's
+  links, section_start() and section_end()
+
+
+
+  33..55..11..  sseeccttiioonn__ssttaarrtt
+
+  section_start($title,$icon_url) starts the section for your
+  application. $title is passed through lang() for you. $icon_url should
+  be page-relative to admin/index.php or an absolute URL.
+
+
+  33..55..22..  sseeccttiioonn__eenndd
+
+  section_end() closes the section that was started with
+  section_start().
+
+
+  33..66..  HHooookkiinngg iinnttoo PPrreeffeerreenncceess ppaaggee
+
+  The mechanism to hook into the preferences page is identical to the
+  one used to hook into the administration page, however it looks for
+  appname/inc/preferences.inc.php instead of appname/inc/admin.inc.php.
+  The same functions and variables are defined.
+
+  44..  IInnffrraassttrruuccttuurree
 
   44..11..  OOvveerrvviieeww
 
   phpGroupWare attempts to provide developers with a sound directory
   structure to work from.
   The directory layout may seem complex at first, but after some use,
-  you will see that it is designed to accommidate a large number of
+  you will see that it is designed to accommodate a large number of
   applications and functions.
 
   44..22..  DDiirreeccttoorryy ttrreeee
@@ -324,6 +387,9 @@
 
 
 
+
+
+
 
 
 
@@ -343,7 +409,8 @@
   |   `-- inc
   |   |   |-- functions.inc.php
   |   |   |-- header.inc.php
-  |   |   `-- footer.inc.php
+  |   |   |-- footer.inc.php
+  |   |   `-- admin.inc.php
   |   `-- templates
   |       `-- default
   |-- calendar
@@ -363,7 +430,9 @@
   |   `-- inc
   |   |   |-- functions.inc.php
   |   |   |-- header.inc.php
-  |   |   `-- footer.inc.php
+  |   |   |-- footer.inc.php
+  |   |   |-- preferences.inc.php
+  |   |   `-- admin.inc.php
   |   `-- templates
   |       `-- default
   |-- filemanager
@@ -372,9 +441,9 @@
   |   `-- users
   |-- inc
   |   |-- phpgwapi
-      |   |-- phpgw.inc.php
+  |   |   |-- phpgw.inc.php
-      |   |-- phpgw_info.inc.php
+  |   |   |-- phpgw_info.inc.php
-      |   |-- phpgw_common.inc.php
+  |   |   |-- phpgw_common.inc.php
   |   |   `-- etc...
   |   `-- templates
   |       |-- default
@@ -398,7 +467,8 @@
   |   `-- inc
   |   |   |-- functions.inc.php
   |   |   |-- header.inc.php
-  |   |   `-- footer.inc.php
+  |   |   |-- footer.inc.php
+  |   |   `-- preferences.inc.php
   |   `-- templates
   |       `-- default
   |-- themes
@@ -422,7 +492,7 @@
   We are completing a program called Transy, which will provide
   developers/translators a nice GUI for building and updating
   translations.
-  In the mean time you will need to create a sql script yourself and
+  In the mean time you will need to create a SQL script yourself and
   name it lang.sql. You can copy the one in doc/lang.sql and use it as a
   template.
 
@@ -435,7 +505,7 @@
   To do this we have created a multi-dimensional class $phpgw->.
   This allows for terrific code organization, and help developers easily
   identify the file that the function is in.  All the files that are
-  patr of this class are in the inc/core directory and are named to
+  part of this class are in the inc/core directory and are named to
   match the sub-class.
   Example: $phpgw->send->msg() is in the inc/phpgwapi/phpgw_send.inc.php
   file.
@@ -448,18 +518,23 @@
   Add support for session management. ALL links must use this, that
   includes href's form actions and header location's.
   If you are just doing a form action back to the same page, you can use
-  it without any paramaters.
+  it without any parameters.
   This function is right at the core of the class because it is used so
   often, we wanted to save developers a few keystrokes.  Example:
 
+
+
+
+
   ______________________________________________________________________
   <form name=copy method=post action="<?php echo $phpgw->link();?>">
-  /* If session management is done via passing url paramaters */
+  /* If session management is done via passing url parameters */
   /* The the result would be */
   /* <form name=copy method=post action="somepage.php?sessionid=87687693276?kp3=kjh98u80"> */
   ______________________________________________________________________
 
 
+
   55..33..  AApppplliiccaattiioonn FFuunnccttiioonnss
 
 
@@ -469,10 +544,10 @@
   Store important information session information that your application
   needs.
   $phpgw->appsession will return the value of your session data is you
-  leave the paramater enmpty [i.e. $phpgw->appsession("")], otherwise it
+  leave the parameter empty [i.e. $phpgw->appsession("")], otherwise it
   will store whatever data you send to it.
   You can also store a comma delimited string and use explode() to turn
-  it back into an array when you recieve the value back.
+  it back into an array when you receive the value back.
   Example:
 
   ______________________________________________________________________
@@ -517,7 +592,6 @@
   $phpgw->vfs->read_userfile($file)
   Returns the data from $file, which resides in the users private dir.
   Example:
-
   ______________________________________________________________________
   $data = $phpgw->vfs->read_userfile("file.txt");
   ______________________________________________________________________
@@ -525,7 +599,6 @@
 
 
 
-
   55..44..44..  $$pphhppggww-->>vvffss-->>wwrriittee__uusseerrffiillee
 
   $phpgw->write_userfile($file, $contents)
@@ -585,13 +658,6 @@
   easy.
   Here are some examples:
 
-
-
-
-
-
-
-
   ______________________________________________________________________
     <?php
     // To do a hello username
@@ -614,7 +680,7 @@
   $phpgw_info["user"]["sessionid"] = The session ID
   $phpgw_info["user"]["theme"] = Selected theme
   $phpgw_info["user"]["private_dir"] = Users private dir. Use
-  phpgroupware core functions for access to the files.
+  phpGroupWare core functions for access to the files.
   $phpgw_info["user"]["firstname"] = Users first name
   $phpgw_info["user"]["lastname"] = Users last name
   $phpgw_info["user"]["fullname"] = Users Full Name
@@ -685,7 +751,7 @@
   $phpgw_info["server"]["mail_suffix] = This is the domain name, used to
   add to email address
   $phpgw_info["server"]["mail_login_type"] = This adds support for
-  VMailMgr. Generally this hsould be set to 'standard'.
+  VMailMgr. Generally this should be set to 'standard'.
   $phpgw_info["server"]["smtp_server"] = Address of the SMTP server.
   Usually this is set to localhost.
   $phpgw_info["server"]["smtp_port"] = This is usually 25, and should
@@ -698,11 +764,11 @@
   only be changed if there is a good reason.
   $phpgw_info["server"]["nntp_sender"] = Unknown
   $phpgw_info["server"]["nntp_organization"] = Unknown
-  $phpgw_info["server"]["nntp_admin"] = Uknown
+  $phpgw_info["server"]["nntp_admin"] = Unknown
 
   66..88..  AApppplliiccaattiioonn iinnffoorrmmaattiioonn
 
-  Each application has the following information avalible.
+  Each application has the following information available.
   $phpgw_info["apps"]["appname"]["title"] = The title of the
   application.
   $phpgw_info["apps"]["appname"]["enabled"] = If the application is
@@ -723,49 +789,141 @@
   77..11..  OOvveerrvviieeww
 
   phpGroupWare is built using a multi-language support scheme. This
-  means the pages can be translated to other languages very easily. It
+  means the pages can be translated to other languages very easily.
-  is done thru a series of lang files, which can be translated and
+  Translations of text strings are stored in the phpGroupWare database,
-  selected by the user.
+  and can be modified by the phpGroupWare administrator.
 
   77..22..  HHooww ttoo uussee llaanngg ssuuppppoorrtt
 
-  Some instructions on using the lang files.
+  The lang() function is your application's interface to phpGroupWare's
-  Under inc/lang there needs to be a sub-directory for each langague.
+  internationalization support.
-  Inside the directory there are a number of files for each application.
+
-  There is one common file which contains a list of words that all
+  While developing your application, just wrap all your text output with
-  applications use.  ie, add, delete, edit, etc...
+  calls to lang(), as in the following code:
-  Words that are specific to a application should be stored with that
-  applications include file.
 
   ______________________________________________________________________
-    function lang_todo($message, $m1 = "", $m2 = "", $m3 = "", $m4 = "")
+    $x = 42;
-    {
+    echo lang("The counter is %1",$x)."<br>";
-      $message = strtolower($message);
-      switch($message)
-      {
-         case "urgency": $s = "Urgency"; break;
-         case "completed": $s = "completed"; break;
-         [ snip ]
-         default: $s = "<b>*</b> " . $message;
-      }
-      return $s;
-    }
-
   ______________________________________________________________________
 
 
-  The list of words in the left column should always be written in
+  This will attempt to translate "The counter is %1", and return a
-  english.  The second column is used to return those words in that
+  translated version based on the current application and language in
-  includes language.  $m1, $m2, $m3, and $m4 are used to pass extra data
+  use. Note how the position that $x will end up is controlled by the
-  to be place in the middle of a sentence.
+  format string, nnoott by building up the string in your code. This allows
-  For example:
+  your application to be translated to languages where the actual number
+  is not placed at the end of the string.
 
-  You have 29 new messages!
+  When a translation is not found, the original text will be returned
+  with a * after the string.  This makes it easy to develop your
+  application, then go back and add missing translations (identified by
+  the *) later.
+
+  Without a specific translation in the lang table, the above code will
+  print:
+
+  The counter is 42*<br>
 
 
-  The default should return a bold faced * and the word that wasn't
+  If the current user speaks Italian, they string returned may instead
-  found. This allows users to notice that something is missing in the
+  be:
-  files and make changes if necessary.
+
+  il contatore  42<br>
+
+
+
+  77..22..11..  TThhee llaanngg ffuunnccttiioonn
+
+
+  lang($key, $m1="", $m2="", $m3="", $m4="", $m5="",
+               $m6="", $m7="", $m8="", $m9="", $m10="")
+
+
+
+     $$kkeeyy
+        is the string to translate and may contain replacement
+        directives of the form %n.
+
+     $$mm11
+        is the first replacement value or may be an array of replacement
+        values (in which case $m2 and above are ignored).
+
+     $$mm22 -- $$mm1100
+        the 2nd through 10th replacement values if $m1 is not an array.
+
+  The database is searched for rows with a lang.message_id that matches
+  $key.  If a translation is not found, the original $key is used. The
+  translation engine then replaces all tokens of the form %N with the
+  Nth parameter (either $m1[N] or $mN).
+
+  77..22..22..  AAddddiinngg ttrraannssllaattiioonn ddaattaa
+
+  An application called TTrraannssyy is being developed to make this easier,
+  until then you can create the translation data manually.
+
+
+  77..22..22..11..  TThhee llaanngg ttaabbllee
+
+  The translation class uses the lang table for all translations.  We
+  are concerned with 4 of the columns to create a translation:
+
+     mmeessssaaggee__iidd
+        The key to identify the message (the $key passed to the lang()
+        function). This is written in English.
+
+     aapppp__nnaammee
+        The application the translation applies to, or common if it is
+        common across multiple applications.
+
+     llaanngg
+        The code for the language the translation is in.
+
+     ccoonntteenntt
+        The translated string.
+
+  77..22..22..22..  llaanngg..ssqqll
+
+  Currently all applications, and the core phpGroupWare source tree have
+  a lang.sql file. This is the place to add translation data. Just add
+  lines of the form:
+
+  ______________________________________________________________________
+  REPLACE INTO lang (message_id, app_name, lang, content)
+  VALUES( 'account has been deleted','common','en','Account has been deleted');
+  ______________________________________________________________________
+
+
+  translating the content to reflect the message_id string in the lang
+  language.  If the string is specific to your application, put your
+  application name in for app_name otherwise use the name common. The
+  message_id should be in lower case for a small increase in speed.
+
+  77..33..  CCoommmmoonn rreettuurrnn ccooddeess
+
+  If you browse through the phpGroupWare sources, you may notice a
+  pattern to the return codes used in the higher-level functions.  The
+  codes used are partially documented in the doc/developers/CODES file.
+
+  Codes are used as a simple way to communicate common error and
+  progress conditions back to the user. They are mapped to a text string
+  through the check_code() function, which passes the strings through
+  lang() before returning.
+
+  For example, calling
+
+  ______________________________________________________________________
+  echo check_code(13);
+  ______________________________________________________________________
+
+
+  Would print
+
+  Your message has been sent
+
+
+
+  translated into the current language.
+
 
   88..  UUssiinngg TTeemmppllaatteess
 
@@ -788,8 +946,6 @@
   The newest version of this document can be found on our website
   <http://www.phpgroupware.org> as SGML source, as HTML and as TEXT.
 
-
-
   99..22..  CCoommmmeennttss
 
   Comments on this HOWTO should be directed to the phpGroupWare
@@ -812,7 +968,7 @@
   A copy of the license is available at GNU Free Documentation License
   <http://www.gnu.org/copyleft/fdl.txt>.
 
-  99..55..  AAcckknnoowwlleeddggeemmeennttss aanndd TThhaannkkss
+  99..55..  AAcckknnoowwlleeddggmmeennttss aanndd TThhaannkkss
 
   Thanks to Joesph Engo for starting phpGroupWare (at the time called
   webdistro).  Thanks to all the developers and users who contribute to
@@ -832,27 +988,3 @@
 
 
 
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-