Chrysalis allows you to control certain view page settings outside the logic of the page itself, in page configuration files. This allows developers to address certain concerns independently of the core view logic:

• Page Security: Who can access the pages.
• Page Templates: Controlling common page layout, such as headers, footers and sidebar menus.
• Page Messages: Useful for internationaling view pages.

Page configuration is located in the WEB-INF/classes/page_config/ file, and can be in one of two formats:

• WEB-INF/classes/page_config/chrysalis.xml: Configuration data in an XML file. This is the prefered format.
• WEB-INF/classes/page_config/chrysalis.properties: Configuration data in a Java properties file. This formats is for compatibility with the standard format for internationalized messages in Java.

This document gives most of its examples in the XML format. The properties format is discussed at a section towards the end.

Page configuration is hierarchical, and configuration values can be set globally, for a given directory, or for a specific page. For any given page, the most specific configuration settings are used:

1. Page-specific values have the most precedence.
2. If there are no page-specific values, the directory-specific value is used, moving up the directory hierarchy.
3. If there are no directory-specific values, the global value is used.
4. If no value is specified anywhere for any particular configuration value, then a default value is used.

<config>
  <!-- ***** Global settings ***** -->
  <page-template>/template.jsp</page-template>
  <security login="/login.jsp" encryption="NEVER" />

  <!-- ***** Directory-specific settings ***** -->
  <directory name="directory" page-template="/directory-template.jsp">
    <security encryption="ALWAYS" roles="admin" />

    <!-- ***** Page-specific settings ***** -->
    <page name="page" page-template="/page-specific-template.jsp">
      <security encryption="AS_REQUESTED" />
    </page>
  </directory>
</config>

For example, the "directory/page.jsp" page would have the following settings given the configuration file above:

• security encryption: "AS_REQUESTED", page-specific.
• page template: "/page-specific-template.jsp".
• security roles: "admin", as defined for the directory.
• security login: "/login.jsp", as defined globally.

For deeper directory structures, settings for sub-directories take precedence over settings for their parent directories.

For pages, the file extension (".jsp") should be omitted from the page name. The page name of the "index.jsp" file should simply be "index". This simplifies support of alternate view URLs (".view").

Chrysalis supports a permissions-based security system, based on user roles. Chrysalis does have a predefined set of roles; the development team can define a set of user roles appropriate to their application: "admin", "account-manager" and so forth.

Access restrictions to Chrysalis view pages can be set in one of two ways:

• Using the J2EE standard security settings in the web.xml configuration file.
• Custom security in the page configuration file.

The development team should choose one of these security strategies, depending on the application's needs. This document only discusses Chrysalis custom security settings; the J2EE standard settings are described in the J2EE specifications and any number of books.

Chrysalis page-based security is configured in the WEB-INF/classes/page_config/chrysalis.xml configuration file, using <security> tags. There are three security settings:

• login: The login page.
• roles: The required roles for the page. Pages with no roles are not secured, and can be accessed by anyone.
• encryption: The encryption requirements, "ALWAYS", "AS_REQUESTED" or "NEVER".

The settings be specified globally, for a directory or for a specific page. The most specific values are used.

<config>
  <!-- ***** Global settings ***** -->
  <security login="/login.jsp" encryption="NEVER" />

  <!-- ***** Directory-specific settings ***** -->
  <directory name="directory">
    <security encryption="ALWAYS" roles="admin" />

    <!-- ***** Page-specific settings ***** -->
    <page name="page">
      <security encryption="AS_REQUESTED" />
    </page>
  </directory>
</config>

If a given page or directory does not specific a given security setting, it uses the setting of its parent directory or the global value. For example, since the "page.jsp" does not specify any security roles, it uses the roles for its directory: "admin".

If for some reason you wanted to specify that a page within a secured directory is not secure, you would need to explicitly assign it an empty list of roles. This is useful if you want to secure everything except for your login page itself:

<config>
  <!-- **** Login and encryption required by default -->
  <security login="/login.jsp" roles="AUTHENTICATED" encryption="ALWAYS" />

  <page name="login">
    <!-- No login required; still needs encryption. -->
    <security roles="" />
  </page>
</config>

