You need to have a working Java Web Application server. The ginp is developed with Tomcat and the Standard Java Developer Kit available from Sun, but it should also work with other J2EE platforms. This document is focused on a Tomcat installation, which is known to work. You are of course free (as in freedom) to use other environments. If you have problems or comments about making the software more platform and environment independent please post them to the ginp users mailing list.
The ginp.war (Web Application Archive) file, which can be downloaded from sourceforge, contains the complete web application. The simplest way to get started is to copy this WAR file to your Tomcat webapps directory ($TOMCAT_HOME/webapps/). Restart Tomcat and it will deploy the application by unpacking the WAR file and automatically start it in the /ginp context.
The ginp application includes a configuration wizard that can setup the main configuration file. Connect a browser to http://mytomcatserver:8080/ginp/ to confirm the webapp has been deployed and follow the configuration wizard to setup an initial Ginp environment. You will need to provide it with the path to a local directory containing some photos (JPEG files).
Note: at this time, the configuration wizard does not always run to a successful completion. If you experience problems, you should finish the installation by creating $TOMCAT_HOME/webapps/ginp/WEB-INF/ginp.xml maunually. Use the following template and modify it to suit your own environment.
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE ginp SYSTEM "ginp.dtd" >
<ginp>
<collection>
<name>My Private Photo Collection</name>
<root>/path/to/my/Photos</root>
<users></users>
<admins>
<username>admin</username>
</admins>
</collection>
<collection>
<name>Guest Photo Collection</name>
<root>/path/to/public/Photos</root>
<users>
<username>guest</username>
<username>admin</username>
</users>
<admins>
<username>admin</username>
</admins>
</collection>
<user username="admin" userpass="adminpass" fullname="Administrator" />
<user username="guest" userpass="guestpass" fullname="Guest User" />
</ginp>
The organisation of the source and project files fits the "Maven Project Model". You can either use maven (veriosn 2) to build the project or follow the instructions below to merge the extracted war and souce files with your project.
# 1. Choose a sample style that most fits your requirements.
# 2. Copy the style folder to your project
cp -r ginp/web/styles/favoritestyle myproject/web/myginpfolder
# 3. Copy across the ginp src files to your projects src tree.
cp -r ginp/src/* myproject/src/
# 4. Add the ginp servlet definitions to your myproject/web/WEB-INF/web.xml file. Note you must change the url-pattern of the ginpservlet but not the ginppic
....
<servlet>
<servlet-name>ginp Controller Servlet</servlet-name>
<description>
Controller Servlet for the ginp Photo Browser
</description>
<servlet-class>net.culnane.ginp.GinpServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet>
<servlet-name>ginp Picture Servlet</servlet-name>
<description>
Servlet that delivers the images
</description>
<servlet-class>net.culnane.ginp.GinpPictureServlet</servlet-class>
<load-on-startup>2</load-on-startup>
</servlet>
<servlet>
<servlet-name>ginpSetup</servlet-name>
<servlet-class>org.apache.tapestry.ApplicationServlet</servlet-class>
<init-param>
<param-name>org.apache.tapestry.application-specification</param-name>
<param-value>/net/sf/ginp/setup/web/ginpSetup.application</param-value>
</init-param>
<load-on-startup>0</load-on-startup>
</servlet>
....
<servlet-mapping>
<servlet-name>ginpSetup</servlet-name>
<url-pattern>/ginpSetup</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>ginp Controller Servlet</servlet-name>
<url-pattern>/ginpservlet</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>ginp Controller Servlet</servlet-name>
<url-pattern>/myginpfolder/ginpservlet</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>ginp Picture Servlet</servlet-name>
<url-pattern>/ginppic</url-pattern>
</servlet-mapping>
....
# 5. Copy the Tag Library Definition and Configuration File Definition file to your project
cp ginp/web/WEB-INF/ginp.tld myproject/web/WEB-INF/ cp ginp/web/WEB-INF/ginp.dtd myproject/web/WEB-INF/
# 6. Edit your web.xml file to add the ginp Tag Library
...
<taglib>
<taglib-uri>/ginp</taglib-uri>
<taglib-location>/WEB-INF/ginp.tld</taglib-location>
</taglib>
...
# 7. Copy across the jars.
cp ginp/web/WEB-INF/lib/*.jar myproject/web/WEB-INF/lib/
# 8. Build the project as per the "Application Developer's Guide".
cd myproject ant deploy
# 9. Customise the sample style so it fits to your website.
# 10. Good Luck and if you are having problems with the above please see the ginp/ReadMe.txt for information about how to get help.
The user interface can be translated into any language using the setLanguageCode command and the src/main/resources/net/sf/ginp/Ginp_lc_CC.properties ResourceBundles. Where lc is a lowercase language code and CC is the uppercase country code.
When a new session is established with the Application it attempts to set the Locale settings based on the browsers request headers for example: en_GB would be British English. It is a good idea to provide a link to override this setting to allow the user to select their preferred language.
For Example:
<a href="<ginp:link url="ginpservlet?cmd=setlanguagecode&code=fr" />"Click Here for French</a> <a href="<ginp:link url="ginpservlet?cmd=setlanguagecode&code=fr_CA" />"Click Here for Canadian French</a>
The Application will then search the properties files in the webapps/ginp/WEB-INF/classes/net/sf/ginp/resources folder, for the closest language and locale match.
The ResourceBundles need to be converted to ANSII files with Unicode escape sequences for non ANSII chars. This can be done with the command:
native2ascii Ginp_es.properties.bak >Ginp_es.properties
Java ResourceBundles are explained in more detail at: http://java.sun.com/developer/technicalArticles/Intl/ResourceBundles/
If you have done some translations of the Ginp.properties file please send them to the ginp developers.
Add URIEncoding="UTF-8" to the server.xml file in Connector definition section, so parameter encodeing works correctly.
The taglib attribute dateformatpattern allows the JSP developer access to the java.text.SimpleDateFormat date and time patterns. If this is not used then the internal storage value is used displayed. ie. yyyy.mm.dd. The format pattern and language code are used to display the date as required.
Example Patterns:
dateformatpattern en de
EEE dd.MM.yyyy Wed 31.12.2003 Mi 31.12.2003
EEE d MMM yyyy Wed 31 Dec 2003 Mi 31 Dez 2003
EEEE d MMMM yyyy Wednesday 31 December 2003 Mittwoch 31 Dezember 2003
For more information see the Java API Documentation for the java.text.SimpleDateFormat class.
The ginp code uses Commons-logging. We recomend log4j as a logging implementaion. To use log4j need to do that following 3 tasks:
1. Download the log4j jar and put it in your classpath (ie. webapp/ginp/WEB-INF/lib/log4j.jar)
2. You need a config file there is a config file sample supplied with the ginp at webapp/ginp/WEB-INF/classes/log4j-example.properties.
3. Set the environment variable log4.jconfiguration=log4j-example.properties
(For more information see: http://jakarta.apache.org/commons/logging/)