Decorating a Page (Decorator 3)

Problem

How to apply decoration such that all web applications have the same layout, header and footer?  How to manage different families of web applications?  How to manage decorators so that minor changes are pushed out to all web applications automatically?

Pre-requisite

• Learn SiteMesh

Solution

ACT uses SiteMesh to decorate pages any pages that is returned as text/html.  For each URL pattern, you can instruct SiteMesh to decorator a page with a specific decorator.  Decorators are further broken down into families that generally look the same but with different navigation menu and breadcrumbs that pertains to each own business functions.  To better manage these decorators, all these decorators are located in the one web application called the 'decorators'.  This should be bundled with your Tomcat 4 distribution when you setup your development environment in the getting-started guide.

• Decorator
  • Choosing a Decorator
  • Updating a Decorator
• Navigation Menu & Breadcrumbs
• Customize Webapp Name
• Customize Log Out URL
• Customize Feedback URL
• Customize Search
• Troubleshooting

Choosing a Decorator

Here is a sample list of available decorators:

You can specify which decorator you want in the file web/WEB-INF/decorators.xml.  Change the page parameter to the appropriate decorator. For example:

<decorator name="default" webapp="/decorators" page="/decorators/2/financial.jsp">
    <pattern>/*</pattern>
</decorator>

You can specify multiple decorators for different URL.  This is good for a web application that behaves the same but looks different for different audiences. 

<decorator name="student-prospective" webapp="/decorators" page="/decorators/2/academic-student-prospective.jsp">
    <pattern>/prospective/*</pattern>
</decorator>
<decorator name="student-current" webapp="/decorators" page="/decorators/2/academic-student-current.jsp">
    <pattern>/student/*</pattern>
</decorator>

In the same file, you can also exclude certain URL pattern from being decorated.  A good example would be not decorating an inline html that is returned to the client browser.

<excludes>
    <pattern>/inline/*</pattern>
    <pattern>error.jsp</pattern>
</excludes>

Updating a Decorator

Decorators are managed through the UXT team.  Please contact us for any decorator requests, such as adding or updating.

You'll notice the version number in the page parameter.  You may choose to use a version of a decorator by specifying a version number.  When UXT has a new version of a decorator, you can choose to upgrade by changing the version number to the latest version number.

<decorator name="default" webapp="/decorators" page="/decorators/2/financial.jsp">
    <pattern>/*</pattern>
</decorator>

Customizing Web Application Name

You can specify the name of your web application and the URL it's pointing to at the top of each page by editing the web/WEB-INF/jsp/_meta.jsp.

<meta name="webapp.name" content="[your webapp name here]" />
<meta name="webapp.url" content="[your webapp url here]" />

Customizing Navigation Menu and Breadcrumbs

You can add menu or sub menu items to the navigation menu tailored to each web application.  Likewise for breadcrumbs.  Simple edit the web/WEB-INF/jsp/_nav.jsp and web/WEB-INF/jsp/_crumbs.jsp files by adding more <ul> or <li>.  You can further tailored to each page if you wish.

To not show breadcrumbs, add the following to your web/WEB-INF/jsp/_meta.jsp

<meta name="display.crumbs" content="none" />

Customizing SSO Log Out URL

The default SSO log out URL is https://www.ucsd.edu.  If your web application needs a different URL, add the following to your web/WEB-INF/jsp/_meta.jsp. For example, the url can be https://uxt.ucsd.edu.

<meta name="logout.url" content="[your url here]" />

Customizing Feedback URL

The UXT feedback form captures the submitter's referring URL, user agent, IP address, and form fields such as name, email, and comment text.

The feedback URL format is: http://act.ucsd.edu/cwp/feedback/[form type]/[distribution list].

There are 4 form styles:

1. Basic: "Your Opinion Counts" - /tool
2. Help (used in TritonLink applications) -/help
3. FinancialLink: "Did You Get What You Wanted?" - /finlink
4. Mobile - /mobile

The default feedback URL is http://act.ucsd.edu/cwp/feedback/tool/apps. It uses the basic form style and routes submissions to both the ACT Help Desk and the TritonLink help desk. We recommend using a custom distribution list (lists can be nested, e.g., /tritonlink/registrar). Contact UXT to request a new distribution list, or to check for an existing distribution list.

To add a feedback link to your application, add the following to your web/WEB-INF/jsp/_meta.jsp. (You can also just use a mailto link.)

<meta name="feedback.url" content="[feedback URL or mailto://]" />

Customizing Search

The default decorators will have a search bar and the "This Site" option will default to a particular Google Search Appliance collection value for each different decorator.  You can customize if you want to show this search bar or not. 

To not show it, add the following to your web/WEB-INF/jsp/_meta.jsp

<meta name="display.search" content="none" />

Decorator Troubleshooting

If you are getting a blank screen instead of a decorated page, it typically means cross context is not enabled for your webapp.  Check your server's configuration setting.  The cross context simply means it's okay for this webapp to get the result from another webapp on this virtual host (in this case, the decorators webapp).