Direct to Web Components

Direct to Web provides nine types of Web pages to perform the tasks shown in Table 1. See Dynamically Generated Pages for more information about these tasks.

To render these pages, Direct to Web uses three types of components: Direct to Web templates, Direct to Web reusable components, and property-level components.

Direct to Web Templates

Direct to Web generates the task Web pages using instances of the D2WPage class (itself a descendent of the WOComponent class) called Direct to Web templates. A Direct to Web template defines the basic layout for the task’s user interface. Direct to Web includes 29 templates: nine for the Basic look, ten for the Neutral look, and ten for the WebObjects look. For more information about looks, see The Different Looks for WebObjects Applications. The Direct to Web templates are listed in Table 2-2.

Some Direct to Web templates perform multiple tasks. For example, an InspectPage template also edits. For some tasks, there are multiple Direct to Web templates in a given look that you can use. For example, you can use a ListPage, a PlainListPage, or a MasterDetailPage template to perform the list task.

Like any other WOComponent, a Direct to Web template has an HTML template (.html ) file and a bindings (.wod ) file. What differentiates a Direct to Web template from other components is that it resolves its bindings with the help of the Direct to Web framework at runtime.

Note that a Direct to Web template is different from a component’s HTML template (.html ) file: a Direct to Web template is a special type of component while an HTML template is a file containing the HTML code that defines a component’s appearance.

Direct to Web Reusable Components

Some Direct to Web templates can be viewed as implementing more than one task:

• A MasterDetailPage template consists of a select component at the top and an edit component at the bottom.

• An EditRelationshipPage template consists of a select component at the top and query, select, and edit components at the bottom.

Direct to Web displays these subcomponents with Direct to Web templates. For example, a NEUMasterDetailPage displays its select component using a NEUListPage and its edit component with a NEUInspectPage. However, the Direct to Web templates are not designed to be nested directly within other Direct to Web templates. To permit nesting, Direct to Web uses another type of component called a Direct to Web reusable component, which acts as an interface between the outer template and the inner template. There are five types of Direct to Web reusable components; they are listed in Table 2-3.

Table 2-4 shows how the reusable components are used in the Direct to Web templates containing multiple tasks. The remaining templates do not contain Direct to Web reusable components.

In addition to allowing the nesting of Direct to Web templates, Direct to Web reusable components can also be embedded in your own components; they are available on a palette in WebObjects Builder. See the Direct to Web Reference for more information about the individual Direct to Web reusable components.

Property-Level Components

Direct to Web uses property-level components to display, query, and edit individual properties of an entity. A property is an attribute or relationship of an entity. Direct to Web defines components for manipulating strings, dates, numbers, to-one relationships, to-many relationships, and other objects. For example, Table 2-5 lists some property-level components; these components work with numbers.

At runtime when a template displays a property, Direct to Web chooses which property-level component should display the property. The choice depends on the property’s data type and how you configure the application with the Web Assistant.

Direct to Web Component Organization

Figure 2-1 shows the components in an edit page for the Customer entity in the Neutral look, with only the attritubutes firstName, lastName, and agent showing. The top-level component is a Direct to Web template called NEUInspectPage.wo. It contains the project’s PageWrapper.wo component, which defines the overall layout of the page. The PageWrapper.wo component contains the MenuHeader.wo component, which defines the Direct to Web navigation menu. See The Structure of a Direct to Web Project for more information about PageWrapper.wo and MenuHeader.wo.

The PageWrapper.wo component content comes from the NEUInspectPage Direct to Web template. This content includes HTML input elements for the visible attributes of an entity. Each attribute appears in a separate property-level component that depends on the attribute’s type. The firstName and lastName attributes are displayed using D2WEditString components. The agent relationship displays using a D2WEditToOneFault component.

Pages with nested Direct to Web templates contain Direct to Web reusable components. Figure 2-2 shows a master detail page in the Neutral look. The NEUMasterDetailPage.wo Direct to Web template contains PageWrapper.wo which in turn, contains MenuHeader.wo. NEUMasterDetailPage.wo also contains two reusable components that act as interfaces to the templates they display: a D2WSelect component and a D2WEdit component. Each of these components is actually a WOSwitchComponent that displays a template—the D2WSelect component displays a NEUListPage Direct to Web template and the D2WEdit component displays a NEUInspectPage Direct to Web template.

The Direct to Web Context

As mentioned earlier, a Direct to Web template is rendered using runtime information about the entities it displays. To translate that information into something you can bind to the template’s dynamic elements, Direct to Web uses an instance of the D2WContext class called the Direct to Web context. This object has two functions: it maintains a state dictionary that holds the state of a Direct to Web template as it renders, and it provides values that you can bind directly to attributes of dynamic elements. Each instance of a Direct to Web template has an associated Direct to Web context.

