Apple WebObjects 3.5 User Manual

GETTING STARTED WITH WEBOBJECTS
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 fitness for any particular purpose. In no event shall they be liable for any indirect, special, incidental, or consequential damages arising out of purchase or use of this manual or the information contained herein. NeXT or Apple will from time to time revise the software described in this manual and reserves the right to make such changes without obligation to notify the purchaser.
Copyright  1997 by Apple Computer, Inc., 1 Infinite Loop, Cupertino, CA 95014. All rights reserved. [7010.01]
No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of the publisher or copyright owner. Printed in the United States of America. Published simultaneously in Canada.
NeXT, the NeXT logo, OPENSTEP, Enterprise Objects, Enterprise Objects Framework, Objective-C, WEBSCRIPT, and WEBOBJECTS are trademarks of NeXT Software, Inc. Apple is a trademark of Apple Computer, Inc., registered in the United States and other countries. PostScript is a registered trademark of Adobe Systems, Incorporated. Windows NT is a trademark of Microsoft Corporation. UNIX is a registered trademark in the United States and other countries, licensed exclusively through X/Open Company Limited. ORACLE is a registered trademark of Oracle Corporation, Inc. SYBASE is a registered trademark of Sybase, Inc. All other trademarks mentioned belong to their respective owners.
Restricted Rights Legend: Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 [or, if applicable, similar clauses at FAR 52.227-19 or NASA FAR Supp. 52.227-86].
This manual describes WebObjects 3.5.
Writing: Ron Karr and Kelly Toshach Editing: Laurel Rezeau and Jeanne Woodward With help from: Andy Belk, Craig Federighi, John Graziano, Ben Haller, Kenny Leung, Charles Lloyd, Jean Ostrem, Becky Willrich, Greg Wilson Graphic Design: Karin Stroud Production: Gerri Gray

Contents

Table of Contents
Contents iii
Preface 7
About WebObjects 9 About This Book 9 Where to Go From Here 10
Creating a Simple WebObjects Application 11
Creating a WebObjects Application Project 14 Choosing the Programming Language 16 Examining Your Project 17 Launching WebObjects Builder 18 Creating the Page’s Content 20
Entering Static Text 21 Using the Inspector 22 Creating Form-Based Dynamic HTML Elements 23 Resizing the Form Elements 25
Binding Elements 27
Creating Variables 27 Binding the Input Elements 29 Implementing an Action Method 30
Creating the Application’s Output 32 Building and Running Your Application 35
Enhancing Your Application 37
Duplicating Your Project 39 Creating a Custom Guest Class 41
Binding the Class’s Instance Variables to the Form Elements 42 Creating a Table to Display the Output 43 Adding Dynamic Elements to Table Cells 45 Binding the Dynamic Elements in the Table 45 Creating the Guest Object 46
Keeping Track of Multiple Guests 47
Creating a Guest List 48 Adding Guests to the Guest List 50
Adding a Second Component 51 Using a Repetition 53 Adding the Finishing Touches 56
Clearing the Guest List 56 Adding a Dynamic Hyperlink 57
Creating a WebObjects
Database Application 59
The Movies Application 62
Enterprise Objects and Relationships 63
Designing the Main Page 65
Starting the WebObjects Application Wizard 65 Specifying a Model File 66 Choosing an Adaptor 67 Choosing What to Include in Your Model 68 Choosing the Tables to Include 71 Specifying Primary Keys 71 Specifying Referential Integrity Rules 72 Choosing an Entity 74 Choosing a Layout 75 Choosing Attributes to Display 76 Choosing an Attribute to Display as a Hyperlink 77 Choosing Attributes to Query On 77 Running Movies 78
Examining Your Project 79
Examining the Variables 80 Examining the Bindings 81
Refining Main.wo 85
Specifying a Sort Order 86 Specifying Default Values for New Enterprise Objects 87 Setting a Date Format 88 Setting a Number Format 89 Optional Exercise 90
v
Adding the MovieDetails Page 92
Creating the MovieDetails Component 93 Storing the Selected Movie 93 Navigating from Main to MovieDetails 94 Designing MovieDetails’ User Interface 95 Adding Date and Number Formats 96 Navigating from MovieDetails to Main 96 Running Movies 97
Refining Your Model 97
Opening Your Model 97 Removing Primary and Foreign Keys as Class Properties 98 Adding Relationships to Your Model 99 Using the Advanced Relationship Inspector 102 Where Do Primary Keys Come From? 103
Setting Up a Master-Detail Configuration 104
Creating a Detail Display Group 105 Adding a Repetition 108 Configuring a Repetition 109 Running Movies 110
Updating Objects in the Detail Display Group 111
Managing a DisplayGroup’s Selection 112 Adding a Form 113 Adding a Talent Display Group 113 Configuring the Browser 114 Adding Insert, Save, and Delete Buttons 116
Adding Behavior to Your Enterprise Objects 117
Specifying Custom Enterprise Object Classes 117 Generating Custom Enterprise Object Classes 118 Adding Custom Behavior to Talent 119 Providing Default Values in MovieRole 119 Running Movies 120
vi

