JiNN FAQ Database Administration

27 December 2006

Pim Snel

Abstract

This tutorial learns to create a small admin interface for an external F.A.Q. database using JiNN.

1 Introduction

In this tutorial we're going to create an administration back-end using JiNN. The front-end of the F.A.Q. Application can not be created with JiNN. This should be written from scratch or using other tools. JiNN's purpose is to quickly give normal user access to a database without the need of writing code. Creating a complete full featured F.A.Q. application is outside the scope of this tutorial.

The intended audience are web-developers who make extensive use of databases. Basic knowledge of eGroupWare and MySQL is required. You need administrator access to an eGroupWare environment with JiNN installed.

2 Words you need to understand

You need to understand two important words used in JiNN.

JiNN-sites or just sites do NOT mean website but. A JiNN-site contains database connection information and it contains JiNN-objects. A JiNN-site can be seen as a single application in a framework containing more applications, or as a single database next to other databases.
JiNN-objects are assigned to table. A JiNN object automatically contains a form view and a list view. JiNN-objects can be seen as sections in an application or as tables in a database.

3 Setup the database

Before we can create a JiNN-site a database with tables must exist. We create a database for the F.A.Q. application in MySQL using the following schema:

: CREATE TABLE `category` (
  `id_cat` int(4) NOT NULL auto_increment,
`cat_name` varchar(30) NOT NULL default ",
PRIMARY KEY  (`id_cat`)
) ENGINE=MyISAM DEFAULT CHARSET=latin1 AUTO_INCREMENT=1 ;
CREATE TABLE `questions_answers` (
  `id` int(4) NOT NULL auto_increment,
  `cat_id` int(4) NOT NULL default '0',
  `question` varchar(250) NOT NULL default ",
  `answer` longtext NOT NULL,
  PRIMARY KEY  (`id`)
) ENGINE=MyISAM DEFAULT CHARSET=latin1 AUTO_INCREMENT=1 ;

As you can see the question can be put into categories using a foreign key.

4 Creating the JiNN-Site

Log into your eGroupWare environment and open JiNN. Make sure your are administrator. You may have to give yourself permission to use JiNN in the eGroupWare Admin Application. Because you are an administrator you have an extra admin site box menu in JiNN's sidebox.

Figure 1: JiNN Sidebox menu with Administration box

Click on the link Add Site from the sidebox menu. You must now define the database connection and the name of your JiNN-site. Do at as in the image below.

Figure 2: JiNN-Site settings containing database connection information

Before saving you can test your connection by clicking on the button test database and paths. In our example the database connection must succeed but the path and URL will give errors. This is nothing to worry about for this tutorial. When database connection was successful you can save the site, else check the database connection settings.

Figure 3: Testing the database connection

5 Adding Objects

When the JiNN-site is saved, the database connection is working and there are tables in the database, we can setup the JiNN-objects. After saving a new site the Site Settings Page is still opened. At the bottom of this page the site objects are displayed. We haven't made any yet, so lets add an object: click the button New Object.

Figure 4: JiNN-objects listed at the bottom of the Site Settings Page

The object properties window will open. You must give this object a name and assign a database table from the dropdown list. We will name the first object `Categories' and assign this to the categories table. Repeat this steps for the object `Questions & Answers'.

Figure 5: Creating a JiNN-object

6 Adding the first content

Though we're not finished yet we can already use these objects for maintaining content. Lets have a look at the categories first. Before we can access our object we open our JiNN-site. Select the Site in the JiNN Nagivation in the Sidebox.

Figure 6: Opening a JiNN-site

When the site is opened the active objects are listed in the JiNN Navigator. We will now select the object `Categories'.

Figure 7: Selecting an object

JiNN will now open the categories in the Listview showing no records. Lets create a new record by clicking on Add new record.

Figure 8: List View of the newly create object Categories

Add a category and click on save.

Figure 9: Adding new record

After the record is saved we will return in the last added record and on top of the page the message 'Record was succesfully saved' is displayed. Lets add another by clicking on new record(s) from sidebox menu.

Figure 10: Record saved successfully

When you're done click on Save and finish. You will now return to the list view which will show your records. Every record can be viewed, edited, copied or deleted by using these small icons.

Figure 11: icons to maintain records

7 Adding relations and changing labels

We now want to create the relation between category.id_cat and questions_answers.cat_id. After we have create this relation we can assign a category to a Question and Answer using a dropdown list.

Click on the object Questions and Answers from the JiNN Navigation and then click on Edit Object Form View from the administration sidebox menu

Figure 12: open design form

You will now see the developers mode of the form view which is one of JiNN's most important and powerfull screens. On top of the form you see a horizontal bar with configuration buttons for concerning the complete object. On the left side you'll see buttons and icons per field to configure every field.

Figure 13: developer toolbar

Click on the button Relation Widgets. The relation editor will be openen in a plugin. You can create different relation types, displayed in the tabs. We're going to create a One-to-many relation widget in this form which is the first tab. Click on the the button Create new relation.

Figure 14: create new relation

Then select keys, tables and fields like in the example below.

Figure 15: relation editor

Click on save when your finished. The new relation is displayed as in the image below:

Figure 16: save relation in relation editor

If this seems good click on close to close the popup. You will now see that the field cat id has a dropdown list containing our category names.

To finish our work we will edit the default label into Category. Click on the edit field symbol left from the cat id field.

Figure 17: edit field button

Change label into Category in the popup form and save and close the form when your finished.

Figure 18: change field properties

Click on the button Back to normal mode on top of the screen to see the form with the new created relation and try to enter and new record.

Figure 19: form with one-to-many dropdown list

8 Assign field plugin

One more thing configuration before our interface is ready. We will now assign a WSYIWYG-editor to the answer field of Questions and Answers. Click again on Edit Object Form View and then click on the edit field icon to get the field configuration popup again. Now select the plugins tab and then select TinyMCE from the dropdownlist

Figure 20: edit field properties

Figure 21: select field plugin

You'll will now get a lot of configuration options. Just leaving these as they are will give you result, but of course you are encouraged to play with them. Save the form clicking on save at the bottom of the page and close the popup.

Figure 22: configure field plugin

You're form will now look as this example below.

Figure 23: the TinyMCE plugin shown in design form view

And it will look below like this when you click on Back to normal.

Figure 24: the TinyMCE plugin shown in the normal form

That's all for this tutorial. You now have a simple administration interface for your FAQ database. When you assign access to you're normal users they can maintain data using these navigation buttons.

Figure 25: the moderators navigation menu

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