Providing Binding Values

Each Direct to Web template has a Direct to Web context called d2wContext, which implements the EOKeyValueCoding interface. Thus you can bind directly to keys that the context responds to. For example, Listing 2-1 shows the bindings file for a Direct to Web template that displays the name of the entity.

Listing 2-1  Bindings file for a Direct to Web template

String1: WOString {

value = d2wContext.entity.name;

};

The Direct to Web context determines the values for the keys (d2wContext.entity.name for example) in one of three ways:

• it looks it up in its state dictionary

• it accesses application configuration information. (The Web Assistant is the primary way to modify the application configuration.)

• it derives values from the state and configuration information

Resolving Keys With the State Dictionary

The state dictionary contains the following entries:

Key	Description of Value
task	A string representing the current task.
entity	An EOEntity representing the current entity.
propertyKey	A string representing the key of the current property.
attribute	An EOAttribute representing the current attribute (null if the current property is a relationship.)
relationship	An EORelationship representing the current relationship (null if the current property is an attribute.)

If the dictionary contains the key the template needs, the Direct to Web context resolves the key by returning the value in the dictionary. Otherwise the Direct to Web context resolves the key using one of the other ways.

Resolving Keys With the Application Configuration

Some keys can only be resolved using the application configuration information, which is stored as a database of rules. For example, a rule to determine the property-level component for the dateReleased attribute might be “If the task is ‘edit’, the entity name is ‘Customer’, and the property key is ‘lastName’ then the value for the componentName key is ‘D2WEditString’.”

The Direct to Web context uses the rule engine to resolve keys that aren’t in its dictionary. Figure 2-3 shows how the rule engine relates to the Direct to Web context. The Rule System contains detailed information on how the rule engine works.

Resolving Derived Values

The rule engine also provides objects that have methods that derive values from the Direct to Web context’s state dictionary. An example of a derived value is the name displayed for a property: a method converts a property name like lastName to a display string “Last Name”. Using derived values is discussed in more detail in The Rule System.

The Direct to Web Factory

Direct to Web pages are created by the Direct to Web factory, an instance of the D2W class (see Figure 2-3). This object creates pages by instantiating a Direct to Web context and a Direct to Web template for each page. Rendering a Direct to Web Page: An Example, shows how the factory generates a query page.

Rendering a Direct to Web Page: An Example

This section describes how the components, the Direct to Web context, and the Direct to Web factory interact while creating and rendering a query page for the Customer entity. This example begins with the user viewing a query all page in the Basic look and clicking a hyperlink labeled “more..” in the Customer row, which links to the query page. The query all page is rendered using a BASQueryAllEntitiesPage.wo template.

publicWOComponent showRegularQueryAction()

{

    QueryPageInterface newQueryPage= D2W.factory().queryPageForEntityNamed

        (entity().name(), session());

    return (WOComponent)newQueryPage;

}

((look= “BasicLook”) and (task = “query”)) => pageName = “BASQueryPage”

*true* => look = “BasicLook”

Rendering the Direct to Web Template

Now the WebObjects framework begins to render the template. Listing 2-4 shows excerpts from the HTML template for the BASQueryPage Direct to Web template; the listed portions of the file are discussed in this example. Listing 2-5 shows the corresponding sections in the bindings file.

First, the Direct to Web template displays the page wrapper. To do so, it needs to resolve the WOComponentName binding for the PageWrapper WOSwitchComponent (see Listing 2-5). A WOSwitchComponent displays a nested component that has the name specified by its WOComponentName binding, which in this case is bound to the d2wContext.pageWrapperName key. Since the Direct to Web Context can’t find it in its dictionary, it invokes the rule engine to resolve the key, which fires the rule:

*true*=> pageWrapperName = “PageWrapper”

The Direct to Web context returns “PageWrapper” for the WOComponentName binding and the WOSwitchComponent displays the application’s PageWrapper.wo component. The template continues to render, resolving its keys in a similar way.

Listing 2-4  BASQueryPage.html excerpts

<WEBOBJECTNAME=PageWrapper>

.

.

    <WEBOBJECT NAME=ResourceRepetition>

.

.

        ... <WEBOBJECT NAME=ResourceLabel>:... </WEBOBJECT>

.

.

        <WEBOBJECT NAME=ResourceInputRepresentation></WEBOBJECT>

.

.

    </WEBOBJECT>

</WEBOBJECT>

Listing 2-5  BASQueryPage.wod excerpts

PageWrapper:WOSwitchComponent {

    WOComponentName = pageWrapperName;

    ...

}

ResourceInputRepresentation:WOSwitchComponent {

    WOComponentName = d2wContext.componentName;

    ...

}

ResourceLabel: WOString {

    ...

    value = d2wContext.displayNameForProperty;

}