Preface

About WebObjects

About This Book

WebObjects is an object-oriented environment for developing and deploying World Wide Web applications. A WebObjects application runs on a server machine and receives requests from a user’s web browser on a client machine. It dynamically generates HTML pages in response to the user’s requests. WebObjects provides a suite of tools for rapid application development, as well as prebuilt application components and a web application server.
WebObjects is flexible enough to suit the needs of any web programmer. You can write code using one of three programming languages: Java, Objective-C, or WebScript. You can write simple WebObjects applications in a matter of minutes. For more complex projects, WebObjects makes it easy by performing common web application tasks automatically and by allowing you to reuse objects you’ve written for other applications.
This book contains three tutorials that help you learn what WebObjects is and how to use it:
Chapter 1, “Creating a Simple WebObjects Application” (page 11), teaches you the basic concepts and steps involved in creating a WebObjects project, using the applications Project Builder and WebObjects Builder. You’ll create a simple application that takes input from a user and displays it.
Chapter 2, “Enhancing Your Application” (page 37), extends the capabilities of your application and shows you additional techniques you use when working with WebObjects.
Chapter 3, “Creating a WebObjects Database Application” (page 59), teaches you how to create a more complex application, one that accesses a database.
WebObjects can run on several platforms. Screen shots in this book are for Windows NT systems; if you are running on a different platform, the look of your windows may vary slightly.
9
Preface

Where to Go From Here

After you have worked through the tutorials in this book, you should have a good working knowledge of WebObjects. For more in-depth information about how WebObjects works, read the
Other valuable information about WebObject is available online. You can access all online information through the WebObjects Home Page. It is located in your server’s document root, and you can access it at this URL:
In particular, the WebObjects HomePage gives you access to some books that are available only online:
WebObjects Developer’s Guide
http://localhost/WebObjects/Documentation/WOHomePage.html
.
WebObjects Tools and Techniques
is a more comprehensive guide to using Project Builder and WebObjects Builder to develop WebObjects applications.
Serving WebObjects
describes how to administer and deploy WebObjects
applications after you’ve written them.
The
Dynamic Elements Reference
documents the dynamic elements provided
with WebObjects and provides examples of how to use them.
The
Client-Side Components Reference
describes what client-side components are available for use in your program and the Java classes used to create them.
The
WebObjects Class Reference
provides a complete reference to the classes in the WebObjects framework. Reference material is provided for both the Java and Objective-C languages.
Additionally, for more information on Enterprise Objects Framework, read the
Enterprise Objects Framework Developer’s Guide
. This book provides in-depth information about how Enterprise Objects Framework works and about techniques for developing database applications with it.
10
Chapter 1

Creating a Simple WebObjects Application

