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
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
- 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:
| Decorator Name | Description |
|---|---|
| decorator | The default Blink decorator. |
| academic-student-prospective | Triton Link web applications for prospective students. |
| academic-student-current | Triton Link web applications for currently enrolled students. |
| academic-families | Triton Link web applications for student's parents and families. |
| academic | Triton Link web applications for staff. |
| employee | EmployeeLink web applications such as Timekeeping. |
| financial | Financial web applications including to Budget and Staff, Market Place, Payroll, Timekeeping, and Travel. |
| telecom | Telecom web applications. |
| research | Research web applications. |
| mobile | Mobile web applications. |
| iframe | Just content, for iframed web applications. |
Note that each decorator should contain the base line navigation menu items for each application family. Each web application has the ability to add additional navigation menu items or bread crumbs.
For a complete list of decorators, visit the decorators web application on our production server.
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:
- Basic: "Your Opinion Counts" -
/tool - Help (used in TritonLink applications) -
/help - FinancialLink: "Did You Get What You Wanted?" -
/finlink - 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).