[phpGroupWare-developers] answers to some questions

[Dave Hall]

Hi,

This list of questions from a new user was forwarded to me by another
developer.  I hope someone finds the information useful.

Cheers

Dave

> All of my comments are based on the Developers Guide at
> http://docs.phpgroupware.org/contrib/
> 
> 1.) Section "3.4 Making phpGroupWare aware of your application" is not
> valid app_title is no longer a column,
> also app_order, app_version, and app_tables columns need to be filled.
> It should probably be something 
> closer to this:
> 
>                 INSERT INTO phpgw_applications (app_name, app_order,
> app_version, app_tables, app_enabled)
>         VALUES('appname', 8, '0.0.1', '<Tables associated with your
> app seperated by commas>', 1);

This example code seems to be a hang over from 0.9.14.

I have updated the code in the document.  It should show up on
phpgrouwpare.org shortly.

app_tables is only used if setup/setup.inc.php is being used, so I
didn't leave that in the example.

> 
> 
> 2.) After your application is recognized by phpgw you must give
> permission to users or groups to access the application. This is not
> stated
> in the docs at all. (graphics accompanying this part may be a good
> aid):
> 
>                 *       Go to the Admin module
>                 *       Click "User Groups"
>                 *       Click "Edit" next to the group you wish to
> change application permissions for
>                 *       Check off your application in order to give
> the group permission to use your application
>                 *       Click "Submit Changes" 
>                 *       Your application should now appear in the
> navbar

This is covered in the admin guide.  We expect that our developers have
at least a basic understanding of how phpgw works :)

http://docs.phpgroupware.org/html/install/admin.html

>                 
>                 
> 3.) A description of setup.inc.php would be helpful as well as the
> $setup_info[<AppName>] array with definitions of its available
> elements.


$setup_info['appname']['name']    = 'appname';  // appname - should probably be 
dropped and use the key instead
$setup_info['appname']['version'] = '0.9.17.501'; // the current version of the 
app
$setup_info['appname']['app_order'] = 99; // the order the item shows up in the 
menu
$setup_info['appname']['enable']  = 1; // the app is available, 2 means active 
but not shown in menu

$setup_info['appname']['author'] = 'Your Name'; // name of the person who wrote 
the app
$setup_info['appname']['license']  = 'GPL'; // the license of the app, must be 
GPL to be an official phpgw app
$setup_info['appname']['description'] = 'what does the app do ? Just a short 
one line description;
$setup_info['appname']['note'] = 'This is contains more information about what 
the app does and where to get more information about it';
$setup_info['appname']['maintainer'] = array(
        'name'  => 'Your Name',
        'email' => 'address@hidden' // once you are granted cvs access we will 
give you an alias, just email me if I forget to do it
);

/* the tables created by the app */
$setup_info['appname']['tables'] = array
(
        'appname_data',
        'appname_lookup'
)


/* The hooks implemented by this app */
$setup_info['appname']['hooks'] = array
(
        'home',
        'preferences',
        'sidebox_menu',
);

/* Dependencies for this app to work */
$setup_info['appname']['depends'][] = array(
         'appname' => 'phpgwapi',
         'versions' => Array('0.9.14','0.9.15','0.9.16')
);

> 
> There is no documentation on how to hook into sidebox menu so that a
> developer can create their own sidebox menu  I had to go
> look at code from the addressbook apps' "hook_sidebox_menu.inc.php"
> code.  A description of all hooks that are available to a developer 
> and sample code showing how to use them could be helpful.

Good idea, unfortunately I don't have half a day to spend documenting
the ones I sort of know, let alone the ones I don't.


> 
> 
> 4.) A description of the way menuaction works, even though it is
> relatively apparent that <appname>.<class>.<method> will execute the
> function 
> designated there are a few caveats that have no documentation:
> 
> 
>                 A.)     The $public_functions Array is needed as a
> variable within all classes in in order to call via menuaction.  
>                 The name of any method within a class that needs to be
> called via menuaction should be declared as key in $public_functions
> and its associated
>                 Boolean value should be declared as well. 
> 
>                         var $public_functions = array(
>                                 'index' => True,
>                                 'view' => True,
>                                 'add'  => True,
>                                 'add_email' => True,
>                                 'copy' => True,
>                         )
>                 
>                 This achieves some sort of security through a
> visibility modifier of sorts but with php5 having true visibility
> modifiers
>                 this should become unecessary at some point either way
> it wouldn't be immediately apparent to a developer.
> 

This was first implemented in php3 :)  It should probably be changed,
but 0.9.18 is still likely to support php 4, so this won't be an option.
It is documented in many classes, but a note on it in the dev guide
would be a good idea.

> 
>                 B.)     When you call a function that outputs a UI via
> a template and the function is called via a menuaction you have to
> call 
>                 two functions BEFORE your template:             
>         
>                         $GLOBALS['phpgw']->common->phpgw_header();
>                         echo parse_navbar();
>                         
>                 If these calls are not made then the navbar and header
> will not be output even if you have them declared in in your apps.
>                 
>                 C.) 'B' is really part of a bigger problem. The whole
> "menuaction" methodology has no explanation at all other than looking
> at the code its pretty straightforward once you know it but an
> explanation would save developers a whole lot of time. 
> 

Which part of it?  The who n-tier design or just the menuaction
dispatcher?

> 
> 5.) Including javascript and css resources in <head> that are local to
> a developers application is not explained at all.
> 

phpgwapi/inc/class.javascript.inc.php does the JS for you :)  I HEAD i
am still working on a nicer way of handling CSS.

> 
> 6.) A description of what resources are available in $GLOBALS['phpgw']
> would also be helpful.  This is something can easily be determined by
> taking
> a look at the code but it would make a potential develoeprs job much
> easier.
> 

This is just based on the instance variables of the class.  The
irrelevant ones have been left out.

accounts - information about users
applications - information about the installed apps
acl - access control list, rights management
auth - authentication, login stuff
db - database abstraction class
crypto - cryptography, 2 way data encryption
categories - categories info
$common - commonly used functions
contacts - contact data
datetime - date and time related functions
hooks - data hooks
js - javascript
network - network related functions
extmatchs - pager
preferences - user specific config
session - session handler
send - messages (email sending) should be overhauled in HEAD
template - UI templates, used xslt in head if possible
translation - translation engine, just use lang() for most stuff
utilities - not very useful, I don't used it in any of my apps AFAIK
vfs - virtual file system, files storage system

HTH

Cheers

Dave
-- 
Dave Hall (aka skwashd)
API Coordinator
phpGroupWare
e address@hidden
w phpgroupware.org
j address@hidden
sip address@hidden
       _            ____                    __        __             
 _ __ | |__  _ __  / ___|_ __ ___  _   _ _ _\ \      / /_ _ _ __ ___ 
| '_ \| '_ \| '_ \| |  _| '__/ _ \| | | | '_ \ \ /\ / / _` | '__/ _ \
| |_) | | | | |_) | |_| | | | (_) | |_| | |_) \ V  V / (_| | | |  __/
| .__/|_| |_| .__/ \____|_|  \___/ \__,_| .__/ \_/\_/ \__,_|_|  \___|
|_|         |_|                         |_|Web based collaboration platform