This chapter introduces you to the basic concepts and procedures of developing WebObjects applications. You’ll develop, in stages, a simple application for the World Wide Web. The application you’ll write is called GuestBook.
When you’ve finished the steps in this chapter, your application will have a single web page containing a form that allows users to enter their names, e-mail addresses, and comments. When the form is submitted, the application redraws the page with the user’s information at the bottom.
In Chapter 2, “Enhancing Your Application” (page 37), you will add features to the application, including a second page, a table that displays information from multiple users, and hyperlinks.
This application illustrates the basic techniques you use to create a WebObjects application. You’ll use two primary tools, Project Builder and WebObjects Builder.
13
Chapter 1
Creating a Simple WebObjects 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. In this tutorial, you’ll learn to use Project Builder to:
Create a new WebObjects application project.
Write scripts or compiled code to provide behavior in your application.
Build and launch your application.
WebObjects Builder is an application that provides graphical tools for creating dynamic web pages. You’ll learn to use WebObjects Builder to:
Create static content for your pages.
Add dynamic elements to your pages.
Bind the dynamic elements to variables and methods in your code.

Creating a WebObjects Application Project

A WebObjects application project contains all the files needed to build and maintain your application. You use Project Builder to create a new project.
1. Launch Project Builder.
On Windows NT, you can launch Project Builder from the WebObjects program group in the Start menu. On other platforms, you can launch the application by navigating to the directory launching
ProjectBuilder.app
.
NeXT_ROOT
is an environment variable defined
NeXT_ROOT
/NextDeveloper/Apps/
when you installed WebObjects. On Windows NT systems, it is
.
default. On Mach systems, it is the root directory
2. Choose Project
m
New.
/
Set project type here.
Click to choose directory in which to create your project.
C:\NeXT
and
by
3. In the New Project panel, select WebObjectsApplication from the Project
Type pop-up list.
14
Creating a WebObjects Application Project
4. Click Browse.
Choose WebObjects under the server’s document root.
Type project name here.
Click when finished.
5. In the Save panel, navigate to the
DocumentRoot
is your HTTP server’s document root, which you
DocumentRoot
/WebObjects
specified when you installed WebObjects.
6. Type the name of the project you want to create (
7. Click Save.
The New Project panel shows the path you specified.
8. Click OK.
The WebObjects Application Wizard starts.
directory.
GuestBook
).
Choose level of assistance.
Choose programming language.
Click to proceed.
15
Chapter 1
Creating a Simple WebObjects Application
9. For Available Assistance, choose None.
If you are developing an application that accesses a database, you may wish to use one of the levels of assistance that WebObjects provides. For more information on these options, see Chapter 3, “Creating a WebObjects Database Application” (page 59).

Choosing the Programming Language

WebObjects supports three languages:
Java
Objective-C
WebScript
Java and Objective-C are
compiled
languages. They require you to build your
application before running it. WebScript, which is based on Objective-C, is a
scripted
language. It allows you to make changes to your application while it is
running.
When you create a new project, Project Builder provides you with a
component
called Main. In WebObjects terminology, a component represents a page in your application (or possibly part of a page).
In the Wizard, you specify the language you’ll use to program your Main component, as well as the
application
and
session
code files (which will be
described later).
1. For the primary language, select Java.
Later, you’ll create an additional component for your application and write its code in WebScript.
2. Click Finish.
Project Builder creates a new application directory called
GuestBook
. This directory contains the files you work with in both Project Builder and WebObjects Builder.
16

Examining Your Project

Examining Your Project
Project Builder displays a browser showing the contents of your project. The first column lists several categories of files that your project may contain. This section describes some of the most important files you’ll use.
Categories (“suitcases”) of project resources.
Your project’s components.
Files in the selected component.
1. Select Web Components.
The next column displays a list with one element, directory containing the first
component
in your application. Every
Main.wo
, which is a
application starts with a component called Main.
Main.wo
2. Select
.
The files you see displayed in the next column are some of the files you work with when developing your component:
is used for components that are going to be reused by other
Main.api
components; you won’t use it in this tutorial. See
Techniques
Main.html
for more information on creating reusable components.
is the HTML template for your page. It can include tags for
WebObjects Tools and
dynamic WebObjects elements as well as regular HTML. Typically, you do not edit this file directly; you create your page’s elements graphically using WebObjects Builder.
is the declarations file that specifies bindings between the dynamic
Main.wod
• elements and variables or methods in your scripts. Normally, you don’t edit this file directly; you use WebObjects Builder to generate the bindings for you.
17
Chapter 1
Creating a Simple WebObjects Application
3. Select Classes in the first column of the browser.
Your application’s Java classes.
The Main component’s code goes here.
You’ll see three files listed in the second column:
Main.java
component. You do this by writing code in Java (since you specified Java as the language when you created the project). You use Project Builder to edit this file.
Application.java
• Chapter 2, you’ll add code to session variables.

