This guide is for web developers using the Chrysalis framework. By "web developers", we mean specialists in browser-based technologies, such as HTML, JavaScript, and Cascading Style Sheets. Web developers are responsible for producing page views for a Chrysalis application, each page appearing as a new screen in the user's web browser.

The Chrysalis framework assumes that web developers are part of a larger team, including specialists in other areas. At minimum, the development team must also include Java developers, who are responsible for creating server-side Java components that will process data entered into the application. Large teams may also include project managers, system architects, business analysts, database adminstrators and others. The precise titles assigned to the team members will vary from one organization to the next.

The Chrysalis framework is built around the "Model-View-Controller" pattern of application development. System components are broken up into three groups:

• The Model represents application data. The model consists of groups of business objects that can be manipulated by the application. This data is usually stored in some permanent data store, such as a relational database like DB2, SQLServer or Oracle.
• The View displays application data in web pages. Views in Chrysalis are created using JSP (Java Server Pages) technology. JSP are mostly standard HTML syntax, plus a few specialized tags.
• The Controllers are special command components that mediate between the View and the Model. Before a View can interact with the business objects in the Model, it must first invoke a controller.

Chrysalis development divides responsibilities as follows:

• Java developers are responsible for the Controller and the Model components.
• Web developers are responsible for the View components.

The View JSP created by web developers will interact with both controllers and business objects in the model. Thus, web developers need a basic understanding of how controller and model components work, even though these components will be created by other team members.

Model components are business objects. Business objects are software components that represents business concepts. Each business object has a set of data values associated with it, called the properties of that object. These properties can be both simple values and collections of other business objects. In Java, these business objects are sometimes called "JavaBeans".

The sample application for Chrysalis has a simple object model with three types of objects:

• Item - An item or product in a catalog.
• Order - A customer order.
• LineItem - An item in an order.

The properties for these items are as follows:

In Java (and Chrysalis), the names of object types and properties are case sensitive and cannot include spaces. By convention, the names of object types begin with a capital letter, and the names of properties begin with a lowercase letter. Multiple words are generally indicated by capital letters ("camel case").

Each application will have a different set of business objects with different properties. It is the responsibility of Java developers to create the business objects and provide documentation listing their properties.

Controller components control business objects. Controller do two basic things:

• Load data - Controllers load business object data into View pages.
• Update data - Controllers process HTML form information and save them in business objects (and ultimately to the permanent data store).

Controllers manipulate business object data through two mechanisms:

• Properties (Initializers) - Controller properties that load data. Controller properties are also called initializers because they initialize business object data.
• Methods (Commands) - Operations that update data in some way. Controller methods are also called commands, because they form the command and control system for a Chrysalis application.

The sample application for Chrysalis has two controllers:

• Cart - A controller that holds items in user's shopping cart and creates orders.
• Catalog - A controller for updating catalog data.

The properties and methods of these controllers are as follows:

Catalog Controller

Cart Controller

[*] Indicates a multi-value parameter.

Controller methods are invoked using a Command URL. For example, the Command URL for the addItem method of the Cart controller would look like:

Cart.addItem.cmd?itemId=296

Each application will have a different set of controllers. It is the responsibility of Java developers to create the controllers and provide documentation listing their properties, methods and parameters. The mechanisms for invoking controller methods is discussed in more detail below.

The view components are the primary responsibility of web developers. Views are written using JSP (Java Server Pages) technology. Despite its name, developers do not need to know any Java to create JSP. Chrysalis JSP are mostly HTML code, with some custom tags to interact with controllers and business objects.

The remainder of this document discusses the creation of Chrysalis views.

JSP pages use the ".jsp" file extension instead of ".html". The source code in a Chrysalis view page will consist of a mixture of standard HTML and custom Chrysalis tags to print information about business objects. The example below creates an HTML form that is pre-populated with information for a particular Item business object.

<jutil:use var="item" controller="Catalog" />

<h1>Edit Catalog Item</h1>

<jhtml:form action="Catalog.editItem.cmd">
<table>
  <tr>
    <td><jhtml:label property="itemId" /></td>
    <td><jhtml:input property="itemId" /></td>
  </tr>
  <tr>
    <td><jhtml:label property="name" /></td>
    <td><jhtml:input property="name" /></td>
  </tr>
  <tr>
    <td><jhtml:label property="stock" /></td>
    <td><jhtml:input property="stock" /></td>
  </tr>
  <tr>
    <td><jhtml:label property="price" /></td>
    <td><jhtml:input property="price" /></td>
  </tr>
  <tr>
    <td><jhtml:label property="startDate" /></td>
    <td><jhtml:input property="startDate" /></td>
  </tr>
  <tr>
    <td colspan="2"><input type="submit" value="Submit"></td>
  </tr>