A page without any specified roles is not secured. Anyone can access that page, no login required.

Pages with a list of required roles is secured. If a user goes to a page with a list of roles, several things can happen:

1. If the user is logged in, and belongs to any one of the specified roles, they can access the page.
2. If the user is not logged in, they are redirected to the specified login page. The original page is stored in a "redirect" parameter, so that the user can be sent back to the desired location after login.
3. If the user is logged in, but does not belong to any of the listed roles, the user is denied access and an error message is generated.
4. If the user is not logged in, but Chrysalis cannot determine the login page (there is no "login" configuration setting), the user is denied access and an error message is generated.

Note that, like the J2EE specifications, roles are not additive. If you specify multiple roles, the user can belong to any of these roles, and gain access. Therefore, more roles gives access to more people, not fewer people.

Chrysalis has one special "AUTHENTICATED" role. If a page has "AUTHENTICATED" as one of its roles, then the user simply needs to login to gain access to the page; it does not matter what roles the user belongs to.

Encryption (SSL) requirements are configured separately from the rest of the security settings. You have three options for encryption:

• ALWAYS: SSL is required to access this resource. If the user accesses the page without SSL, they are redirected to the same page with an "https://" URL, to activate SSL.
• AS_REQUESTED: The presence of SSL is unimportant. The user can access the page with or without SSL, as requested.
• NEVER: SSL access is forbidden. If the user accesses the page with SSL, they are redirected to the same page with an "http://" URL, to deactivate SSL.

At first glance, the "NEVER" setting may seem pointless, but many commercial sites prefer that the majority of the site (such as catalog browsing pages) not be encrypted, to improve performance. The "NEVER" encryption setting is useful in those cases.

If there is no encryption setting specified for a page, the default value depends on whether the page is secured or not:

• Non-secured pages (those without roles) default to "AS_REQUESTED".
• Secured pages (those with roles) default to "ALWAYS".

Chrysalis uses templates to define global page structures for a web application such as headers, footers, menus and stylesheets. Chrysalis allows you to define page templates in the page configuration file: WEB-INF/classes/page_config/chrysalis.xml. This same file is also used to store message strings for internationalization. Messages and templates can be defined at various levels:

<config>
  <!-- ***** Global settings ***** -->
  <page-template>/template.jsp</page-template>
  <message name="example-message">Example global message</message>

  <!-- ***** Directory-specific settings ***** -->
  <directory name="dir" page-template="/template2.jsp">
    <message name="example-message">Example message for a directory</message>

    <!-- ***** Page-specific settings ***** -->
    <page name="page" page-template="/template3.jsp">
      <message name="example-message">Example message for a page</message>
    </page>
  </directory>
</config>

The global template must be assigned in the <page-template> tag at the root of the configuration XML file. Templates for specific directories and pages must be assigned as page-template attributes of the appropriate <directory> or <page> tags. For page names, the file extension (".jsp") should be omitted.

Chrysalis will use the most specific message or template possible.

1. If a template is defined for a specific page, that page's template will be used.
2. If a template is not defined for the page, but is defined for the page's directory, the directory template will be used.
3. If no template is defined for the page's directory, the global template will be used.
4. If no template is defined anywhere, the Chrysalis will invoke the page directly (without a template).

Similarly, messages are assigned to a configuration property with that message's name. Messages for specific directories and pages must also be qualified with the directory or page path. Again, Chrysalis will use the most specific message possible.

Chrysalis templates are defined as JSP pages, with a special <ji18n:includeBody> tag to indicate where the main page content should be inserted. Messages can be inserted into the template using <ji18n:message> tags.

<!-- /template.jsp -->
<html>
<head>
  <title><ji18n:message name="page-title" /></title>
</head>
<body>

<h1><ji18n:message name="page-title" /></h1>

<ji18n:includeBody />

<p>Copyright 2003, Example-CO. All rights reserved.</h1>

</body>
</html>

The page's content will be inserted in place of the <ji18n:includeBody> tag. For example, suppose the target page was example1.jsp:

<!-- /example1.jsp -->
<p>This is the inserted content of Example 1.</p>

Suppose that WEB-INF/classes/page_config/chrysalis.xml has the following information:

