JiNN User Manual

Pim Snel

April 13 2007

This document is the official JiNN User Manual. The latest version can always be found in the subversion repository of egroupware.

Chapter 1
Introduction

JiNN was made originally made for maintaining websites online, typically called a Content Management. In the early days JiNN was a just a CMS, but today JiNN can do a lot more then that. With JiNN database applications can be developed very fast. Developers don't have to write code but can design their application using the JiNN's webbased developer tools. Developers can rapidly develop database applications that can be used as native eGroupWare application or used from inside the JiNN Users Mode.

JiNN is written from scratch and still maintained by Pim Snel. Development started in 1999.

1.1 In short

as developer you can develop database interfaces and complete applications which can be used by non-technical users.
as user you can maintain your data easily on line.
without programming code create CRUD or BREAD screens.
make use of standard or custom database field plugins like the FileManager, ColorPicker?, Visual SelectBox?.
make use of standard or custom event plugins like email or change value.

1.2 Features

Fast creating CRUD / BREAD screens using webbased tools
Visual Relation Editor
Database field plugins for custom input and storage
Event Plugins for triggering scripts after application events
eGroupWare API for using JiNN from other eGroupWare applications
Importing and Exporting CSV files with custom mapping profiles
Saving and opening JiNN Applications
Creating Custom HTML Reports
Reusable database filters

1.3 Typical JiNN Solutions

Website Content Management Systems
JiNN is a very useful tool for web developers who need to setup a CMS for their frontend product. You're able to setup a nice idiot-proof interface for you're complex database design within minutes. Even one-to-many relations, and many-to-many relations are a peace of cake.
Webshop Maintainance System
Simple Project Management
Invoice Administration
Wholesale Catalog Administration
Ticket Tracking
Mailinglist Management

1.4 Current Status and Future

JiNN can currently be used to rapidly creat CRUD / BREAD applications. Our goal is to create a complete Database Application Development Studio and IDE simular to Microsoft Access of OpenOffice? Base. Complex applications must be created without writing code. If functionality is missing reusable plugins can be creating with PHP.

Chapter 2
Using JiNN Applications as Moderator

2.1 Site Navigation

2.2 Object Navigation

2.3 Browsing through records

The records listing screen is the first step for accessing you object records. If you have selected an object this screen is automaticly opened showing you the first page with records. From here you can do a lot of things with you're data. Below you find a list of regular actions. Notice that the developer of you're JiNN application can have disabled buttons or functions for this object. Some of the stuff described below may not be available in you're application.

2.3.1 Browsing using the pager

When there are a lot a records JiNN splits the listing into pages showing 20 records per page by default. When you open an object for the forst time you enter the record listing on page one. In the center right above the records you'll find the pager. Here you can click on one if the 9 pages or the last page.

2.3.2 Editing Single Field Value

When a cell highlights at when the mouse passes over this indicated that this field can be live edited from within the list view. You can edit the content of this field without opening the complete record. Just simply double click the cell and it will change to edit mode. When you're done click once somewhere else in the same column. The value is now saved. You can repeat this as many as you like for other fields.

2.3.3 Creating a new record(s)

You can click the "Add a New Record" button to add a new record in this object.

2.3.4 Changing the ordering direction and field

Sometimes you'll want to browse through you're data when they have a different ordering. To change the order of your records click on a column head set the ordering on this column. Click again to change the direction of the ordering on this column.

2.3.5 Simple Keyword Search

Lets say you have a lot of names and addresses listed and you want to quickly find all the records containing "Adam". You can simply type "Adam" in the search box and click the Search Button. JiNN will do a case-insensitive search for "Adam" in all fields so the results could look like the example below.

Adam Smith	12 Greenhill	767886 South Ford

Clare Johnson	45 Adamstreet	2545 Oxhampton
Peter Dadam	2 Monkey Plaze	2545 New Liverton

To remember you that you're quick search filter is still active the search box has soft red background.

2.3.6 Advanced Filtering

Sometime you'll need more powerfull filtering and you may need these filters in later sessions. You can click the "Edit Filter" button to specific field filters.

To remember you you have an active filter the filter select box has soft red background.

2.3.7 Selecting Records

A lot of actions that can be done on a record can also be done on a selection of records. The make a selection you check the checkboxes located on the far left of every record. You can also select all the records in the current page at once by clicking the checkbox left bottom of the list below the records.

2.3.8 Opening one or more records for viewing

You can click on the magnify glass icon on the left of the record to view its content in detail. You can also check more then one of the record checkboxes and then click on the magnify glass icon on the left bottom of the screen below the records. You will now have a detailed view of all these selected records.