Launching WebObjects Builder

Now that you’ve created your project, you’ll edit the Main component with WebObjects Builder.
1. Select Web Components in the first column of the browser.
is a file that allows you to specify behavior associated with the
Session.java
and
are other Java files that you may want to work with. In
Application.java
and learn about application and
18
Launching WebObjects Builder
2. Double-click
in the second column.
Main.wo
The application WebObjects Builder launches and displays a window entitled
Pop-up list switches editing modes
. This represents your application’s Main component.
Main.wo
Click to inspect selected element.
These buttons change properties of selected elements.
Click one of these buttons to create a specific element.
Elements pop-up list switches buttons displayed to its right.
This window displays your component’s elements graphically.
Object browser shows variables and methods in your application’s code.
Pull-down menu lets you add variables, methods, and actions to your source code.
You create your component graphically in the upper pane of the component window. The browser at the bottom of the window (known as the
object browser)
is used to display variables and methods your
component uses. Note that there are two variables already defined,
application
and
. You’ll create others later.
session
The toolbar at the top of the window contains several buttons that allow you to create the content of your component. WebObjects Builder also has menu commands corresponding to these buttons.
Depending on the width of the window, the toolbar may appear in
Note:
two rows or one.
3. From the pop-up list at the left of the toolbar, choose .
19
Chapter 1
Creating a Simple WebObjects Application
This pop-up list allows you to switch between graphical editing mode and source editing mode. When you choose source editing mode, the text of your HTML template (
Main.html
) appears. It is a skeleton at this point, since the page is empty. As you add elements graphically, their corresponding HTML tags appear in this file.
The HTML source for your component.
Information about bindings is displayed here.
The bottom pane shows your declarations ( bind variables to your dynamic elements, this file stores the information. Normally, you never edit this file directly.
4. Switch back to graphical editing mode. For the rest of the tutorial, you’ll work in this mode.

Creating the Page’s Content

A web page consists of elements found in all web pages, WebObjects allows you to create
elements
To create elements, you use the buttons on the bottom row of the toolbar (or at the right of the toolbar if your window is large). The button is a pop-up list
that lets you switch the group of buttons that are displayed to its right. There are four groups of buttons:
20
, whose look and behavior are determined at run time.
elements
) file. Later, when you
Main.wod
. In addition to the standard static HTML
dynamic
Creating the Page’s Content
Structures .
Use these buttons to create paragraphs, lists, images, and
other static HTML elements. This setting is the default.
Tables .
Use these buttons to create and manipulate HTML table
elements.
Dynamic form elements .
Use these buttons to create form elements in which users enter information. WebObjects gives your application access to the data entered by users by allowing you to associate, or
bind
these elements to variables in your application.
Other WebObjects .
Use these buttons to create other dynamic elements, which you can bind to variables and methods in your program to control how they are displayed. Some of these (such as hyperlinks) have direct HTML equivalents. Others are
abstract dynamic elements
, such as repetitions and conditionals, which determine how many times an element is displayed or whether it is displayed at all.

Entering Static Text

The simplest way to add text to a page is to type it directly into the component’s window. To demonstrate this, add a title for the GuestBook’s page.
1. Type
My Guest Book
and press Enter.
,
The text is displayed at the insertion point, in this case at the beginning of the page.
2. Select the text you just typed.
3. Click the button in the toolbar. This converts the text to a heading element and displays it in bold.
4. From the pop-up list in the toolbar, choose center justification.
The toolbar also has buttons that allow you to apply text styles such as bold, underline, and italics.
HTML provides several levels of headings. Typically, a document’s main
<H1>
title should be displayed as an
heading. To change the level, you use the Inspector window. You’ll use this window frequently throughout these tutorials.
21
Chapter 1
Creating a Simple WebObjects Application