</table>
</jhtml:form>

A more compact form of the above is:

<jutil:use var="item" controller="Catalog" />

<h1>Edit Catalog Item</h1>

<jhtml:form action="Catalog.editItem.cmd">
<table>
  <jhtml:field property="itemId" />
  <jhtml:field property="name" />
  <jhtml:field property="stock" />
  <jhtml:field property="price" />
  <jhtml:field property="startDate" />
  <tr><td colspan="2"><input type="submit" value="Submit"></td></tr>
</table>
</jhtml:form>

A typical Chrysalis view JSP will do the following:

1. Retrieve business objects from a controller via a <jutil:use> tag.
2. Print object data to the screen.
3. Use Command URLs to target controller methods that will process data entered by the user.

Most view pages in Chrysalis will display information about business objects. Before they can do so, the business object must be loaded into the page. The standard way of loading business data is to retrieve a property value from a controller via a <jutil:use> tag.

<jutil:use var="order" controller="Cart" property="order"/>

The object retrieved from the controller is stored in a variable whose name is specified by the var attribute. You can reference the object by its name in the object attribute of other tags in the same page.

<jutil:use var="order" controller="Cart" property="order"/>
Item name: <jutil:print object="order" property="status"/>

In many cases, tag attributes are optional. For example, with the <jutil:use>, the property attribute is optional if it matches the value of the var attribute. The object attribute is always optional; if omitted, it defaults to the last object defined. The above tag logic is equivalent to the following:

<jutil:use var="order" controller="Cart"/>
Item name: <jutil:print property="status"/>

The objects available from a particular controller are defined by that controller's properties (also called object initializers). Some controller properties require special request parameters before they can load object data into memory. For example, the item property of the Catalog controller requires a itemId web parameter in order to know which item to load. In this case, the parameter values can be appended to the page's URL when invoking that page:

showItem.jsp?itemId=427

Once an object has been loaded into memory, other custom tags can be use to print information about that object. The example below prints out all the data for a single item object.

<jutil:use var="item" controller="Catalog" />

<h2>Catalog Item</h2>

<table border="1">
  <tr>
    <td><jhtml:label property="itemId" />: </td>
    <td><jutil:print property="itemId" /></td>
  </tr>
  <tr>
    <td><jhtml:label property="name" />: </td>
    <td><jutil:print property="name" /></td>
  </tr>
  <tr>
    <td><jhtml:label property="stock" />: </td>
    <td><jutil:print property="stock" /></td>
  </tr>
  <tr>
    <td><jhtml:label property="price" />: </td>
    <td><jutil:print property="price" /></td>
  </tr>
  <tr>
    <td><jhtml:label property="startDate" />: </td>
    <td><jutil:print property="startDate" /></td>
  </tr>
</table>

Other tags can print out other kinds of information. Consult the Tag Library Documentation for more details.

Some controller and object properties will be collections of other business objects. You can use the <jutil:forEach> to loop through all the objects in a collection to print out the information for each one.

<jutil:use var="itemList" controller="Catalog" />

<h2>Catalog</h2>

<table border="1" width="100%">
  <tr>
    <th>Item</th>
    <th>Stock</th>
    <th>Price</th>
  </tr>
<jutil:forEach var="item" collection="itemList">
  <tr>
    <td><jutil:print property="name" /></td>
    <td><jutil:print property="stock" /></td>
    <td><jutil:print property="price" /></td>
  </tr>
</jutil:forEach>
</table>

One of the major functions of view pages is to gather information from the user so that it can be passed to a controller method. The controller method will then save the information in some business object. The method is specified by:

• The controller name
• The method name
• The command extension (*.cmd)

This combination of information forms the Command URL. For example, the Command URL to target the Cart controller's addItem method is:

Cart.addItem.cmd

Controllers can be targeted in one of two ways:

1. Forms (with input elements)
2. Links (with web parameters)

Forms specify the Command URL in their action attribute, and must have an input element (form field) for each method parameter. For example, a form targeting the Catalog controller's editItem method (which has five method parameters) might look like:

<jutil:use var="item" controller="Catalog" />

<h1>Edit Catalog Item</h1>

<jhtml:form action="Catalog.editItem.cmd">
<table>
  <jhtml:field property="itemId" />
  <jhtml:field property="name" />
  <jhtml:field property="stock" />
  <jhtml:field property="price" />
  <jhtml:field property="startDate" />
  <tr><td colspan="2"><input type="submit" value="Submit"></td></tr>
</table>
</jhtml:form>

Links specify the target controller in their href attribute, and must have a parameter for each method parameter. These links are equivalent to the HTML <a> tag. A link targeting the Cart controller's addItem method might look like:

<jutil:use var="item" controller="Catalog" />