2.3.9 Opening one or more records for editing

You can click on the pencil icon on the left of the record to edit its content. You can also check more then one of the record checkboxes and then click on the pencil icon on the left bottom of the screen below the records. You can now edit the contents of all these selected records.

2.3.10 Deleting one or more records

You can click on the red cross icon on the left of the record to delete it. You can also check more then one of the record checkboxes and then click on the red cross icon on the left bottom of the screen below the records. All the selected records will be deleted. There'e now way to restore deleted records.

2.3.11 Copy a record

To copy a record click on the white paper with the plus sign icon. All the contents exept for the primary key will be copied to a new record.

2.3.12 Exporting records to CSV

You can export you selected records to CSV by clicking on the floppy disk icon located on the left bottom below the records.

2.3.13 Merging Data into Reports

You can create reports templates or use existing templates to create a new Report with merged object data. The merged data can be retrieved from all records, a filtered record set or a selection of records.

2.3.14 Run Custom Event Scripts

When you're application developer has setup Event Scripts in the WalkList? Event you can run these scripts on all records, a filtered recordset or a selection of records. An example of an Event Script is to send an email to all addresses stored in the email-field in the current object. Custom Event Scripts appear as buttons on top of the list records screen.

2.3.15 Viewing records

When you clicked on the view record icon of a records you get detailed wiew of all contents of one record. Some data may be presented in a specific way in stead of showing you the flat field data. For example you may see a litte green box that represents the color that is set in a that field. The real value shall be something like #00FF00, but the colorpicker plugin translates this to a box with representing color.

It's possible you have made a selection of records to view. Every record is displayed in a box with a dashed line.

You can click the Edit Button to Edit the current displayed records(s) or you can click the Back to List button to return to the Record List.

2.4 Editing records

2.4.1 Modifying / Entering Data

When you clicked on the edit record icon of a record you can change its contents.

Most data fields will be presented and can be modified using regular input fields. Some data though may be presented in a specific way in stead of showing you the flat field data. These fields have Field Plugins Attached to them.

For example you may see a litte green box that represents the color that is set in a that field. The real value shall be something like #00FF00, but the colorpicker plugin translates this to a box with representing color. To change to color click on the box and the popup that will be opened helps you choose a new color.

There are a lot of possible Field Plugins. There are plugins to add or upload images, to enter text using Richtext Boxes (Like Word). The number of Field with specialized tasks are increasing everyday. In most cases it will be simple to understand how the Field Plugin work. Importing CSV data

2.4.2 Saving and Closing

When you're satisfied with you modification you can click save to update the record data. This step cannot be undone. If you want to leave the record unmodified, click the Back to List button to return to the Record List

2.5 Exporting data to CSV

2.6 Reports

Chapter 3
Developing JiNN Applications

3.1 Creating and changing Sites

A JiNN Site stands on top of the Hierarchie. It contains al the essention database and filesystem information and all it is the container for all Site Objects.

3.1.1 main properties

Site Name: This is diplayed to the user
Website URL. Used for creating a shortcut to the frontsite. (optional)
Table prefix for data objects: Normally objects must be created manually. If you want to integrate database tables that are automaticly created and show them in the menu enter their prefix here. JiNN Scan for them and adds them to the Site Objects List (optional)
Environment profile to use: Activate the used Environment Profile here.

The Buttons:

Save: saves all Site data
Export: saves all Site data to a JiNN File. This file can be used used to transfer sites to different hosts.
Test database and fs: Tests if JiNN can use the database and read/write to the filesystem basepath.

3.1.2 Environment profiles

A site has to environment profiles which is easy when you develop JiNN Sites on a different server where you run the production sites. By using the profiles you don't have the enter the database and filesystem data over and over again when you transfer the site to the production server and back again.

To create a usable site you must at least fill in one Environment Profile. In the profile enter the following:

database information to create a database connection.
filesystem BASEPATH: Used by some plugins to store images or files.
filesystem BASEURL: Used to show the stored images or files in the webbrowser (optional)

3.1.3 Site Objects

When the site is initially created you can add objects or edit existing objects.

Checkbox: You can select more objects by checking their checkboxes. On the bottom of the list cou can click on delete to delete all selected Objects.
Add Object: pop's up a window in which you can enter the first needed information to create a new Site Object
Edit Icon: Click on this to edit the Object Properties
Delete Icon: Click on this to delete the Site Object
Save Icon: Click on this to export all object information to a JiNN file. This file can be imported in another Site even on another Server.

3.1.4 Design Objects

When you created a new object it's the Add/Edit Form is automaticly created so it can be used instantly. Though this may be enough in some cases mostly you want to add or edit some extra proprties to this object.

