Apple WebObjects 3.5 User Manual

0 (0)

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

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.

About This Book

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 WebObjects Developer’s Guide.

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:

http://localhost/WebObjects/Documentation/WOHomePage.html

In particular, the WebObjects HomePage gives you access to some books that are available only online:

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 NeXT_ROOT/NextDeveloper/Apps/ and launching ProjectBuilder.app. NeXT_ROOT is an environment variable defined when you installed WebObjects. On Windows NT systems, it isC:\NeXT by 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.

3.In the New Project panel, select WebObjectsApplication from the Project Type pop-up list.

14

Apple WebObjects 3.5 User Manual

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/WebObjects directory.

DocumentRoot is your HTTP server’s document root, which you specified when you installed WebObjects.

6.Type the name of the project you want to create (GuestBook).

7.Click Save.

The New Project panel shows the path you specified.

8.Click OK.

The WebObjects Application Wizard starts.

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 acomponent 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 calledGuestBook. 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.

Your project’s components.

Files in the selected component.

Categories (“suitcases”) of project resources.

1.Select Web Components.

The next column displays a list with one element, Main.wo, which is a directory containing the first component in your application. Every application starts with a component called Main.

2.Select Main.wo.

The files you see displayed in the next column are some of the files you work with when developing your component:

Main.api is used for components that are going to be reused by other components; you won’t use it in this tutorial. See WebObjects Tools and Techniques for more information on creating reusable components.

Main.html is the HTML template for your page. It can include tags for 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.

Main.wod is the declarations file that specifies bindings between the dynamic 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 is a file that allows you to specify behavior associated with the 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 and Session.java are other Java files that you may want to work with. In Chapter 2, you’ll add code to Application.java and learn about application and 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.

18

Launching WebObjects Builder

2.Double-click Main.wo in the second column.

The application WebObjects Builder launches and displays a window entitled Main.wo. This represents your application’s Main component.

Pop-up list switches

Click to inspect

 

These buttons change properties

 

editing modes

selected element.

 

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 session. You’ll create others later.

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.

Note: Depending on the width of the window, the toolbar may appear in 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 (Main.wod) file. Later, when you 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. In addition to the standard static HTML elements found in all web pages, WebObjects allows you to createdynamic elements, whose look and behavior are determined at run time.

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

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, orbind, 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 title should be displayed as an <H1> 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 m Save to save the Main component.

Note: Version 3.5 of WebObjects Builder doesn’t allow you to undo 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 E-mail: ” and press Enter twice

6.Type “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 <INPUT TYPE=TEXT> element.

3.In the Size field, type 20 and press Enter to set the width of the text field 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

5.Inspect the multi-line text area.

In Text Area Inspector, you can set various attributes corresponding to those of a <TEXTAREA> element.

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.

Binding Elements

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.

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 guestName of type String. It appears in the first column of the object browser. A declaration for guestName also appears in Main.java, which you’ll edit later.

5.Create the variables email and comments in the same way (they are also of 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 isvalue, 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 thecomments variable and drag the cursor into the Comments text area. Then release the mouse button.

Binding appears here when complete.

Click here to complete binding

Click variable name and drag to element to begin 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 textcomments 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.

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