GenTIC2

GENTIC2 is a web-based tool that provides the means to quickly build search interfaces over existing databases, without the need of any programming effort. It is particularly suited for scientific data that can conveniently be displayed in tables.

Its main functionalities can be summarized as follows:

• Ability to connect to several databases from a single instance
• Ability to create several search forms for each database
• Ability to populate each form with various kinds of widgets wired to database fields (those that you want users to be able to search on)
• Ability to define, for each form, the structure of the table that will contain search results

The GENTIC2 package is provided with a default “look” that can freely be adapted by anyone with basic web design skills (see section 4).

1. Prerequisites

Setting-up GENTIC2 requires the destination computer to have the following software installed:

• JRE 5.0 or later
• Apache Tomcat 6 or later

It is assumed here that you have a basic knowledge of the prerequisites. Please refer to appropriate documentation regarding installation and usage issues.

Apart from the software mentioned above, there are also requirements in terms of practice: you will need a basic level in SQL language (selects and joins) and of course a good knowledge of the database schema(s) you are planning to plug GENTIC2 into.

2. Deploying the application

GENTIC2 is bundled into a zip file, gentic2.zip, which is a web-application archive. In order to deploy it, the first step is to unzip that file into any convenient location. After slightly configuring its contents, you will be able to place it inside Tomcat.

A single instance of GENTIC2 can manage several "data modules". Think of them as a way of splitting your application into different sections. In order to be functional, each module has a corresponding set of XML files, placed in the WEB-INF/modules/[module_name]. GENTIC2 is delivered by default with MODULE1 and MODULE2. You are free to remove module2 if you don't need several sections in your application (keep a copy of it though, since it contains all the blank but required XML files that are needed to add a module). You should then rename the module(s) according to the section(s) you want. For example if you want to deploy a crop-based application that supports banana and coconut, keep both folders and rename them to "banana" and "coconut".

Then, you will need to manually edit one configuration file per module, which is called connexion_default.xml. Inside it, apart from "base_de_donnees" which is optional (used for filtering database names by specifying a prefix they should start with), a valid entry must be provided for all tokens:

• we discourage amending driver_SGBD and driver since GENTIC2 has only been tested against MySQL so far (if you did so however, bear in mind that you would have to provide an appropriate jdbc driver by placing it into WEB-INF/lib
• domaine should contain the database host name or IP address
• login and password should contain details for giving the application rights to not only list available databases, but also query the one(s) you want it to work with.

Next, you will want to define a username and password for administrating the application. Open WEB-INF/applicationContext.xml with a text-editor and locate the “authentication-manager” tag. Simply replace values of attributes name and password with those of your choice for the user defined in there. You can add more users if needed. Example:

       <authentication-manager>
         <authentication-provider>
           <user-service>
<user name="admin1" password="pass1" authorities="ROLE_ADMIN,ROLE_USER" />
<user name="admin2" password="pass2" authorities="ROLE_ADMIN,ROLE_USER" />
           </user-service>
         </authentication-provider>
       </authentication-manager>

Finally, you should edit WEB-INF/classes/log4j.xml in order to specify a name for your application’s logfile (if you don’t, the default name gentic2.log will be used).

Now your GENTIC2 instance is ready for deployment. To proceed, you have to move the "gentic2" directory into the "webapps" folder found in your Tomcat installation (it is preferable to stop Tomcat before doing so). After that, assuming Tomcat is configured to run on your local machine's default port (8080), the resulting application will be accessible to you from http://localhost:8080/gentic2 (in order to amend the URL of your web application, you should rename the application-folder from "gentic2" to the name of your choice). You can then restart Tomcat.

3. Configuring access to your data

In order to enter the administration tool, you must click on the icon representing a man with a key, which can be found in the home page’s top-right corner. You will then be requested to enter valid user credentials such as provided in WEB-INF/applicationContext.xml. After doing so, you will end up on a page listing your modules with a radio button for each. By clicking one of them, you specify which module you are working on. The magnifier next to it is a shortcut link for its data-search interface.

As displayed to end-users, a module consists of a set of search-forms, each of them being accessible by selecting a tab. This is why the administration tool provides means to add, edit or delete search-forms to the selected module. A search-form is defined by a name of your choice, along with values that provide means to query a given database.

A search-form is based on one or several database tables, which can be added using the “Add a table” button, and are represented by a tab in the administration tool’s search-form edition page (therefore be sure to understand that a set of tabs in the administration tool corresponds to a single tab in the end-user interface).On that page:

• The “FIELDS” section lists the fields that end-users will be able to search on, allowing to apply restrictions to define subsets and to specify the kind of widgets to be used
• The “RESULTS” section lists the fields that will appear as columns in the result table
• The “JOINS” section allows to define the joins that will be required to link tables together in the generated SQL queries

Note that you can use arrows and red cross buttons to move / delete elements in an intuitive manner.

You will also find a button labeled “Manage detailed sheets” that leads to another administration page, the purpose of which is to define the contents of pages that will be linked from result fields for which the “Detailed sheet” option is enabled. This administration page works in a similar way as the one mentioned previously (search-form edition page).

4. Customizing the application's interface

The “top banner” which is included by all pages in the site, resides in JSP/topinc.jsp. You might want to modify it (or at least the images displayed in it) in order to customize the look of your application. Right after that include, all public pages have another include: menu.jsp.

As a consequence, the entire public part of the application contains a menu that has a maximum of 5 items:

• “Presentation” will be displayed if the file JSP/presentation.jsp exists (you can safely remove/modify it)
• “Data” will be displayed if at least one module is present in the application. If there are several modules then a sub-menu will automatically appear in order to offer a way of selecting one of them
• “News” will be displayed if the file JSP/news.jsp exists (you can safely remove/modify it)
• “Staff” will be displayed if the file JSP/staff.jsp exists (you can safely remove/modify it)
• “Links” will be displayed if the file JSP/links.jsp exists (you can safely remove/modify it)

If at least one of these 4 files does not exist: presentation.jsp, news.jsp, staff.jsp, links.jsp, then an extra item will appear before all others, providing a link to the home page.

The color of the big dot appearing under the menu, at the left-most side of the page is meant to remind the user where in the website he is. Each dot is an image file named after the page that is currently being shown: images/dot_presentation.gif is the dot for presentation.jsp for instance.

The contact email-address that can be seen at the right-most side of the menu can be configured via the “contactEmail” text property found in WEB-INF/classes/fr/cirad/tropgene/TextConstants.properties.

If you are familiar with cascading style sheets you can customize the end-user interface’s look by amending CSS/interface.css and CSS/onglets.css (the latter is where the tab-interface’s look is configured, this interface being based on http://www.barelyfitz.com/projects/tabber).

The Home page of your application resides in JSP/index.jsp. You can choose to keep it as such or modify it, knowing that the first paragraph it contains can be configured via the “homePageText” property found in WEB-INF/classes/fr/cirad/tropgene/TextConstants.properties. Below that, you can find a list of images illustrating each module (named images/modules/[module_name].jpg), the size of which should be 100*75 if you keep the provided JSP/index.jsp, and that link to corresponding search interfaces.