<config>
  <page-template>/template.jsp</page-template>
  <message name="page-title">Global Page Title</message>
<config>

The assembled page displayed in the user's browser will be:

<!-- Assembled page -->
<html>
<head>
  <!-- Inserted "page-title" message -->
  <title>Global Page Title</title>
</head>
<body>

<h1>Global Page Title</h1>

<!-- Inserted "example1.jsp" body -->
<p>This is the inserted content of Example 1.</p>

<p>Copyright 2003, Example-CO. All rights reserved.</h1>

</body>
</html>

Some care must be taken with URLs in the template and include pages for elements such as images, links, etc. In particular, relative URLs will be resolved relative to the URL of the base page, not the template. This is because these URLs are resolved by the browser, which only knows of the base page's URL:

<h1>Header
<!-- Resolved from the page location, not the template location -->
<img src="../logo.gif">
<ji18n:includeBody />
<h6>Footer</h6>

This issue can be avoided by using site-relative (with a leading "/") rather than page relative links. These site-relative links must include the web application's context path, if any. For example, if the context path were "myapp":

<h1>Header
<img src="/myapp/images/logo.gif">
<ji18n:includeBody />
<h6>Footer</h6>

The <jhtml:link> and <ji18n:url> tags automatically prepend the correct context path to URLs and can be used to build applications independent of their context path.

<h1>Header
<img src="<ji18n:url value='/images/logo.gif' />">
<ji18n:includeBody />
<h6>Footer</h6>

Messages can be inserted into a page or its template using the <ji18n:message />. Messages are retrieved from the page configuration based on the message name. For example the <ji18n:message name="page-title" /> tag is replaced by the "page-title" message from the page_config/chrysalis.xml file.

<config>
  <page-template>/template.jsp</page-template>
  <message name="page-title">Global Page Title</message>
<config>

Message replacement always uses the most specific message possible. Consider a second example page, example2.jsp.

<config>
  <page-template>/template.jsp</page-template>
  <message name="page-title">Global Page Title</message>
  
  <page name="example2">
    <message name="page-title">Title for Example 2</message>
  </page>
<config>

The "page-title" message for example2.jsp will use the page-specific message "Title for Example 2". Other pages without page-specific messages will use the global message: "Global Page Title".

Message properties can be defined at the global, directory and page level. This allows you to define a generic text insertion point in your templates, but have different values inserted for different pages, based on the values in page_config/chrysalis.xml file. You could therefore have a different page title inserted for each specific page in the web application.

In addition to messages and the page body insertion point (<ji18n:includeBody />), you can define other inserted content based on messages in the page configuration, using <ji18n:include /> tags. Consider the following template:

<!-- /template.jsp -->
<html>
<head><title><ji18n:message name="page-title" /></title></head>
<body>
<!-- Table to define the layout for the template -->
<table>
  <tr><td colspan="2><ji18n:include name="page-header" /></td></tr>
  <tr>
    <td><ji18n:include name="page-menu" /></td>
    <td><ji18n:includeBody /></td>
  </tr>
  <tr><td colspan="2><ji18n:include name="page-footer" /></td></tr>
</table>
</body>
</html>

The <ji18n:includeBody /> tag will be replaced with the main page's content, as usual. The various other include tags will insert content from the pages specified in the page configuration:

<!-- /WEB-INF/classes/page_config/chrysalis.xml -->
<config>
  <page-template>/template.jsp</page-template>
  <message name="page-title">Global Page Title</message>
  <message name="page-header">/global-header.jsp</message>
  <message name="page-menu">/global-menu.jsp</message>
  <message name="page-footer">/global-footer.jsp</message>
<config>

Different directory- or page-specific insertions can be defined. Based on the following configuration, the "example3.jsp" page will use the global page-header and page-footer, but its own custom page-title and page-menu.

<!-- /WEB-INF/classes/page_config/chrysalis.xml -->
<config>
  <page-template>/template.jsp</page-template>
  <message name="page-title">Global Page Title</message>
  <message name="page-header">/global-header.jsp</message>
  <message name="page-menu">/global-menu.jsp</message>
  <message name="page-footer">/global-footer.jsp</message>

  <page name="example3">
    <message name="page-title">Page Title for Example 3</message>
    <message name="page-menu">/example3-menu.jsp</message>
  </page>