ResourceRepetition: WORepetition{

    ...

    item = d2wContext.propertyKey;

    list = d2wContext.displayPropertyKeys;

}

Setting the Property Key

When the template begins to render the query fields for the entity’s attributes and relationships (like the agent and contact info) it encounters the WORepetition labeled ResourceRepetition. See Listing 2-4 and Listing 2-5. The WORepetition’s list attribute is bound to d2wContext.displayPropertyKeys. Since displayPropertyKeys is not in its dictionary, the Direct to Web context resolves the key using the rule engine, which causes the following rule to fire:

*true*=> displayPropertyKeys = “defaultPropertyKeysFromEntity”

The defaultPropertyKeysFromEntity key refers to a method that derives a value based on the Direct to Web context’s dictionary. See The Rule System for more information about the how derived values are handled. The defaultPropertyKeysFromEntity method returns an NSArray containing the Customer entity’s property keys, which resolves the WORepetition’s list binding.

As the repetition iterates, it sets the item attribute for each of the objects in the list. The first object is the string “agent”. Since item is bound to d2wContext.propertyKey, the Direct to Web context sets the value for propertyKey in its dictionary to “agent”. At the same time, it sets the value for the attribute key to null and the value for the relationship key to the agent EORelationship, since a Customer’s agent property is a relationship and not an attribute. Now the Direct to Web Context dictionary contains the information listed in Table 2-7.

Resolving Keys That Depend on the Property

As the WebObjects framework continues to render the ResourceRepetition WORepetition, it encounters the ResourceLabel WOString. See Listing 2-4. The value attribute is bound to d2wContext.displayNameForProperty. This causes the following rule to fire:

*true*=> displayNameForProperty = “defaultDisplayNameForProperty”

The derived value for the defaultDisplayNameForProperty key is implemented by a method that capitalizes the property key in the context’s dictionary, inserts spaces between words with mixed case, and returns the resulting name “Agent”, which the template displays.

Next, the template displays the property-level component that queries for the agent relationship. Since this component is known only at runtime, the Direct to Web template displays it with a WOSwitchComponent called ResourceInputRepresentation. See Listing 2-5. The WOSwitchComponent’s WOComponentName attribute is bound to d2wContext.componentName. When the context evaluates this key, the following rule fires:

((task= “query”) and (propertyType = “r”)

    and (not (relationship.isToMany= (java.math.BigDecimal)”1”))

    => componentName = “D2WQueryToOneField”

Thus the WOSwitchComponent displays a D2WQueryToOneField.wo reusable component from the DirectToWeb framework.

The rest of the template renders in a similar way.

The Rule System

Direct to Web stores its configuration in the form of rules. The following is an example of a rule:

((task= “query”) and (not (attribute = null))

    and (attribute.valueClassName= “java.lang.String”)

    => componentName = “D2WQueryStringComponent”

A rule consists of five parts, of which three are shown in the example:

• a left-hand side, which is separated from the right-hand side by “=>”

  The left-hand side specifies a condition that must be true for the rule to be a candidate to fire. In this case, the task must be “query”, the attribute must not be null and its value must be a Java String.

• a right-hand-side key (componentName in this case)

  The right-hand-side key must match the key the Direct to Web context is seeking for the rule to be a candidate to fire.

• a right-hand-side value (”D2WQueryStringComponent” in this case)

  The right-hand-side value specifies the value for the right-hand-side key when the rule fires. It can be a constant value (as in this case) or a value computed by a method.

• a priority

  The priority helps Direct to Web decide which rule should fire when there are several candidates. See Deciding Which Candidate Should Fire for more information about the rule priority.

• an assignment class specifier

  The assignment class sets the value for the right-hand-side key when the rule fires. The default assignment class, Assignment, defined in the Direct to Web framework, assigns a constant value like “D2WQueryStringComponent”. When the right-hand-side value is derived using a method, the assignment class specifies a class that contains the method.

*true*=> componentName = “D2WUneditable”

(task = “inspect”) =>componentName = “D2WDisplayString”

((task = “inspect”) and

    (attribute.valueClassName= “com.webobjects.foundation.NSTimestamp”))

    => componentName = “D2WDisplayDate”

((look= “BasicLook”) and (task = “query”)) => pageName = “BASQueryPage”

*true*=> look = “BasicLook”

((task= “edit”) and (entity.name = “Customer”)

    and (propertyKey = “agent”))

    => componentName = “D2WEditToOneRelationship”

*true*=> look = “NeutralLook”

((task= “list”) and (entity = “Listing”) and (session.user.accessLevel= 1))

    => pageName = “AgentListListing”

((task = “list”) and (entity= “Listing”) and (session.user.accessLevel = 3))

    => pageName = “CustomerListListing”