Availability | Available in WebObjects 5.0 and later. |
A WOComponent bundle contains a representation of a WOComponent object and related objects that are loaded at runtime by WebObjects applications. WOComponent objects are fundamental to how dynamic content works in WebObjects. You use components to represent webpages or partial webpages generated by your website. Components are actually templates for generating HTML pages. Components are constructed from static and dynamic elements. You use dynamic elements to bind HTML counterparts to variables and methods in your component class.
A WOComponent bundle is a directory containing specific files. The name of the directory is the name of the component with a .wo suffix—for example, Main.wo is the directory name when Main is the name of the component. The WOComponent bundle contains the following files:
[componentName].java—contains the controllers and business logic needed to make the dynamic component work. This file is mandatory but does not reside in the bundle—it needs to be loaded by the application.
[componentName].html—contains markup text plus any webobject elements that are resolved at runtime.
[componentName].wod—contains bindings that map webobject elements and associated values to dynamic elements or custom components. This file is optional.
[componentName].woo—contains information that describes WODisplayGroup objects and other information for build tools such as text encodings. This file is optional if this information is covered in the Java file.
[componentName].api—used for validating bindings within a component—defines what bindings are mandatory. This file is optional and does not need to reside in the bundle.
The following sections describe the format of each of these types of files.
See WebObjects 5.4 Reference for more details on the corresponding WebObjects classes described in this document. See WebObjects Dynamic Elements Reference and WebObjects Extensions Reference for complete descriptions of dynamic elements that may be contained in WOComponent bundles. See WebObjects Web Applications Programming Guide for a description of web applications that use WOComponent bundles.
This bundle format is one of two types of formats used to represent a WOComponent—read “WOComponent HTML File Format” for a description of the HTML file format.
The Java file of a WOComponent bundle contains a WOComponent subclass that implements the controllers and business logic that makes the component work. This includes declarations of WODisplayGroup objects and other variables used to bind user interface elements to application objects. Typically, bindings are made directly to enterprise objects.
Listing 1 shows the Java file for a Main.wo component of a Direct to Web application that presents a login panel to the user. The Main class inherits from WOComponent and defines username and password instance variables that are bound to WebObjects elements in the corresponding WOD file show in Listing 3. The Java file also contains action methods such as defaultPage() and isAssistantCheckboxVisible() that can be bound to elements in the user interface.
Listing 1 Sample Main.java file
// Created by Direct to Web's Project Builder Wizard |
import com.webobjects.foundation.*; |
import com.webobjects.appserver.*; |
import com.webobjects.directtoweb.*; |
public class Main extends WOComponent { |
public String username; |
public String password; |
public boolean wantsWebAssistant = false; |
public Main(WOContext aContext) { |
super(aContext); |
} |
public WOComponent defaultPage() { |
if (isAssistantCheckboxVisible()) { |
D2W.factory().setWebAssistantEnabled(wantsWebAssistant); |
} |
return D2W.factory().defaultPage(session()); |
} |
public boolean isAssistantCheckboxVisible() { |
String s = System.getProperty("D2WWebAssistantEnabled"); |
return s == null || NSPropertyListSerialization.booleanForString(s); |
} |
} |
The HTML file inside a WOComponent bundle presents the syntactic structure of data content. It's a regular HTML document containing one special element called webobject. The webobject element has a single required attribute called name which corresponds to an entry in the WOD file.
A webobject element shares the same basic content models as HTML, namely inline and block. When a webobject element poses as a block level element such as a WOConditional element, it contains other elements. When a webobject element poses as an inline element such as a WOString element, it does not contain any other elements. It serves as a placeholder for that inline element.
Listing 2 shows an HTML file from the Main.wo component of a Direct to Web application containing several webobject elements for the Username and Password fields in a form.
Listing 2 Sample HTML file
<html> |
<head> |
<title>Direct to Web</title> |
</head> |
<body bgcolor="#ffffff"> |
<h1 align="center">Welcome to Direct to Web!</h1> |
<webobject name="LoginForm"> |
<center> |
<table border="2" cellpadding="4" cellspacing="2" bgcolor="#b0b0b0"> |
<tr> |
<td> |
<table border="0" cellpadding="2" cellspacing="0" bgcolor="#b0b0b0"> |
<tr> |
<th align="right">Username: </th> |
<td> |
<webobject name="UsernameField"></webobject> |
</td> |
</tr> |
<tr> |
<th align="right">Password: </th> |
<td> |
<webobject name="PasswordField"></webobject> |
</td> |
</tr> |
<webobject name="AssistantConditional"> |
<tr> |
<th align="center" colspan="2">Enable Assistant: |
<webobject name="LACheckbox"></webobject> |
</th> |
</tr> |
</webobject> |
<tr> |
<td colspan="2" align="center"><webobject name="LoginButton"></webobject> |
</td> |
</tr> |
</table> |
</td> |
</tr> |
</table> |
<p></p> |
<webobject name="DirectToWebPlaque"></webobject> |
</center> |
</webobject> |
</body> |
</htm> |
The WOD file contains bindings that map the named webobject elements declared in the HTML file to other WOComponent objects, dynamic elements, or variables or actions in the Java file.
Each webobject element contained in the HTML file must have a corresponding declaration construct in the WOD file formated as follows:
CDATA_NAME: ELEMENT_TYPE { |
CDATA_ATTRIBUTE_KEY = CDATA_ATTRIBUTE_VALUE; |
[CDATA_ATTRIBUTE_KEY = CDATA_ATTRIBUTE_VALUE; ...] |
} |
where CDATA_NAME must match the name attribute of the webobject element in the HTML file. The possible values for ELEMENT_TYPE and their corresponding CDATA_ATTRIBUTE_KEY and CDATA_ATTRIBUTE_VALUE values are described in WebObjects Dynamic Elements Reference and WebObjects Extensions Reference.
Listing 3 shows a WOD file from the Main.wo component of a Direct to Web application that binds the Username and Password fields to the corresponding username and password variables declared in the Java file. It also binds the submit button action to the defaultPage() method.
Listing 3 Sample WOD file
AssistantConditional: WOConditional { |
condition = isAssistantCheckboxVisible; |
} |
DirectToWebPlaque: WOImage { |
alt = "Direct to Web - WebObjects 4.5"; |
filename = "DTW.gif"; |
framework = "JavaDirectToWeb"; |
height = "49"; |
name = "Direct to Web - WebObjects 4.5"; |
width = "196"; |
} |
LACheckbox: WOCheckBox { |
checked = wantsWebAssistant; |
} |
LoginButton: WOSubmitButton { |
action = defaultPage; |
value = "Login"; |
} |
LoginForm: WOForm { |
} |
PasswordField: WOPasswordField { |
value = password; |
size = "16"; |
} |
UsernameField: WOTextField { |
value = username; |
size = "16"; |
} |
The WOO file contains information for tool developers such as the character encoding for the files within the bundle, WebObjects version information, and localization information. The file also contains information on objects that are referenced by the component. Typically, an object such as a WODisplayGroup definition reside in this file—represented as an item in an array that is the value for the variables key.
The format of a WOO file is as follows:
{ CDATA_ATTRIBUTE_KEY = CDATA_ATTRIBUTE_VALUE; [CDATA_ATTRIBUTE_KEY = CDATA_ATTRIBUTE_VALUE; ...] } |
where CDATA_ATTRIBUTE_KEY and CDATA_ATTRIBUTE_VALUE are key-value pairs.
Variables such as WODisplayGroup objects might appear in an array that is the value for the variables key. For example, Listing 4 declares a creatureDisplayGroup variable that is an instance of WODisplayGroup. This example is of the FolderViewPage.woo component in the WOInheritanceExample sample code located in /Developer/Examples/JavaWebObjects.
Listing 4 Sample WOO file
{ |
"WebObjects Release" = "WebObjects 5.0"; |
encoding = NSMacOSRomanStringEncoding; |
variables = { |
creatureDisplayGroup = { |
class = WODisplayGroup; |
dataSource = { |
class = EODatabaseDataSource; |
editingContext = session.defaultEditingContext; |
fetchSpecification = { |
class = EOFetchSpecification; |
entityName = Creature; |
fetchLimit = 0; |
isDeep = YES; |
}; |
}; |
formatForLikeQualifier = "%@*"; |
localKeys = (); |
numberOfObjectsPerBatch = 0; |
selectsFirstObjectAfterFetch = YES; |
sortOrdering = (); |
}; |
}; |
} |
The API file is used to validate bindings made between component objects—it defines the interface of a reusable component. It specifies whether an attribute is mandatory or read only, for example. Tools may use this API validation mechanism. The WebObjects runtime does not use the API files to validate bindings.
The API file has the following format:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> |
<wodefinitions> |
<wo class=[component class name] wocomponentcontent=[true/false]> |
<binding name=[binding name] defaults=[default value]"/> |
[more bindings] |
<validation message="[binding name of a settable value]"> |
<unsettable name=[binding name]/> |
</validation> |
</wo> |
</wodefinitions> |
Listing 5 shows an API file from the Main.wo component of a Direct to Web application.
Listing 5 Sample API file
<?xml version="1.0" encoding="macintosh" standalone="yes"?> |
<wodefinitions> |
<wo class="Main" wocomponentcontent="NO"> |
</wo> |
</wodefinitions> |
Last updated: 2008-11-19