Using the Inspector

You use the Inspector window to set properties of the elements in your component. The Inspector’s title and contents reflect the element you’ve selected in the component window.
1. Click .
A window titled Heading Inspector appears. It allows you to set the level of the heading.
The element path. Click to inspect different elements in the hierarchy.
Click here to set the heading level.
2. Click “1”.
The text is now part of an
<H1> tag, and it is displayed in a larger font.
3. Click the icon at the top of the window.
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. By clicking the icons in the element path, you can easily choose different elements in the hierarchy.
22
Creating the Page’s Content
Each element has its own Inspector that allows you to set properties appropriate for the element. The Page Attributes Inspector allows you to set properties such as the page’s title and its text color.
Enter page’s title here.
4. Enter a title (such as My Guest Book, or something else of your
choosing) in the Title text field. This is the title of the window that appears in your web browser when you run the application.
5. Close the Inspector window.
6. Choose File
Note: Version 3.5 of WebObjects Builder doesn’t allow you to undo
m Save to save the Main component.
actions you take when editing your component. Therefore, it is a good idea to save frequently. That way, if you make a mistake, you can revert to your previously saved version.

Creating Form-Based Dynamic HTML Elements

In this section, you’ll create a form with several elements to capture input from a guest. These elements look and act like HTML form elements but are actually dynamic WebObjects elements, which enable your code to receive and manipulate the data entered by the user.
23
Chapter 1 Creating a Simple WebObjects Application
1. To display the dynamic form elements buttons in the toolbar, choose from the Elements pop-up list.
2. Place the cursor on the line after the “My Guest Book” text and press Enter.
3. Click .
WebObjects Builder adds a form element to your component. The triangle at the upper-left corner indicates that it is a dynamic form, as opposed to a static form.The gray border indicates the extent of the form. You can increase its size by adding additional elements inside it.
4. Type the text “
Name: ” and press Enter.
This text replaces the word “Form” that was displayed by default.
5. Type “
6. Type “
E-mail: ” and press Enter twice
Comments: ” followed by Enter.
You have just entered three lines (and a blank line) of static text inside the form. Now you’ll enter some dynamic elements to receive input from the user: two text fields and a multi-line text area.
7. Place the cursor to the right of the text “Name: ”.
8. Click to create a dynamic text field element (WOTextField).
9. Repeat steps 7 and 8 for “E-mail: ”.
10. Use the button to create a multi-line text area below the “Comments: ” line.
11. Press Enter twice to create two blank lines.
12. Click to create a Submit button, which is used to send the data in the form to the server.
13. Click to create a Reset button, which is used to clear the data in the form.
24
Creating the Page’s Content
The window should now look like this:
Dynamic form elements buttons.
Dynamic text field elements.
Dynamic text area element.
Rectangle indicates extent of form.

Resizing the Form Elements

The text fields and text area are a bit small, so you’ll resize them using the Inspector window.
To inspect an element, you must first select it. Some elements (such as text fields and text areas) can be selected simply by clicking them; they appear with a gray line underneath.
You select text elements as you would in most text-editing applications (by dragging, or by double-clicking words, or by triple-clicking lines); they appear with gray shading.
25
Chapter 1 Creating a Simple WebObjects Application
1. Inspect the Name text field (that is, select the text field and open the Inspector window).
Choose Static Inspector from this pop-up list.
Enter rows and columns here.
2. Change the setting of the pop-up list at the upper right of the window from Dynamic Inspector to Static Inspector.
All WebObjects elements have a dynamic inspector, that is, one that allows you to set bindings (you’ll work with bindings in the next section). In addition, many WebObjects elements (those with direct counterparts in static HTML) also have a static inspector. This inspector allows you to set the standard HTML attributes for that type of element.
In this window, you can set various attributes of the static counterpart of a WOTextField, which is an HTML
3. In the Size field, type
20 and press Enter to set the width of the text field
<INPUT TYPE=TEXT> element.
to 20 characters.
Note: Be sure to press Enter after typing the values; otherwise, they won’t
“stick.”
4. Repeat steps 1 through 3 for the E-mail field.
26