In this screen you see every field that is available in the object and you can change all the Object and Field Properties.

3.1.4.1 Database Requirements

3.1.5 General Object Properties

Object Name
Table to use for the object
SQL Where filter: e.g. "CATEGORY='food' AND ACTIVE='y'
Hide from menu: some objects serve as child-object and don't need to be shown in the object menu
Max record: Some objects only allow 1 record (this will be a free number in the future)

3.1.6 Define Relations

This opens the Object Relation Editor in which you can create advanged database relations. The following relations can be created:

One-to-Many: Creates a select-box widget where the user can link one foreign record
Many-to-Many: Creates a two combo-select-boxes. One with all available foreign records and one with all linked foreign records.
One-to-One: Merges the fields of the foreign object in this object. Use this to glue to tables
Many-to-One: Created a list with all linked records. Records can be add from the within the form and record can also be edited from within the form. (Not finished at the time of writing)

3.1.7 Field Properties

In the design form screen you can click on a field to open its properties in the properties pane located on the left. Older JiNN versions also display an edit icon next to the field which you can click to open an popup with all field properties.

You can change the name
Add tooltip information
Change form visibility
Change form default list visibility
Make field mandatory
Select Field Plugin

3.1.8 Field Plugins

A JiNN field plugin adds functionality to the input forms and a method the way data is stored in to the database. The application developer assigns a plugin to a selected field and tunes its behaviour by modifying its configuration. The modified behaviour is limited to the assign field. JiNN ships with a lot of core field plugins. You can see what plugins are registered in your JiNN installation by opening the JiNN application and opening About JiNN from the general menu.

In this section we describe them and also give an example how to use them.

3.1.8.1 ewline2Break

for replacing breaks with the HTML equivelent

3.1.8.2 Date

3.1.8.3 selectbox

a selectbox

3.1.8.4 boolian

for adding a boolian selectbox

3.1.8.5 AttachmentPath

For uploading and selecting one or more files

3.1.8.6 Order Plugin

3.1.8.7 Switchboard Plugin

3.1.8.8 Timestamp2integer Plugin

3.1.8.9 Timestamp Plugin

3.1.8.10 Unserialize Plugin

3.1.8.11 Password Plugin

string to upper of lowercase plugin

3.1.8.12 Publication Timer plugin

3.1.8.13 colorlab

The Colorlab Plugin is written by GABRI�L RAMAKER. Colorlab is flashmovie that binds to a varchar field. It can be configured to let the user select a color from a predefind pallet or from photoshop like color selector. It stores a W3C validated hexadecimal code in to the database, like #00FF00.

3.1.8.14 imagepath

ImagePath is a plugin which offers a method for uploading images which are stored in the upload path. If necessary ImagePath resizes the image to given max sizes and generate thumbnails. The paths to the images are stored in a varchar or text field seperated by semicolons. Programmers can use the PHP function explode to access to file locations from an PHP-array

3.1.8.15 tinymce

Description

The TinyMCE plugin creates an WYSIWYG html editor in your record edit form.

3.1.8.16 word2html

Description

The word2html plugin is able to import an uploaded Word document and convert this to html. It saves all images to the configured upload path and stores the HTML in the assigned field of a table record.

Requirements

This plugin depends on the wvWare toolkit. Most available in as standaard package in most linux distributions. See http://wvware.sourceforge.net/ for more info.

Configuration Options

path to wv executable: This option help the plugin find the executable which is needed for conversion. The plugin defaults to /usr/bin, but /usr/local/bin
Subdirectory to use for extracted images: Embedded Images can optionally be saved in a child directory in the configured upload path
Max. image width (else leave empty): If embedded images are wider then this maxumum width in pixels they are resized untill they fit. Aspect ratio is always preserved.
Max. image height (else leave empty): If embedded images are heigher then this maxumum height in pixels they are resized untill they fit. Aspect ratio is always preserved.

Example

Word2html is ideal to use in combination with the TinyMCE plugin. First assign the word2html plugin to your destinated text field. The create an an extra field element and assign the TinyMCE editor to it. Make sure you enable the images button in the TinyMCE conifguration. Also make sure the TinyMCE element is ordered below the word2html field.

When a moderator uploads his word document with word2html plugin, the converted content will be displayed in the TinyMCE editor. The moderator can now make changes to the converted text with the TinyMCE editor.

3.1.9 Object Events Plugins

This is a very early events handleling implementation using plugin scripts which can be configured per event. At this moment only one event exists and only one plugin script exists Events:

On Single Record Update: Script is run after an existing record is saved.
Plugins Scripts:
Email: Script can use field(s) information to email this to configurable addresses.

