egroupware/doc/developers/phpGW_Developers-HOWTO.txt

  phpGroupWare Application Development
  Dan Kuykendall <dan@kuykendall.org>
  v0.5, 09 September 2000

  This document explains phpGroupWare's infastructure and API, along
  with what is required to integrate applications into it.
  ______________________________________________________________________

  Table of Contents

























































  1. Introduction

     1.1 Overview of application writing
     1.2 What does the phpGroupWare API provide?

  2. Guidelines

     2.1 Requirements
     2.2 Writing/porting your application
        2.2.1 Include files

  3. Installing your application

     3.1 Overview
     3.2 Automatic features
     3.3 Adding files, directories and icons.
     3.4 Making phpGroupWare aware of your application

  4. Infastructure

     4.1 Overview
     4.2 Directory tree
     4.3 Translations

  5. The API

     5.1 Introduction
     5.2 Basic functions
        5.2.1 $phpgw->link
     5.3 Application Functions
        5.3.1 $phpgw->common->appsession
     5.4 File functions
        5.4.1 $phpgw->vfs->read_file
        5.4.2 $phpgw->vfs->write_file
        5.4.3 $phpgw->vfs->read_userfile
        5.4.4 $phpgw->vfs->write_userfile
        5.4.5 $phpgw->vfs->list_userfiles
     5.5 Email/NNTP Functions
        5.5.1 $phpgw->send->msg

  6. Configuration Variables

     6.1 Introduction
     6.2 User information
     6.3 Group information
     6.4 Server information
     6.5 Database information
     6.6 Mail information
     6.7 NNTP information
     6.8 Application information

  7. Using Language Support

     7.1 Overview
     7.2 How to use lang support

  8. Using Templates

     8.1 Overview
     8.2 How to use templates

  9. About this document

     9.1 New versions
     9.2 Comments
     9.3 History
     9.4 Copyrights and Trademarks
     9.5 Acknowledgements and Thanks


  ______________________________________________________________________

  11..  IInnttrroodduuccttiioonn

  phpGroupWare is a web based groupware application framework (API), for
  writing applications. Integrated applications such as email, calendar,
  todo list, address book, and file manager are included.

  11..11..  OOvveerrvviieeww ooff aapppplliiccaattiioonn wwrriittiinngg

  We have attempted to make writing application for phpGroupWare as
  painless as possible.  We hope any pain and suffering is cause by
  making your application work, but not dealing with phpGroupWare
  itself.

  11..22..  WWhhaatt ddooeess tthhee pphhppGGrroouuppWWaarree AAPPII pprroovviiddee??

  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.
  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.

  22..  GGuuiiddeelliinneess

  22..11..  RReeqquuiirreemmeennttss

  These guidelines must be followed for any application that wants
  considered for inclusion into phpGroupWare deluxe.

  It must run on PHP3 and PHP4.
  SQL statements must be compatible with both MySQL and PostgreSQL.
  It must use our default header.inc.php include.
  It must use our $phpgw_link($url) for all links (this is for session
  support).
  It must use "post" for forms.
  It must respect phpGW group rights and phpGW user permissions.
  It must use our directory structure, template support and lang (multi-
  language) support.
  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
  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";
    include("../header.inc.php");
    ?>
  ______________________________________________________________________


  Of course change application name to fit.
  This include will provide the following things:

  +o  The phpgwAPI - The phpGroupWare API will be loaded.

  +o  The phpGW navbar will be loaded (by default, but can be disabled
     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
     include all your application specific functions.. You are welcome
     to include any additional files you need from within this file.

  +o  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.

  +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.

  +o  The phpGW footer will be loaded, which closes several connections.


  33..  IInnssttaalllliinngg yyoouurr aapppplliiccaattiioonn

  33..11..  OOvveerrvviieeww

  It is fairly simple to add and delete applications to/from
  phpGroupWare.

  33..22..  AAuuttoommaattiicc ffeeaattuurreess

  To make things easy for developers we go ahead and load the following
  files.

  +o  appname/inc/functions.inc.php - This file should include all your
     application specific functions.

  +o  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.

  +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.

  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
        `-- templates
            `-- default




  33..44..  MMaakkiinngg pphhppGGrroouuppWWaarree aawwaarree ooff yyoouurr aapppplliiccaattiioonn

  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.

    insert into applications (app_name, app_title, app_enabled) values ('appname', 'The App name', 1);



  44..  IInnffaassttrruuccttuurree

  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
  applications and functions.

  44..22..  DDiirreeccttoorryy ttrreeee
































  .-- addressbook
  |   `-- images
  |   |   `-- navbar.gif
  |   `-- inc
  |   |   |-- functions.inc.php
  |   |   |-- header.inc.php
  |   |   `-- footer.inc.php
  |   `-- templates
  |       `-- default
  |-- admin
  |   `-- images
  |   |   `-- navbar.gif
  |   `-- inc
  |   |   |-- functions.inc.php
  |   |   |-- header.inc.php
  |   |   `-- footer.inc.php
  |   `-- templates
  |       `-- default
  |-- calendar
  |   `-- images
  |   |   `-- navbar.gif
  |   `-- inc
  |   |   |-- functions.inc.php
  |   |   |-- header.inc.php
  |   |   `-- footer.inc.php
  |   `-- templates
  |       `-- default
  |-- cron
  |-- doc
  |-- email
  |   `-- images
  |   |   `-- navbar.gif
  |   `-- inc
  |   |   |-- functions.inc.php
  |   |   |-- header.inc.php
  |   |   `-- footer.inc.php
  |   `-- templates
  |       `-- default
  |-- filemanager
  |-- files
  |   |-- groups
  |   `-- users
  |-- inc
  |   |-- phpgwapi
      |   |-- phpgw.inc.php
      |   |-- phpgw_info.inc.php
      |   |-- phpgw_common.inc.php
  |   |   `-- etc...
  |   `-- templates
  |       |-- default
  |       |   |-- addressbook
  |       |   |-- admin
  |       |   |-- calendar
  |       |   |-- common
  |       |   |-- email
  |       |   |-- filemanager
  |       |   |-- headlines
  |       |   |-- preferences
  |       |   |-- todo
  |       |   `-- tts
  |       `-- icons
  |           |-- email
  |           |-- calendar
  |           `-- tts
  |-- preferences
  |   `-- images
  |   |   `-- navbar.gif
  |   `-- inc
  |   |   |-- functions.inc.php
  |   |   |-- header.inc.php
  |   |   `-- footer.inc.php
  |   `-- templates
  |       `-- default
  |-- themes
  `-- todo
      `-- images
      |   `-- navbar.gif
      `-- inc
      |   |-- functions.inc.php
      |   |-- header.inc.php
      |   `-- footer.inc.php
      `-- templates
          `-- default




  44..33..  TTrraannssllaattiioonnss

  The translations are now being done thru the database, and will be
  configurable to use other mechanisms.
  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
  name it lang.sql. You can copy the one in doc/lang.sql and use it as a
  template.

  55..  TThhee AAPPII

  55..11..  IInnttrroodduuccttiioonn

  phpGroupWare attempts to provide developers with a useful API to
  handle common tasks.
  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
  match the sub-class.
  Example: $phpgw->send->msg() is in the inc/phpgwapi/phpgw_send.inc.php
  file.

  55..22..  BBaassiicc ffuunnccttiioonnss

  55..22..11..  $$pphhppggww-->>lliinnkk

  $phpgw->link($url)
  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.
  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 */
  /* The the result would be */
  /* <form name=copy method=post action="somepage.php?sessionid=87687693276?kp3=kjh98u80"> */
  ______________________________________________________________________


  55..33..  AApppplliiccaattiioonn FFuunnccttiioonnss


  55..33..11..  $$pphhppggww-->>ccoommmmoonn-->>aappppsseessssiioonn

  $phpgw->common->appsession($data)
  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
  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.
  Example:

  ______________________________________________________________________
    $phpgw->common->appsession("/path/to/something");
    echo "Dir: " . $phpgw->common->appsession();
  ______________________________________________________________________



  55..44..  FFiillee ffuunnccttiioonnss

  55..44..11..  $$pphhppggww-->>vvffss-->>rreeaadd__ffiillee

  $phpgw->vfs->read_file($file)
  Returns the data from $file.
  You must send the complete path to the file.
  Example:

  ______________________________________________________________________
  $data = $phpgw->vfs->read_file("/some/dir/to/file.txt");
  ______________________________________________________________________




  55..44..22..  $$pphhppggww-->>vvffss-->>wwrriittee__ffiillee

  $phpgw->vfs->write_file($file, $contents)
  Write data to $file.
  You must send the complete path to the file.
  Example:

  ______________________________________________________________________
  $data = $phpgw->vfs->write_file("/some/dir/to/file.txt");
  ______________________________________________________________________




  55..44..33..  $$pphhppggww-->>vvffss-->>rreeaadd__uusseerrffiillee

  $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");
  ______________________________________________________________________





  55..44..44..  $$pphhppggww-->>vvffss-->>wwrriittee__uusseerrffiillee

  $phpgw->write_userfile($file, $contents)
  Writes data to $file, which resides in the users private dir.
  Example:

  ______________________________________________________________________
  $data = $phpgw->vfs->write_userfile("file.txt");
  ______________________________________________________________________




  55..44..55..  $$pphhppggww-->>vvffss-->>lliisstt__uusseerrffiilleess

  $phpgw->vfs->list_userfiles()
  Returns an array which has the list of files in the users private dir.
  Example:

  ______________________________________________________________________
  $filelist = array();
  $filelist = $phpgw->vfs->list_userfiles();
  ______________________________________________________________________



  55..55..  EEmmaaiill//NNNNTTPP FFuunnccttiioonnss



  55..55..11..  $$pphhppggww-->>sseenndd-->>mmssgg

  $phpgw->msg->send($service, $to, $subject, $body, $msgtype, $cc, $bcc)
  Send a message via email or NNTP and returns any error codes.
  Example:

  ______________________________________________________________________
  $to = "someuser@domain.com";
  $subject = "Hello buddy";
  $body = "Give me a call\n Been wondering what your up to.";
  $errors = $phpgw->msg->send("email", $to, $subject, $body);
  ______________________________________________________________________



  66..  CCoonnffiigguurraattiioonn VVaarriiaabblleess

  66..11..  IInnttrroodduuccttiioonn

  phpGroupWare attempt to provide developers with as much information
  about the user, group, server, and application configuration as
  possible.
  To do this we provide a multi-dimensional array called
  '$phpgw_info[]', which includes all the information about your
  environment.
  Due to the multi-dimensional array approach. getting these values is
  easy.
  Here are some examples:








  ______________________________________________________________________
    <?php
    // To do a hello username
    echo "Hello " . $phpgw_info["user"]["fullname"];
    //If username first name is John and last name is Doe, prints: 'Hello John Doe'
    ?>
    <?php
    // To find out the location of the imap server
    echo "IMAP Server is named: " . $phpgw_info["server"]["imap_server"];
    //If imap is running on localhost, prints: 'IMAP Server is named: localhost'
    ?>

  ______________________________________________________________________



  66..22..  UUsseerr iinnffoorrmmaattiioonn

  $phpgw_info["user"]["userid"] = The user ID.
  $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.
  $phpgw_info["user"]["firstname"] = Users first name
  $phpgw_info["user"]["lastname"] = Users last name
  $phpgw_info["user"]["fullname"] = Users Full Name
  $phpgw_info["user"]["groups"] = Groups the user is a member of
  $phpgw_info["user"]["app_perms"] = If the user has access to the
  current application
  $phpgw_info["user"]["lastlogin"] = Last time the user logged in.
  $phpgw_info["user"]["lastloginfrom"] = Where they logged in from the
  last time.
  $phpgw_info["user"]["lastpasswd_change"] = Last time they changed
  their password.
  $phpgw_info["user"]["passwd"] = Hashed password.
  $phpgw_info["user"]["status"] = If the user is enabled.
  $phpgw_info["user"]["logintime"] = Time they logged into their current
  session.
  $phpgw_info["user"]["session_dla"] = Last time they did anything in
  their current session
  $phpgw_info["user"]["session_ip"] = Current IP address

  66..33..  GGrroouupp iinnffoorrmmaattiioonn

  $phpgw_info["group"]["group_names"] = List of groups.

  66..44..  SSeerrvveerr iinnffoorrmmaattiioonn

  $phpgw_info["server"]["server_root"] = Main installation directory
  $phpgw_info["server"]["include_root"] = Location of the 'inc'
  directory.
  $phpgw_info["server"]["temp_dir"] = Directory that can be used for
  temporarily storing files
  $phpgw_info["server"]["common_include_dir"] = Location of the
  core/shared include files.
  $phpgw_info["server"]["template_dir"] = Active template files
  directory. This is defaulted by the server, and changeable by the
  user.
  $phpgw_info["server"]["dir_separator"] = Allows compatibility with
  WindowsNT directory format,
  $phpgw_info["server"]["encrpytkey"] =
  $phpgw_info["server"]["site_title"] = Site Title will show in the
  title bar of each webpage.
  $phpgw_info["server"]["webserver_url"] = URL to phpGroupWare
  installation.
  $phpgw_info["server"]["charset"]      = Unknown
  $phpgw_info["server"]["version"] = phpGroupWare version.

  66..55..  DDaattaabbaassee iinnffoorrmmaattiioonn

  It is unlikely you will need these, because $phpgw_info_db will
  already be loaded as a database for you to use.
  $phpgw_info["server"]["db_host"] = Address of the database server.
  Usually this is set to localhost.
  $phpgw_info["server"]["db_name"] = Database name.
  $phpgw_info["server"]["db_user"] = User name.
  $phpgw_info["server"]["db_pass"] = Password
  $phpgw_info["server"]["db_type"] = Type of database. Currently MySQL
  and PostgreSQL are supported.

  66..66..  MMaaiill iinnffoorrmmaattiioonn

  It is unlikely you will need these, because most email needs are
  services thru core phpGroupWare functions.
  $phpgw_info["server"]["mail_server"] = Address of the IMAP server.
  Usually this is set to localhost.
  $phpgw_info["server"]["mail_server_type"] = IMAP or POP3
  $phpgw_info["server"]["imap_server_type"] = Cyrus or Uwash
  $phpgw_info["server"]["imap_port"] = This is usually 143, and should
  only be changed if there is a good reason.
  $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'.
  $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
  only be changed if there is a good reason.

  66..77..  NNNNTTPP iinnffoorrmmaattiioonn

  $phpgw_info["server"]["nntp_server"] = Address of the NNTP server.
  $phpgw_info["server"]["nntp_port"] = This is usually XX, and should
  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

  66..88..  AApppplliiccaattiioonn iinnffoorrmmaattiioonn

  Each application has the following information avalible.
  $phpgw_info["apps"]["appname"]["title"] = The title of the
  application.
  $phpgw_info["apps"]["appname"]["enabled"] = If the application is
  enabled. True or False.
  $phpgw_info["server"]["app_include_dir"] = Location of the current
  application include files.
  $phpgw_info["server"]["app_template_dir"] = Location of the current
  application tpl files.
  $phpgw_info["server"]["app_lang_dir"] = Location of the current lang
  directory.
  $phpgw_info["server"]["app_auth"] = If the server and current user
  have access to current application
  $phpgw_info["server"]["app_current"] = name of the current
  application.

  77..  UUssiinngg LLaanngguuaaggee SSuuppppoorrtt

  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
  is done thru a series of lang files, which can be translated and
  selected by the user.

  77..22..  HHooww ttoo uussee llaanngg ssuuppppoorrtt

  Some instructions on using the lang files.
  Under inc/lang there needs to be a sub-directory for each langague.
  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
  applications use.  ie, add, delete, edit, etc...
  Words that are specific to a application should be stored with that
  applications include file.

  ______________________________________________________________________
    function lang_todo($message, $m1 = "", $m2 = "", $m3 = "", $m4 = "")
    {
      $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
  english.  The second column is used to return those words in that
  includes language.  $m1, $m2, $m3, and $m4 are used to pass extra data
  to be place in the middle of a sentence.
  For example:

  You have 29 new messages!


  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 necessary.

  88..  UUssiinngg TTeemmppllaatteess

  88..11..  OOvveerrvviieeww

  phpGroupWare is built using a templates based design. This means the
  display pages, stored in tpl files, can be translated to other
  languages, made to look completely different.

  88..22..  HHooww ttoo uussee tteemmppllaatteess

  Some instructions on using templates
  For Further info read the PHPLIBs documentation for their template
  class.

  99..  AAbboouutt tthhiiss ddooccuummeenntt

  99..11..  NNeeww vveerrssiioonnss

  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
  developers mailing list phpgroupware-developers@lists.sourceforge.net
  <mailto:phpgroupware-developers@lists.sourceforge.net>.

  To subscribe, go to  <http://sourceforge.net/mail/?group_id=7305>

  99..33..  HHiissttoorryy

  This document was written by Dan Kuykendall.

  99..44..  CCooppyyrriigghhttss aanndd TTrraaddeemmaarrkkss

  Copyright (c)  Dan Kuykendall.  Permission is granted to copy,
  distribute and/or modify this document under the terms of the GNU Free
  Documentation License, Version 1.1 or any later version published by
  the Free Software Foundation

  A copy of the license is available at GNU Free Documentation License
  <http://www.gnu.org/copyleft/fdl.txt>.

  99..55..  AAcckknnoowwlleeddggeemmeennttss aanndd TThhaannkkss

  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.