Instruction Manual

ManualsBrandsApple ManualsSoftwareWebObjects 3.5 Tools And Techniques

WEBOBJECTS

TOOLS AND TECHNIQUES

Summary of content (88 pages)

PAGE 1
WEBOBJECTS TOOLS AND TECHNIQUES
PAGE 2
Apple,NeXT, and the publishers have tried to make the information contained in this manual as accurate and reliable as possible, but assume no responsibility for errors or omissions. They disclaim any warranty of any kind, whether express or implied, as to any matter whatsoever relating to this manual, including without limitation the merchantability or ﬁtness for any particular purpose.
PAGE 3
Contents
PAGE 4
PAGE 5
Table of Contents Contents iii Editing With WebObjects Builder 31 Setting Up WebObjects Applications 7 Introduction 33 The Component Window 33 The WebObjects Builder Toolbar 34 Introduction 9 Creating WebObjects Application Projects 9 Editing Modes 34 Choosing Assistance 11 Entering Text 36 Choosing the Programming Language 11 Creating Elements With the Toolbar 37 The Structure of a WebObjects Application Project 12 Adding or Deleting Items From a Project 13 Web Components 15 Classes 17 Menu Equi
PAGE 6
Working With Dynamic Elements 53 Introduction to Dynamic Elements 55 Attributes 55 Creating Dynamic Elements 56 Using the Toolbar 56 Dragging Elements into the Component Window 56 Using the Add WebObject Panel 57 The Object Browser 58 Creating Variables and Methods in WebObjects Builder 60 Adding Display Groups 63 Configuring the Display Group 65 Creating a Detail Display Group 67 Binding Elements 68 Creating Form-Based Dynamic Elements 72 Dynamic and Static Inspectors 73 Creating Other WebObjects 75 Dyna
PAGE 7
Chapter 1 Setting Up WebObjects Applications
PAGE 8
PAGE 9
Introduction To develop WebObjects applications, you use two primary tools: Project Builder and WebObjects Builder. These tools help you perform the major tasks required to develop your application Project Builder is an integrated software-development application. It contains a project browser, a code editor, build and debugging support, and many other features needed to develop an application. It helps you to: • • • Create and manage your project. Write code to provide behavior in your application.
PAGE 10
Chapter 1 Setting Up WebObjects Applications Set the project type here. Click to choose directory in which to create your project. The New Project panel has a Project Type pop-up list that lets you choose the type of project you want to create. WebObjectsApplication is shown by default. 3. In the Project Type pop-up list, make sure WebObjectsApplication is selected. Another type of project you may want to create is WebObjectsFramework. See “Frameworks” for more information. 4.
PAGE 11
Creating WebObjects Application Projects 6. Type the name of the project you want to create. 7. Click Save. The New Project panel shows the path you speciﬁed. 8. Click OK. The WebObjects Application Wizard starts. Choose level of assistance. Choose programming language. Click to proceed. Choosing Assistance If your application doesn’t access a database, you always choose None for Available Assistance.
PAGE 12
Chapter 1 Setting Up WebObjects Applications Java and Objective-C are compiled languages. WebScript, which is based on Objective-C, is a scripted language. A scripted language allows you to make changes to your application while it is running. When you use compiled code, your application runs faster, but you must build your application before running it. Java ﬁles have the extension .java, Objective-C ﬁles have the extension .m, and WebScript ﬁles have the extension .wos.
PAGE 13
Chapter 1 Setting Up WebObjects Applications Project Builder displays a browser showing the contents of your project. The ﬁrst column lists several categories of ﬁles that your project may contain. The following sections describe these categories. Your project’s components. Double-click to edit in WebObjects Builder. Files in the selected component. Click to display their contents in Project Builder. Categories (“suitcases”) of project resources.
PAGE 14
Chapter 1 Setting Up WebObjects Applications Click here, then choose File->New in Project. Enter new ﬁle name here. The New File panel comes up with the suitcase you selected open by default. 3. Type the name of the item and click OK. The new item is added to your project. To add an existing item (for example, a component, a framework, or a source ﬁle) to a suitcase, ﬁrst select the suitcase in the ﬁrst column of the browser. Then either: • • • Double-click the suitcase.
PAGE 15
The Structure of a WebObjects Application Project Double-click to add existing ﬁles to this suitcase. In addition, you can drag a ﬁle directly onto the suitcase icon in the browser, and the ﬁle is copied into the project and added to the suitcase. To delete items from a project: 1. Select one or more items in the browser. 2. Choose Project m Remove Files. A panel appears, giving you the option of removing the ﬁles from the project only or from the disk as well.
PAGE 16
Chapter 1 Setting Up WebObjects Applications behavior. The name of each one is the component’s name followed by a speciﬁc ﬁle extension. These are the ﬁles in the Main component: • Main.html is the HTML template for the component. This ﬁle contains HTML tags, just like any web page; in addition, it typically contains tags for dynamic WebObjects elements. • Main.wod is the declarations ﬁle that speciﬁes bindings between the dynamic elements and variables or methods in your code. • Main.
PAGE 17
The Structure of a WebObjects Application Project Started With WebObjects for more information on using the Wizard with databases. 4. Specify the language for your component and click Finish. Classes The Classes suitcase contains Java and Objective-C classes. If your application’s primary language is Java, this suitcase contains the Application.java and Session.java ﬁles. If the primary language is Objective-C, it contains the ﬁles Application.m and Session.m.
PAGE 18
Chapter 1 Setting Up WebObjects Applications • • • • The Application.wos and Session.wos ﬁles, if your application’s primary language is WebScript Conﬁguration ﬁles EOModel ﬁles Scripted classes Web Server Resources The Web Server Resources suitcase contains ﬁles, such as images and sounds that must be under the web server’s document root at run time.
PAGE 19
The Structure of a WebObjects Application Project To add an existing subproject (such as ClientSideJava or CommonJava) to your project: 1. Double-click Subprojects in the ﬁrst column of the browser. 2. In the Add Subprojects panel, navigate to the directory of the subproject you want to add and click Open. 3. Double-click PB.project to add the subproject to your project. Supporting Files The Supporting Files suitcase contains your project’s makeﬁle (which you should not edit), as well as Makeﬁle.
PAGE 20
Chapter 1 Setting Up WebObjects Applications Every WebObjects Application project includes several frameworks by default. When you build, your application links with these frameworks. They are: • • • • • WebObjects: The basic WebObjects classes. WOExtensions: Extensions to the WebObjects framework. Foundation: Basic object classes that most applications use. EOAccess: The Enterprise Objects Access Layer. EOControl: The Enterprise Objects Control Layer.
PAGE 21
Editing Your Project’s Source Files Opening an Existing Project To open an existing project from Project Builder: 1. Choose Project m Open. 2. In the Open Project panel, navigate to the project folder and click Open. 3. Select the PB.project ﬁle and click Open. To open an existing project from the ﬁle system, double-click the PB.project ﬁle in the project directory. Project Builder launches (if it is not already running) and opens the project.
PAGE 22
Chapter 1 Setting Up WebObjects Applications • If you use Java or Objective-C, all code ﬁles appear in the Classes suitcase. On disk, they live at the top level of the project directory. • If you use WebScript, the Application.wos and Session.wos ﬁles appear in the Resources suitcase. On disk, they live a the top level of the project directory. The component scripts (ComponentName.wos) appear in the component (ComponentName.wo) in the project and on disk.
PAGE 23
Editing Your Component’s HTML and Declarations Files Editing Your Component’s HTML and Declarations Files While you must use Project Builder to edit your components’ code or script ﬁles, you typically use WebObjects Builder’s graphical interface to generate the HTML and declarations ﬁles. You can, however, also edit these ﬁles using Project Builder. To edit a component in WebObjects Builder: 1. Select Web Components in the ﬁrst column of Project Builder’s browser. 2.
PAGE 24
Chapter 1 Setting Up WebObjects Applications changes to your components (the .html, .wod, or .wos ﬁles) and test them without rebuilding. Note: When you are developing a framework, you must rebuild after any change, even for changes to scripts or images. Therefore, when developing a framework, it is probably best to develop it as an application project, and once it has been tested, move its reusable pieces into a framework.
PAGE 25
Building Your Application The Application Wrapper When you build your project, Project Builder creates an application wrapper, which is a folder whose name is the project name plus the extension .woa. The application wrapper has a structure similar to that of a framework. It consists of the following: • The executable application. • The application’s resources. These include the application’s components as well as other ﬁles that are needed by your application at run time.
PAGE 26
Chapter 1 Setting Up WebObjects Applications When you launch your application, your machine’s web browser is launched by default and it accesses your application. To turn off this feature: 1. Click to bring up the Launch Options panel. 2. Select Environment and Command-Line Arguments from the pop-up menus. 3. Enter -browser OFF as a command line option. You can also launch your application directly from a command line. See Serving WebObjects for more information on command line options.
PAGE 27
Converting Old Projects will reside under the document root, usually DocumentRoot/WebObjects. The ﬁle contains a line you can uncomment for this purpose. 4. In Project Builder’s Build panel, click . 5. From the Target pop-up menu, choose install. (By default, the target is set to woapp.) Select “Install.” 6. Click in the Build panel to install your application.
PAGE 28
Chapter 1 Setting Up WebObjects Applications Performing the Conversion To convert your project, open it in Project Builder. (It’s a good idea to create a backup of your project before converting.) If your project was created prior to WebObjects 3.5, Project Builder detects that a conversion needs to be done. It reassigns the ﬁles in your project to new suitcases, as appropriate.
PAGE 29
Converting Old Projects Moving Your Images After the project is converted, there are additional changes you may want to make in order to take advantage of the new features of WebObjects 3.5. In previous versions, images were stored inside the components themselves. To support the new “split installation” procedure, images should be stored in the Web Server Resources suitcase, so that the web server can access them at run time.
PAGE 30
PAGE 31
Chapter 2 Editing With WebObjects Builder
PAGE 32
PAGE 33
Introduction WebObjects Builder is an application that provides graphical tools for creating dynamic web pages (components). This chapter describes the basic procedures of creating your components’ content with WebObjects Builder. A web page consists of elements. WebObjects Builder allows you to add most of the common HTML elements to a component by using its graphical editing tools.
PAGE 34
Chapter 2 Editing With WebObjects Builder Pop-up list switches editing modes. Click to inspect the selected element. These buttons change properties of selected elements or text. Click one of these buttons to create a speciﬁc element. Click to display the Palette window. Elements pop-up list switches the buttons displayed to its right. This window displays your component’s elements graphically. Object browser shows variables and methods in your application’s code.
PAGE 35
The WebObjects Builder Toolbar • Graphical mode shows a visual representation of your component, including its dynamic elements. The bottom pane, the object browser, lists the variables and methods that are deﬁned in your scripts or code ﬁles. • Source editing mode shows the text of your component’s HTML template in the upper pane and the text of your declarations (.wod) ﬁle in the lower pane. In this mode, you can enter any HTML code.
PAGE 36
Chapter 2 Editing With WebObjects Builder The Preferences panel provides several options for how text is displayed in both graphical and source editing modes. Choose Tools m Options to bring up the panel. For information on resource-handling preferences, see “Dragging Elements into the Component Window”. Set default fonts here. To change the encoding of your HTML document, choose one from this pop-up list. Click here to display formatting preferences for HTML and declarations ﬁles.
PAGE 37
Chapter 2 Editing With WebObjects Builder : This color well allows you to set the color of the currently selected text. To change the color, click on the border of the color well and select a color from the Colors panel. See “Setting Colors” for more information. : This button changes the selected text to a hyperlink. : This pop-up list allows you to center or justify text. Note: Version 3.5 of WebObjects Builder does not support Undo.
PAGE 38
Chapter 2 Editing With WebObjects Builder 1. Place the cursor where you want the element to appear on the page. 2. Click the toolbar button representing the element you want. The element is placed at the cursor position. 3. Select the element (see “Selecting Elements”). In most cases, the element is already selected when you create it. 4. Bring the Inspector to the front by clicking it. If it is not open, click . In the Inspector, you can set various properties of the element.
PAGE 39
The Inspector Some elements (such as text ﬁelds and text areas) can be selected simply by clicking them; they appear with a gray line underneath. Other elements (such as tables) require you to click outside the element and drag across it in order to select it. To select a range of elements, drag across them, or press the Shift key while clicking at the end of the range. The Inspector You use the Inspector to set HTML attributes of the elements in your component. To open the Inspector, click .
PAGE 40
Chapter 2 Editing With WebObjects Builder The top of the window shows the element path to the selected element. Any element can be contained in a hierarchy of several levels of elements and can in turn contain other elements. Here, the element path shows that the heading element is contained in the page element, which is the top level of the hierarchy. When you click an icon in the element path, the appropriate Inspector for that element appears.
PAGE 41
Structure Elements Lists Click to create a new list. If there is a selection, each line in the selection becomes a list item (

). By default the list is an unordered (bulleted) list (

PAGE 42
Chapter 2 Editing With WebObjects Builder Custom Marker Not all legal HTML elements can be created directly using WebObjects Builder’s buttons or menu commands. However, you can create any type of element using the custom tag. To create an HTML element using a custom marker: 1. Place the cursor where you want the element. 2. Click . appears in the component window. You can replace the text “Custom Marker” with the content of the element (if any). 3.
PAGE 43
Working With Tables You can also enter source editing mode and type the marker and its text directly. Tip: To save a custom element so you can use it again, save it on a palette. See “Palettes”. Removing Elements or Text From a Container You can remove an element or text from a containing element. For example, if you’ve typed some text inside a form, but you decide you want the text to be outside the form: 1. Select the text. 2. Click or choose Elements m Promote Selection.
PAGE 44
Chapter 2 Editing With WebObjects Builder To add a column, click the icon at the upper right of the table. The column is added at the right of the table. To add a row, click the icon at the lower left of the table. The row is added at the bottom of the table. Table Editing Modes There are two “modes” that you can be in when working with tables. When you ﬁrst create a table, you are in “structure editing” mode, indicated by the gray handles and icons.
PAGE 45
Working With Tables • Split a selected cell horizontally by clicking or vertically by clicking . • Merge a group of selected contiguous cells into a single cell by clicking . Note: This command isn’t enabled unless the selected cells make up a group that could logically be merged into one cell. • Wrap an abstract dynamic element (conditional or repetition) around a selected row or cell (see “Repetitions”) by clicking dynamic element’s icon in the toolbar.

PAGE 46

Chapter 2 Editing With WebObjects Builder • To set the width or height of a cell, select the cell and use the Table Data Inspector. Changing a cell’s size affects the size of the column or row containing the cell. Inspecting Tables, Rows, and Cells An HTML table (

) is a hierarchical structure, which contains rows (); rows in turn contain cells (

PAGE 47

Creating Hyperlinks Creating Hyperlinks There are two types of hyperlinks that you can use in a WebObjects application: • A static hyperlink (which uses the HTML tag), whose destination is constant. • A dynamic hyperlink (WOHyperlink), whose destination can be speciﬁed at run time. See “Dynamic Hyperlinks”for more information about these. To create a static hyperlink: 1. Click on the toolbar. 2. Type the text that the hyperlink should contain. As you type, the text is underlined. 3. Click again.

PAGE 48

Chapter 2 Editing With WebObjects Builder Setting Page Attributes The top level in the element hierarchy is always the page itself. To inspect a page’s attributes: 1. Select any element in the page. 2. In the Inspector, click the leftmost icon in the element path. (If necessary, click the Inspector button in the toolbar to display the Inspector.) Click here to display Page Attributes. Click here to make the title a dynamic string.

PAGE 49

Setting Colors Setting Colors WebObjects Builder allows you to set the colors for a page’s background, selected text, and hyperlinks. To set the color of selected text in the component window, click in the border of the color well Attributes Inspector. in the toolbar. To set other colors, use the Page Clicking the border of any color well brings up the Colors panel. You can drag colors between this panel and any color well. These buttons provide different ways to select colors.

PAGE 50

Chapter 2 Editing With WebObjects Builder Click to display this palette. Drag an item onto the window to insert into the component. The icons at the top of the palette window show the available palettes. To select a palette, click its icon. Two pre-conﬁgured palettes are provided: Java clientside components and components from the WOExtensions framework.

PAGE 51

Palettes If the palette’s background is gray, you can’t make any changes to it. To enable editing, choose Palettes m Make Editable. The palette's background changes to white and its title says “Alt-drag to insert item.” Note: When you ﬁrst create a palette, it is editable until you save it. 2. In the component window, select the element or elements that you want to add to the palette. 3. Hold down the Alt key and drag the selection to the palette.

PAGE 52

Chapter 2 Editing With WebObjects Builder Note: If the palette is editable, you can drag the item to the window, but it will disappear from the palette. 2. Drag the item from the palette to the location in the component window where you want it to appear. Changing a Palette Icon You can replace the icon of any palette, or any item in a palette, with an image of your own choosing. To do so: 1. Open the palette window and select the palette whose icon you want to change. 2. Make the palette editable. 3.

PAGE 53

Chapter 3 Working With Dynamic Elements

PAGE 54

PAGE 55

Introduction to Dynamic Elements A dynamic element is an element whose exact HTML representation isn’t determined until run time. Dynamic elements are represented in the HTML template by the tag . There are several types of dynamic elements that you can use in your WebObjects applications. Some of them (such as dynamic forms or images) have counterparts in standard HTML (

PAGE 56

Chapter 3 Working With Dynamic Elements For example, a dynamic hyperlink (WOHyperlink) has an action attribute that speciﬁes an action method in the application that is executed when the user clicks the link. The process of associating an attribute with a variable or method in your code is called binding. WebObjects Builder provides tools to make it easy for you to create bindings. Information about your bindings is stored in the declarations (.wod) ﬁle in your component.

PAGE 57

Creating Dynamic Elements In addition, you can also drag a model ﬁle (of type .eomodeld) into a component to create a variable of type WODisplayGroup (see “Adding Display Groups”). Certain ﬁle types (such as .gif, .jpeg, .tif, .eps, and .bmp) are automatically recognized by WebObjects Builder. The Preferences Panel (which you display by choosing Tools m Options) shows a list of ﬁle extensions that WebObjects Builder accepts.

PAGE 58

Chapter 3 Working With Dynamic Elements The element appears in the HTML template. A template appears in the lower pane (the declarations ﬁle) showing the bindable attributes of the element. Elements in brackets are optional. See “Binding Elements” for more information on bindings. Note: You must type in the bindings of all the attributes you want to bind, and delete the others. Otherwise, you will not be able to switch back to graphical editing mode or save the ﬁle. Element appears in HTML source view.

PAGE 59

Chapter 3 Working With Dynamic Elements The ﬁrst column of the object browser displays two types of objects: • Keys are displayed above the horizontal line. A key can be either an instance variable or a method that returns a value. • Actions are displayed below the line. An action (or action method) is a method that takes no parameters and returns a component (the next page to be displayed).

PAGE 60

Chapter 3 Working With Dynamic Elements Choose a command from this menu to add objects to your source code or view the code. There are several ways to add items to the object browser: • Use Project Builder to add keys and actions to your component’s source ﬁle. When you save changes to a source ﬁle, WebObjects Builder parses the ﬁle, detects items that have been added and deleted, and updates the object browser’s display to reﬂect the changes.

PAGE 61

Chapter 3 Working With Dynamic Elements When you choose Add Variable/Method, the following panel opens: Type the variable name here. Click one of these buttons if your variable is an array. Choose the variable’s type from this pop-up list. Check one or more of these boxes. In this panel, you specify: • The name of the key. • Its type. You can choose the type from the pop-up list or type it in directly. You can also use the radio buttons to specify whether the variable is an array.

PAGE 62

Chapter 3 Working With Dynamic Elements Instance variable. Method returning value of instance variable. Method setting value of instance variable. When you choose Add Action, the following panel appears: Enter the action method’s name here. Select response page name from pop-up menu (use null or nil to return same page). When you click Add, the following code is added to your source ﬁle: WebObjects Builder provides these ways to add variables and methods for your convenience.

PAGE 63

Chapter 3 Working With Dynamic Elements Note: To delete a key or action, you must delete it from the source code in Project Builder. Also, the Add Variable/Method and Add Action commands apply only to a component’s code ﬁle. To add variables and methods to the application and session code ﬁles, or to any other code ﬁles, you must edit them directly in Project Builder. Adding Display Groups A display group is an important type of variable that you use in WebObjects applications that access databases.

PAGE 64

Chapter 3 Working With Dynamic Elements • Drag a model (a folder with the extension .eomodeld) from the ﬁle system into the object browser in your component window, or drag an entity from the EOModeler application into the object browser. When you do this, a panel asks you if you want to add the model to your project. If you reply Yes, the Add Display Group panel appears. Enter the display group’s name. Click here to add the display group and conﬁgure it.

PAGE 65

Chapter 3 Working With Dynamic Elements Choose an entity from the project’s models to create an enterprise object based on that entity. Choose this item to create a display group object. In the ﬁgure, if you choose the entity CarPackage as the variable’s type, the following code gets added to your source ﬁle: /** @TypeInfo CarPackage */ protected EnterpriseObject myCarPackage; The variable myCarPackage is declared as type EnterpriseObject.

PAGE 66

Chapter 3 Working With Dynamic Elements In the object browser, means that the display group has been conﬁgured. A means that it has not been conﬁgured, and so the variable isn’t automatically created. A conﬁgured display group shows its keys and actions in the second column of the object browser. You can bind them to elements in your program. Unconﬁgured display Conﬁgured group (double-click to display group conﬁgure). Display group’s keys Display group’s actions.

PAGE 67

Chapter 3 Working With Dynamic Elements • Entity: The Entity combo box has a list of entities from the models in your project. You can select one from the list or type the name. • Has detail data source: Check this to create a detail display group. See “Creating a Detail Display Group” for more information. • Entries per batch: Set a non-zero value here to specify the number of records to be displayed at once. When the value is zero, all records are displayed.

PAGE 68

Chapter 3 Working With Dynamic Elements Drag relationship from EOModeler into component to create detail display group. This example creates a detail display group based on the movieRoles relationship, with Movie as the master entity and MovieRole as the detail entity. As with other display groups, you can use the Display Group Options panel to immediately conﬁgure the newly created display group. Binding Elements This section discusses the basic techniques you use to bind elements.

PAGE 69

Chapter 3 Working With Dynamic Elements In the ﬁgure, you have added a dynamic text ﬁeld (WOTextField) to your component. Note the blue triangle in the top left corner, which distinguishes the dynamic text ﬁeld from a static HTML text ﬁeld. The long rectangle surrounding the text ﬁeld represents the form of which it is a part. To bind the text ﬁeld to the variable myVar: 1. Click myVar in the object browser and drag to inside the text ﬁeld. Default attribute is selected automatically.

PAGE 70

Chapter 3 Working With Dynamic Elements window. Some (not all) dynamic elements display the binding for their default attribute inside the element itself. Binding of text ﬁeld’s default attribute. Click to see documentation on Click to add attribute to this dynamic element. element. 4. If you change your mind, you can click the Inspector’s Disconnect button (which changed from Connect Variable) to undo the binding.

PAGE 71

Binding Elements This time, a different attribute is selected, since the default attribute has already been bound. 2. Click Connect Variable to bind the selected attribute. 3. If, instead, you want to bind an attribute that has already been bound, double-click its row, and the old binding is replaced with the new one. You can also bind an element’s attributes by typing in the Inspector without going through the dragging procedure. To do this: 1.

PAGE 72

Chapter 3 Working With Dynamic Elements • Keys must specify their full key path. For example, to bind the key that is selected in the following ﬁgure, you would type session.selectedSailboards.count Creating Form-Based Dynamic Elements In HTML, a form is a container element (one that can contain other elements).

PAGE 73

Dynamic and Static Inspectors WOForm itself, don’t receive information but contain an action attribute representing an action to be taken when the form is submitted. You bind form-based elements by the process described in “Binding Elements”. Tip: HTML forms don’t allow you to have multiple submit buttons in a single form, but the WebObjects WOForm element does. If you want multiple submit buttons in a form, bind the multiplesubmit attribute of WOForm to the value YES (by typing it in the Inspector).

PAGE 74

Chapter 3 Working With Dynamic Elements Select Dynamic Inspector to set the WOText’s bindings. Set HTML attributes of text area here. To switch back to the WOText Inspector, select Dynamic Inspector from the pop-up list. In addition, you can convert any dynamic element into its static counterpart, or vice versa: • When inspecting a dynamic element, if you click Make Static, the element becomes its static counterpart (if it has one), and the Static Inspector appears.

PAGE 75

Creating Other WebObjects Static Element Dynamic Counterpart Select WOBrowser, WOPopupButton Hyperlink WOHyperlink Applet WOApplet Other Generic WebObject If you convert a static element to its dynamic counterpart by clicking Make Dynamic, and there is no direct counterpart, the element becomes a generic WebObject whose element name is the HTML tag for the static element (see “Generic WebObjects”). In this ﬁgure, a list element (

PAGE 76
Chapter 3 Working With Dynamic Elements To create a dynamic element, you click its toolbar icon. One thing to be aware of is what happens when there are already elements selected when you create the element: • Some dynamic elements (WOHyperlink, WOConditional, WORepetition, custom WebObjects and generic WebObjects) can contain other elements. In this case, the selected elements appear with the new element “wrapped” around it.
PAGE 77
Creating Other WebObjects time. A WOString is abstract in that it doesn’t represent any speciﬁc element, but it can be contained in any other HTML element that can contain text. WebObjects Builder provides a shortcut for binding the value attribute of a WOString, since it is by far the most common attribute you bind. Drag to here to bind value attribute directly. Instead of dragging to one of the icons, drag to the center binding box.
PAGE 78
Chapter 3 Working With Dynamic Elements Repetitions A repetition (WORepetition) is a container element that repeats its contents a certain number of times. It is like a loop in a structured programming language. Repetitions are one of the most important elements in WebObjects, since it is quite common for applications to display repeated data (often from databases) when the amount of data to be displayed isn’t known until run time.
PAGE 79
Creating Other WebObjects When you wrap a repetition around a table row, the repetition symbol doesn’t appear. Instead, a blue border appears around the row. To bind the repetition, drag from the object browser to anywhere in the row (but not to a dynamic element inside the row). The Inspector appears, allowing you to complete the binding as usual. Select a table row, then click here to create a repetition around the row. The blue border and background means the row is in a repetition.
PAGE 80
Chapter 3 Working With Dynamic Elements the WOConditional’s contents are displayed. If condition is false (0), the contents aren’t displayed. condition can be bound to a variable or to method that returns a Boolean value. (WebScript and Objective-C use the constants YES and NO; Java uses true and false.) To bind condition (or any other attribute that takes a Boolean) to a constant value, enter YES or NO in the bindings Inspector. To create a conditional, click in the toolbar.
PAGE 81
Creating Other WebObjects Custom WebObjects You use custom WebObjects for two main purposes: • To implement WebObjects element classes not directly supported by WebObjects Builder. • To implement reusable components (see “Reusable Components” for more details). To create a custom WebObject: 1. Click in the toolbar. A template for a custom WebObject appears at the insertion point. 2. In the Custom WebObject Inspector, specify the element class. Select class name from the list or type it.
PAGE 82
Chapter 3 Working With Dynamic Elements the WOExtensions framework, which is included in your project by default. If WebObjects Builder recognizes the element class, it automatically displays its attributes. Otherwise, you can add them by clicking Add Attribute. The WOExtensions palette (see “Palettes”) contains several pre-deﬁned custom WebObjects elements you can use in a component. Generic WebObjects You can use the generic WebObject element to create a dynamic version of any HTML element.
PAGE 83
Creating Other WebObjects 1. Click in the toolbar. 2. Bring up the Inspector. Enter the element name here. Click to add attributes. A generic WebObject element has one required attribute, elementName, which speciﬁes what type of element should be generated at run time. For example, imagine that a future version of HTML adds a container element called , which you would like to generate dynamically in your component. You would: 3. Type BLOB between the quotes in the Binding column.
PAGE 84
Chapter 3 Working With Dynamic Elements Dynamic Images The elements WOImage and WOActiveImage are dynamic images. At run time, WOImage is rendered as a passive image and WOActiveImage as a mapped, active image. To create them, click respectively. or in the toolbar, A static image element requires you to specify its pathname directly in the HTML. With dynamic images, you bind the ﬁlename attribute to specify the name of an image ﬁle in your project, or in a framework.
PAGE 85
Reusable Components appears in your component, with its code attribute set to the name of the ﬁle. • Drag an element from the Client-Side Components palette to your component (see “Palettes”). Reusable Components One of the strengths of the WebObjects architecture is its support of reusable components. Any component that you deﬁne, whether it represents an entire page or part of a page, can be reused by any WebObjects application.
PAGE 86
Chapter 3 Working With Dynamic Elements • Use the toolbar to add a custom WebObject element (see “Custom WebObjects”) to your page, then use the Inspector to set its type to the name of the reusable component. • Drag a component that has been stored on a palette to the component window (see “Palettes”). A component that is designed for reuse can export keys and actions, which become attributes that the parent component can bind, just as it would set the attributes of any other dynamic element.
PAGE 87
Reusable Components Name of shared component. Parent component can bind to these attributes. Shared component appears inside Custom WebObject icons. The Inspector shows the child component’s attributes. As with any other dynamic element, you can bind the child component’s attributes to keys and actions in the parent component’s code.
PAGE 88