3.1.10 Reports

Very early implementation of reports functionality. You can use it to output HTML reports based on field information. You can create templates using a visual HTML editor. The Templates support PHP scripting. Future features will include PDF generation and events handleling.

Chapter 4
Administration

4.1 Access Rights

JiNN makes it possible to have a lot of site-databases moderated by a lot of people all in one system. Access Rights are assigned at table-level and every site can have one or more site-administrators.

Chapter 5
eGroupWare Application Development Using JiNN

JiNN has can be used to develop other eGroupWare Applications. This saves the developer lots of time so he can concentrate on more difficult parts o his applications.

5.1 JAPIe Technology

5.2 Site Setup

5.3 Updating Lang File

5.4 Calling Japie from your Application Code

Chapter 6
Extentending JiNN

6.1 Writing New Field Plugins

It's quite easy to write new field plugins. Using custom plugins you can extend the functionallity of JiNN with little effort. A field plugin has a few requirements.

A Field plugin has a unique lowered case name without spaces or non alpha numeric characters.
All plugin files resides in one main directory starting with two underscores and then the name of the plugin. E.g. __myplugin
The plugin main directory is located in .../egroupware/jinn/plugins/db_fields_plugins/ or in .../egroupware/jinn/custom_plugins/db_fields_plugins/. The custom plugin directory makes it possible to keep JiNN vanilla and you are encouraged to put you own plugins here.
There must be a register.php file which gives jinn general information about the plugin.
There must be a class.myplugin.php file where the actual plugin methods executed from.
The plugin class file can optionally contain 5 public method which are run when available.

formview_edit(....)

this method renders the field widget when a records opened for editing or a new record is will be inserted.

formview_read()

Called when opening a record for viewing (read only) and formats the field data.

listview_read(....)

this method renders the value of the field when is displayed in the list view.

on_save_filter(....)

(Storage Process Function) This method is run after the form is submitted. It gets the field value as input argument and returns the processed field value for further storage in the database table.

advanced_action()

Currently only used in vorder. It makes it possible to have a custom public function called from the plugin class.

The best way to start writing plugins is to browse through existing plugins JiNN ships and use them a you example.

Chapter 7
Extra Information

7.1 Resources

JiNN User Manual: The Official Complete JiNN Manual. This document is always located at http://svn.egroupware.org/egroupware/trunk/jinn/doc/official-manual/
Tutorial_Creating a FAQ_Administrator: 30 minutes tutorial where you create a JiNN Application which administrates a FAQ database. Still in development.
Mailing-lists: see http://www.egroupware.org
Forum: ...............
Bug Reports: see http://www.egroupware.org
Feature Requests: see http://www.egroupware.org
Source code: see http://www.egroupware.org
Commercial Support: see http://www.lingewoud.nl

7.2 FAQ

Can I create my website using only JiNN?

No you can not (not yet). With JiNN you can easily setup the CMS of your website. You can use this CMS to publish stuff on you site and maintain all existing contents including Images, Music etc... The website isself must stull be coded or setup using another existing system. We developed JiNN because we like to create websites from scratch so it fits perfectly and not like it somes from a bug fabric.

In the future we do want to make JiNN powerfull and customizable enough to create complete websites with it, in it.

Can I only create Website CMS's With JiNN?

No, you can do a lot more with JiNN. We are bit sorry we once named to the database container a JiNN Site because the word Application would fit much better. You really can create nice applications using JiNN, and quite fast also without writing code.

Can JiNN setup a database schema?

No a the moment JiNN can only play with its contents. We use phpMyAdmin or Ralf Beckers great DB Tools for creating and altering database schema's. Lex Vogelaar want's to implement schema creating features in the near future.

Does JiNN work with other databases then MySQL?

We have currently experimental support for PostgreSQL and it this works other databases that eGroupWare supports will follow soon.

Does JINN run on Windows?

It seems to run on Windows though the author never had intentions to make it run on Windows. Some Field Plugins will definitely not work on Window. All inuces like Mac OS X, Linux and the BSD's are completely supported.

7.3 Resembling Software

The idea behind JiNN is quite unique and there are no tools that do the same. There are resembling tools though. Here a list:

Webbased

[http://phpfriendly.sourceforge.net/ phpFriendlyAdmin]
[http://dasystem.sourceforge.net/ DASystem]
[http://www.derosetechnologies.com/ Accession]
[http://greenhell.com/dataMiner/ dataMiner]

Desktop

Microsoft Access
Filemaker

File translated from T_EX by T_TH, version 3.67.
On 16 Apr 2007, 12:48.