Binding Elements

Binding Elements
5. Inspect the multi-line text area.
In Text Area Inspector, you can set various attributes corresponding to those of a
6. Increase the size of the element by specifying the number of columns and number of rows to, say, 30 and 6.
7. Save the Main component.
When a user enters information in GuestBook’s form elements, your application needs a way of accessing that information. This is done by binding the form elements to variables in your application. When the user submits the form, WebObjects puts the data into the variables you’ve specified.
Then, your application typically processes the data and returns a new page (or the same page) displaying information that makes sense based on the user’s input. The information displayed is usually represented by other dynamic elements that are bound to variables and methods in your code.
<TEXTAREA> element.
This process of receiving a request (triggered by actions such as submitting a form or clicking a hyperlink) and responding by returning a page is known as the request-response loop. This loop is at the heart of WebObjects programming.
In this tutorial, you’ll have WebObjects return the same page, with the information you received from the user displayed, in a slightly different format, at the bottom. In the second chapter, you’ll add an additional page to your application.

Creating Variables

In this section, you’ll declare individual variables in your code file (Main.java) to hold the name, e-mail address, and comments entered by a single guest. Later on, you’ll structure this information differently in order to work with data from multiple users.
27
Chapter 1 Creating a Simple WebObjects Application
WebObjects Builder allows you to declare variables without having to edit your source file directly. At the bottom of the window there is a pull-down menu called Edit Main.java. It has three items:
Add Variable/Method allows you to add a key to your source file. A key can be either
• an instance variable or a method that returns a value.
Add Action allows you to add the template for an action method, which is a
• method that takes no parameters and returns a component (the next page to be displayed).
View Source File opens the source file in a Project Builder window.
1. Choose Add Variable/Method from the pull-down menu.
The Add Variable/Method panel opens.
Type variable name here.
Choose variable’s type from this pop-up menu.
2. Type
guestName in the Name field.
3. To specify the variable’s type, select String from the pop-up menu (or you can type
String directly in the box.
4. Click Add.
You have just created a variable called the first column of the object browser. A declaration for appears in
5. Create the variables
Main.java, which you’ll edit later.
email and comments in the same way (they are also of
guestName of type String. It appears in
guestName also
type String.)
28
Binding Elements

Binding the Input Elements

Each dynamic element contains several attributes. These attributes determine what happens when the element is displayed or when a form element is submitted. When you bind an element, you actually bind one or more of its attributes.
For example, a WOText element (which represents a multi-line text area) is defined as having two attributes:
value specifies the string the user enters in the text area.
name specifies a unique identifier for the text area.
In this tutorial, the only attribute you are concerned with is
value, which
represents the string entered by the user in the comments field. You’ll bind this to the
comments variable. You don’t need to bind the name attribute in this
application. In a later example, you’ll bind more than one attribute of an element.
1. In the object browser, click the
comments variable and drag the cursor into
the Comments text area. Then release the mouse button.
Binding appears here when complete.
Click variable name and drag to element to begin binding.
Click here to complete binding
29
Chapter 1 Creating a Simple WebObjects Application
The Inspector window comes to the front, displaying the bindings for the text area. The
value attribute is automatically selected (since that is the one
that is most commonly used in bindings). If you wanted to choose a different attribute to bind (you don’t at this time), you would simply select the binding of your choice.
2. Click Connect Variable.
comments appears in the Binding column next to the value attribute of the text
area, indicating that the binding has been made. Also, the text appears in the text field to show that it has been bound.
Note: you can also bind a variable by typing its name directly in the Binding
column for the desired attribute.
comments
3. In the same way, bind the
guestName and email variables to the two text fields.
4. Save the Main component.

Implementing an Action Method

When the user clicks the Submit button, your application will respond by redisplaying the page with the submitted information shown at the bottom. To make this happen, you implement an action method and bind that method to the
action attribute of the WOSubmitButton.
1. From the Edit Main.java menu at the bottom of the object browser, choose Add Action.
Enter action name here. Select response page name from
pop-up menu (use null to return same page).
2. Enter
submit as the name of your action method.
30
Loading...
+ 90 hidden pages