Guise Framework Installation

Guise Framework can quickly be installed with a minimal configuration.

Requirements

• Java 6.0 or later.
• The JavaMail library present in the web application classpath.
• The Apache Commons FileUpload 1.2 or later library, along with the Apache Commons IO 1.3.1 or later library present in the web application classpath.

Assumptions

These instructions make the following assumptions:

• You have a Java servlet container hosting a web application stored at /server/webapp/.
• Your web application definition file is stored at /server/webapp/WEB-INF/web.xml.
• You want to define your Guise application using the file /server/webapp/WEB-INF/example-application.turf.
• You want your Guise application mapped to /webapp/example/.

Download

You will need to download the Guise Framework source files so that you can build the Guise library.

Procedure

1. Download, build, and install the Guise Framework library file in the application classpath.
2. Install the JavaMail library in the web application classpath.
3. Install the Apache Commons FileUpload 1.2 and Apache Commons IO 1.3.1 libraries in the web application classpath.
4. In your web.xml file, add an HTTP Guise session manager as an HTTP session listener before the first <servlet> definition:

   <listener>
     <description>The class that manages Guise sessions in an HTTP servlet environment.</description>
     <listener-class>com.guiseframework.platform.web.HTTPGuiseSessionManager</listener-class>
   </listener>

5. In your web.xml file, add a servlet definition for your Guise application using the GuiseHTTPServlet. You can have as many Guise applications defined as you like, each using GuiseHTTPServlet, as long as each is mapped to a different path. For each Guise application, indicate the separate Guise application description file relative to web.xml:

   <servlet>
     <description>Guise Example Application</description>
     <servlet-name>guiseExampleApplication</servlet-name>
     <servlet-class>com.guiseframework.platform.web.GuiseHTTPServlet</servlet-class>
       <init-param>
         <param-name>application</param-name>
         <param-value>example-application.turf</param-value>
       </init-param>
     <load-on-startup>1</load-on-startup>
   </servlet>

6. Map your Guise application to its application context path:

   <servlet-mapping>
     <servlet-name>guiseExampleApplication</servlet-name>
     <url-pattern>/example/*</url-pattern>
   </servlet-mapping>

7. Now describe the actual Guise application in the example-application.turf file using URF PLOOP to map your values to the Guise API. Map each main panel to a unique application path, relative to the application base path:

   `URF:
     "guise"~<java:/com/guiseframework/>
     "example"~<java:/com/example/>
   ;¤
     *guise.DefaultGuiseApplication:
       destinations=[
         *guise.ComponentDestination("", example.HomePanel)
         *guise.ComponentDestination("about", example.AboutPanel)
       ]
     ;
   .

8. If you have any resource files (such as included XHTML files) that are accessed by your Guise application, store them under a WEB-INF/guise/resources/application directory, which in this example would be /server/webapp/WEB-INF/guise/resources/example/.

You now have a Guise application that receives requests at http://www.example.com/webapp/example/ along with two main panels, accessible via http://www.example.com/webapp/example/ and http://www.example.com/webapp/example/about. The main panels are mapped to the navigation paths "" (the empty string) and "about", respectively.

Configuration

Guise offers as many configuration options for your application as is available in the Guise API and the API of any Guise subclass you have created, by using URF PLOOP inside your application description document. Below is a complete Guise application description taking advantage of several configuration options:

`URF:
  "urf"~<http://urf.name/urf/>
  "guise"~<java:/com/guiseframework/>
  "example"~<java:/com/example/>
;¤
  *guise.DefaultGuiseApplication:

    †supported locales (optional)‡
    locales=[«*urf.Language("en-US")», «*urf.Language("fr")»]

    †WebTrends DSC ID (optional)‡
    dscid="0123456789"

    †list of components mapped to navigation paths‡
    destinations=[
      *guise.ComponentDestination("", example.HomePanel)
      *guise.ComponentDestination("about", example.AboutPanel):

        †additional style for this destination (optional)‡
        styleURI=<about-stylesheet.css>

        †categories for this destination, used in reporting (optional)‡
        *guise.Category("category1", "First Category"):
          categories=[
            *guise.Category("subcategoryA")
            *guise.Category("subcategoryB")
          ]
        ;
      ;
    ]
  ;
.