<config>

Inserted pages themselves can also use messages, whose values are also determined by the configuration of the targeted page:

<!-- Inserted page: /global-header.jsp -->
<h1><ji18n:message name="page-title" /></h1>

In the inserted header page above, the page-title will be "Page Title for Example 3" in the example3.jsp, and "Global Page Title" for pages without a page-specific page title.

Another use of the <ji18n:message> is to support internationalization. Messages for different languages can be put into language-specific page configuration files. The file names are based on the same conventions used for Java's ResourceBundle: with language and country suffixes:

• English: page_config/chrysalis_en.xml
• French: page_config/chrysalis_fr.xml
• German (Deutsch): page_config/chrysalis_de.xml

The language specific files can include alternate versions of messages for other languages.

<!-- /WEB-INF/classes/page_config/chrysalis_fr.xml -->
<config>
  <message name="page-title">Le Titre Global de Page</message>
  
  <page name="example3">
    <message name="page-title">Le Titre de Page par Exemple 3</message>
  <page>
<config>

The message that is displayed is determined by the user's locale. In general, it is responsiblity of the Java Developers and Chrysalis controllers to set the user locale. The locale can be controlled by using the org.chwf.i18n.UserLocale Java class.

In theory, includes and templates can also be customized for different languages, but this is unusual. Typically, only messages will be internationalized. Message tags can be used in the main JSP, template pages and included pages to generate language-specific labels and messages.

The Chrysalis template and message system is extremely flexible.

• Template pages can be used to define the overall site layout.
• Includes tags can be used to define page sections that can be customized for different sections of the site (such as context-sensitive menus).
• Message tags can be used to define insertion points for page- and language-specific messages. Messages can be used in the template, any includes and the main pages themselves.
• All of these values can be defined at the global, directory or page level.

Ideally, the entire site should use a single template. Layouts can be defined using HTML tables or frames. Includes can be used to define customizable page sections, and messages can be used for page-specific data like titles.

Chrysalis supports some alternative configuration options:

• Properties-Based Configuration: Using Java ".properties" files.
• Configuration Per Directory: Allowing configuration files to specified on a directory-by-directory basis, for very large applications.

Chrysalis page configuration can be done with Java-style ".properties" files. Properties files organized data into "name=values" pairs. Chrysalis messages should be in the format "message-name=message-value".

# /WEB-INF/classes/page_config/chrysalis.properties
page-title=Global Page Title
page-header=/global-header.jsp
page-menu=/global-menu.jsp
page-footer=/global-footer.jsp

Directory- or page-specific messages should be prefixed with their path, with "/" replace by "." and page file extension omitted. For example, the "page-title" for the directory/example.jsp would be set:

directory.example.page-title=Global Page Title

Templates and security values can be set with the following special property names (prefixed by directory/page names, as necessary).

• page-template
• security.login
• security.roles
• security.encryption

If both chrysalis.properties and chrysalis.xml files are present, the XML file takes precedence. If you do use a properties file, you should probably only use it for messages. Other configuration settings should be defined in the XML file.

For very large applications with many JSP, it can be impractical to use one global page configuration file. You can break the "chrysalis.xml" file down into smaller configuration files, organized by directory.

To use directory-based configuration, you need to create a directory structure in the WEB-INF/classes/page_config/ directory that matches the directory structure of your view pages:

Directory-specific configuration files should only contain data for pages and sub-directories within that directory. The "root" of the directory-specific configuration file is that directory, and that directory name should be omitted from any paths in that configuration file. Global settings in the directory-specific configuration apply to that directory, not the entire application.

You can mix-and-match directory-specific configuration data and global configuration data. One useful technique is to organize your development teams and configuration by directory during development, and merge them into a single global configuration file for production and maintenance. XSLT can be used to automate this merge process.

If there is a conflict in global and directory-specific configuration files, the directory-specific configuration value is used. The rules is always "the most specific configuration value take precedence". If you want to ensure that only global configuration is used, be sure to delete all directory-specific configuration files.

This technique also works for properties-based configuration, but the merge operations become much more difficult. We recommend that you use XML for all directory-specific configuration files.