This document explains howto use Jinn for phpGroupWare as webdeveloper, administrator and end user which we call moderator from now on.
1. Introduction 1
2. Database design 2
1. Database requirements 2
3. Setup / Administration 3
1. Global Settings 3
1. Setting and modifying global settings
2. Sites and Site-objects 3
1. Global Configuration 3
2. Creating a site 3
3. Browsing, deleting and modifying sites 3
4. Creating site-objects 4
5. Browsing, deleting and modifying sites-objects 3
6. Adding additional relations 5
7. Adding additional form-plugins 6
3. Access rights
1. Setting access rights for a site 7
2. Setting access rights for a site-object 8
4. Site Moderation
1. Select Site and Site-object 9
2. Add new entry 10
3.
Browsing, modifying and deleting entries 11
5. Example site for
practice
Jinn for phpGroupWare is a multi-site, multi-database, multi-user/-group, database driven jinn written in and for the phpGroupWare Framework. Jinn for phpGroupWare makes it possible to have a lot of site-databases moderated by a lot of people all in one system. Access Rights are asigned at table-level and every site can have one or more site-administrators.
Jinn for phpGroupWare is a very useful tool for webdevelopers who need to setup a jinn for their frontend product. You're able to setup a nice idiot-proof interface for you're complex database design within minutes. Even one with many, and many with many relations are a peace of cake.
Currently it's only tested with MySQL but because it only uses the phpGW-API database calls it's must be able to work with PostgreSQL too.
Jinn for phpGroupWare is ideal for creating a moderators interface for existing databases. Developers have the freedom to design what ever they want at the frontend of the database, without having to worry about the moderaters side of the database. They can simply attach the Jinn for phpGroupWare to their database and voila a complete moderators interface is their. This is the beauty of the Jinn for phpGroupWare. There are only a few things database designers have to keep in mind before they create a new datebase. This section discusses the requirements of the database and then gives an example howto create a valid database which can be attached to the Jinn.
1. Database requirements/conditions
There are only a few conditions a database have to meet. These conditions have to do with reserved fieldnames, fieldtypes etc....
Thirst field, 'id'
For a start when you design a table the thirst field has to be called 'id' and has to be a unique integer that is the primary key of the table and is auto incrementing. The size of the integer doesn't matter. Look at the examble below for creating a table with a valid thirst field.
CREATE TABLE news (
id mediumint(9) NOT NULL auto_increment,
body text NOT NULL,
PRIMARY KEY (id)
) TYPE=MyISAM;
Reserved fieldnames: id, image_path, attachment_path
When you read the text above you can imagine that the fieldname 'id' is a reserved name. When the jinn sees a field of this name it automaticly assumes this is the first identifierfield of the table. There are e few more reserved fieldnames. for a start 'image_path'. When the jinn sees a field with this name and the fieldtype is textblob it automaticly creates a file-uploading field. Images are uploaded to the configured upload directory. Go to section 3.3 to read more about configuring upload directories. The path relative to this directory is stored in the image_path column. Users can upload more then one image because the patyhs are seperated by a ';' (semicolumn ?). Webdevelopers can user the explode function to get the seperate image locations.
The fieldname attachment_path has the same story. When the jinn sees a fieldname called attachment_path and the fieldtype is a textblob it automoticly creates a uploadfield so users can upload any kind of files, like movies, zip-archives, java-applets, etc. The attached files are stored in the configured upload directory and the file locations are stores in the the textfield seperated by semicolomns.
This chapter describes how to setup site and site-objects in Jinn for phpGroupWare and howto assign access rights to this sites or site-objects.
Name conventions
Before going on explaning how to setup site and site-objects I'll first explain them meaning of these things. Sites in Jinn for phpGroupWare are synchrone to the a database in MySQL or PostgreSQL. Every site has its own database assigned to it.Site-objects are synchrone to database tables. After the configuration of a database you can assign site-objects to the tables of that database. We have chosen for these names because it's more understandable for the end-users, the site-moderators.
1. Global Configuration
The section Global Configuration has the purpose to set the locations to system utilities like Convert, to set standard file types and sizes and other global settings or defaults. You can keep this settings unchanged, but if you want to use the image upload feature you have to set a calid path for convert. This tiny command line application comes with the terrific ImageMagick package and is used for converting images to specific web formats, gif, png or jpg or to change the size of an uploaded image. The beauty of convert is that it can handle almost every known image type and is able to convert or modify them. This way we make it possible for non-technical moderators to concentrate on the image itself instead of the filetype. More information on convert and ImageMagick and the software itself can be found on the official website www.imagemagick.org. It is free to use and distribute.
2. Creating a site
To create a site login as adminstrator in phpGroupWare and go to administration. At the Section Jinn you'll find the link of button 'Add Site'.
After choosing this a form is opened where you must fill in all the site settings. The essential settings are Site name, Site db name, Site db host, Site db user, Site db password, Site db type.
Site name is used to identify your site to you and the moderators in the rest of the application. The database settings are used to create connections to the site database. If you make a typo in the database settings the application will stop.