<jhtml:link href="Cart.addItem.cmd">
  <jutil:param property="itemId" />
  Add to Cart
</jhtml:link>

When the user submits the form or clicks on the hyperlink, the data will be passed to the appropriate controller method.

Often view pages will have links that target other view pages. For example, the sample application has a home page that lists all the items in the catalog. It links to individual showItem.jsp pages that displays information for specific items.

<jutil:use var="itemList" controller="Catalog" />

<h2>Catalog</h2>

<table border="1" width="100%">
  <tr>
    <th>Item</th>
    <th>Stock</th>
    <th>Show item</th>
  </tr>
<jutil:forEach var="item" collection="itemList">
  <tr>
    <td><jutil:print property="name" /></td>
    <td><jutil:print property="stock" /></td>
    <td>
      <!-- LINK TO ANOTHER VIEW PAGE -->
      <jhtml:link href="showItem.jsp">
        <jutil:param property="itemId" />
        Show item
      </jhtml:link>
    </td>
  </tr>
</jutil:forEach>
</table>

As noted above, some view pages require parameters because the controller properties (or object initializers) they use require parameters. If this is the case, these parameters must be specified in the link.

The file extension for Chrysalis JavaServer Pages is always ".jsp". For technical reasons, however, URLs (links) to Chrysalis view pages in older servers cannot uses this extension in their links. If you need compatibility with these older server standards (Servlet 2.2), you must use ".view" instead of ".jsp" in the URLs linking to your view pages.

<jutil:use var="itemList" controller="Catalog" />

<h2>Catalog</h2>

<table border="1" width="100%">
  <tr>
    <th>Item</th>
    <th>Stock</th>
  </tr>
<jutil:forEach var="item" collection="itemList">
  <tr>
    <td><jutil:print property="name" /></td>
    <td><jutil:print property="stock" /></td>
    <td>
      <jhtml:link href="showItem.view">
        <jutil:param property="itemId" />
        Show item
      </jhtml:link>
    </td>
  </tr>
</jutil:forEach>
</table>

This change only appears in links. The file names (and server include syntax) continues to use the ".jsp" extension, even on older servers. Consult the Java developers to determine which URL extension is correct for your particular system.

There is a similar problem with index pages on older servers. If you have an index page of "index.jsp", the page will not resolve correctly, because it does not have the .view extension. You can trick the server into rendering your index page by creating a dummy index.view file in the same directory. The server will then correctly load the real index page, index.jsp.

It is possible to use HTML editor programs such as FrontPage or DreamWeaver with Chrysalis. Chrysalis custom tags were designed to resemble normal HTML as much as possible. You can produce an HTML page using an editor and then modify the page to insert the necessary custom Chrysalis tags.

The custom tag logic for Chrysalis is explained in greater detail in the Tag Library Documentation.

Although Chrysalis is relatively complete for common application functions, it cannot cover every possibility. It may be necessary to integrate additional view technologies to support specialized application needs. You have several options for integrating other view technologies:

• JSP Scripting
• Custom JSP Tags
• Third-Party Custom Tags

In general, it is the responsibility of the Java Developers to identify the best approach to solving a particular problem.

Java Server Pages allowing Java code to be directly embedded in JSP view pages using script tags: <% %>. Java is a powerful programming language, and it should be possible to solve nearly any issue with this approach.

Unfortunately, this approach means that Java code must be embedded directly into the view pages, which means that both web developers and Java developers must work with (and maintain) the view files. This increases maintenance costs.

JSP Scripting is not an effective long-term solution. It is ideal for patches and emergency fixes, however, because these solutions can generally be integrated quickly. Once the emergency fix is in place, the development team can evaluate how best to solve the problem in the long term.

Custom JSP Tags are a better long-term solution. Custom JSP tags are similar to the special Chrysalis tags. Java developers can create new tags that perform arbitrary functions. These custom tags can perform all the same logic as scripting, but separate the files maintained by the Java developers (the custom tag files) from those used by the Web Developers (the view pages using the new custom tags).

Application issues that were solved with scripting should eventually be upgraded to use custom tags instead. The Java Development team should take time and care to design the new custom tags for long-term use and expansion.

There are a large number of third-party custom tag libraries that address a variety of concerns. Using third-party custom tags is similar to using custom tags created by your own team, except that the tags are already complete. Since third-party custom tag libraries and Chrysalis view pages use the same underlying technology (JSP), they should be compatible.

Many of the existing third-party custom tag libraries are open-source products. An open source tag library has an additional advantage: if the library is close to what you need, but not an exact match, you can modify the code to customize it to your particular application.

Before creating a new custom tag library, the development team should do some research to determine if an existing library will address their needs. This is especially true of "generic" operations like XML manipulation, data caching and things of that nature.