WEBOBJECTS
TOOLS AND TECHNIQUES
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.
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. 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 Production: Gerri Gray Art: Karin Stroud
With help from: Andy Belk, Craig Federighi, John Graziano, Ben Haller, Charles Lloyd, Jean Ostrem, Kelly Toshach, Greg Wilson
Contents
Table of Contents
Contents iii
Setting Up WebObjects Applications 7
Introduction 9
Creating WebObjects Application Projects 9
Choosing Assistance 11
Choosing the Programming Language 11
The Structure of a WebObjects Application Project 12
Adding or Deleting Items From a Project 13
Web Components 15
Classes 17
Headers 17
Other Sources 17
Resources 17
Web Server Resources 18
Subprojects 18
Supporting Files 19
Frameworks 19
Libraries 20
Non Project Files 20
Opening an Existing Project 21
Editing Your Project’s Source Files 21
Editing Your Component’s HTML and Declarations Files 23 Building Your Application 23
The Application Wrapper 25
Launching Your Application 25
Installing Your Application 26
Converting Old Projects 27
Performing the Conversion 28
Moving Your Images 29
Editing With WebObjects Builder 31
Introduction 33
The Component Window 33
The WebObjects Builder Toolbar 34
Editing Modes 34
Entering Text 36
Creating Elements With the Toolbar 37
Menu Equivalents For Toolbar Commands 38
Selecting Elements 38
The Inspector 39
Structure Elements 40
Paragraphs 40
Lists 41
Headings 41
Horizontal Rule 41
Images 41
Custom Marker 42
Removing Elements or Text From a Container 43
Working With Tables 43
Creating Tables 43
Table Editing Modes 44
Sizing Tables 45
Inspecting Tables, Rows, and Cells 46
Creating Hyperlinks 47
Setting Page Attributes 48
Setting Colors 49
Palettes 49
Creating and Using Palette Items 50
Changing a Palette Icon 52
v
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
Dynamic Strings 76
Dynamic Hyperlinks 77
Repetitions 78
Conditionals 79
Custom WebObjects 81
Generic WebObjects 82
Dynamic Images 84
WOApplets 84
Reusable Components 85
vi
Chapter 1 |
|
Setting Up WebObjects Applications |
|
|
|
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.
•Build and launch your application.
This chapter discusses the main features of Project Builder that you use when developing WebObjects applications. For more information on Project Builder’s other features, refer to its on-line help.
WebObjects Builder is described in the chapters “Editing With
WebObjects Builder” and “Working With Dynamic Elements”.
This document refers to example projects located in the
<DocumentRoot>/WebObjects/Examples/ directory.
Creating WebObjects Application Projects
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.
To do this, launch ProjectBuilder.app, which is found in the NextDeveloper/Apps/ directory. On Mach systems, this directory is under the root directory/. On Windows NT, it is under %NEXT_ROOT%, an environment variable defined when you installed WebObjects (C:\NeXT by default).
On Windows NT, you can launch Project Builder from the WebObjects program group in the Start menu.
2.Choose Project m New.
9
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.Click Browse to specify your project’s location.
Note: You can also type your project’s location and name directly in the Project Path text field.
5.Navigate to the directory in which to create your project.
During development, you typically create a project in the
<DocumentRoot>/WebObjects directory. <DocumentRoot> is your HTTP server’s document root, which you specified when you installed WebObjects. It is convenient to have your entire project under this directory so project resources can be located without going through the installation process (see “Installing Your Application”). However, when deploying your application, you can place parts of your project elsewhere, so that only those files needed by the web server are accessible to users.
Choose WebObjects under the server’s document root.
Type the project name here.
Click here when finished.
10
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 specified.
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.
If your application accesses a database, you also choose None if you want to develop the entire application yourself. However, you may wish to use one of the levels of assistance that WebObjects provides. These forms of assistance are described in other documents:
•Information about Direct to Web.
•Information about the Database Wizard is found in “Creating a WebObjects Database Application” in Getting Started With WebObjects.
Choosing the Programming Language
WebObjects supports three languages:
•Java
•Objective-C
•WebScript
11
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 files have the extension .java, Objective-C files have the extension .m, and
WebScript files have the extension .wos.
The language you choose in the Wizard applies to the following files:
•The Main component. A component in WebObjects represents a page in your application (or possibly part of a page). When you create your project, Project Builder provides you with an initial component called Main. The component’s code file implements the behavior of the component.
•The application and session code files. Application code contains variables and methods that affect the entire application. Session code contains variables and methods that affect a single user’s session.
If, for example, you specify Java as your primary language, the Wizard will create the files Application.java, Session.java, and Main.java for you. You can mix languages in a project by choosing a different language when you create other components.
The Structure of a WebObjects Application Project
On disk, your project is a folder whose name is the project name. The project folder contains all the files in your project. The filePB.project is the project file. You can open a project by double-clicking this file.
Double-click here to open your project.
12
Chapter 1 |
Setting Up WebObjects Applications |
|
|
Project Builder displays a browser showing the contents of your project. The first column lists several categories of files 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.
Adding or Deleting Items From a Project
As you work with your project, you’ll use Project Builder to create new items (such as components or classes) or to add files (such as images) that you created with other programs to the project. For items in certain suitcases (such as subprojects and frameworks), there’s a specific command to add them, discussed in the section about the suitcase. For other suitcases, you use the following procedures.
To create a new item of a particular kind:
1.Select the appropriate suitcase in first column of the browser.
2.Choose File m New in Project.
13
Chapter 1 |
Setting Up WebObjects Applications |
|
|
Click here, then choose File->New in Project.
Enter new file 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 file) to a suitcase, first select the suitcase in the first column of the browser. Then either:
•Double-click the suitcase.
•Double-click the suitcase icon at the top right of the browser window.
•Choose Project m Add Files.
A panel called Add SuitcaseName appears, allowing you to find an item to be added to the suitcase.
14
The Structure of a WebObjects Application Project
Double-click to add existing files to this suitcase.
In addition, you can drag a file directly onto the suitcase icon in the browser, and the file 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 files from the project only or from the disk as well.
Web Components
A component represents a page, or part of a page, in your application. An application can have one or more components.
Every application starts with a component called Main, which is shown in the second column of the browser as Main.wo. All components have the .wo extension.
If you double-click a component, WebObjects Builder opens the component for editing. “Editing With WebObjects Builder” shows how to edit your component using WebObjects Builder.
On disk, a component is represented as a folder with the .wo extension. Every component has several files that specify the component’s look and
15
Chapter 1 |
Setting Up WebObjects Applications |
|
|
behavior. The name of each one is the component’s name followed by a specific file extension. These are the files in the Main component:
•Main.html is the HTML template for the component. This file contains
HTML tags, just like any web page; in addition, it typically contains tags for dynamic WebObjects elements.
•Main.wod is the declarations file that specifies bindings between the dynamic
elements and variables or methods in your code.
•Main.api is used for components that are reused by other components (see
“Reusable Components”).
•Main.woo is used to store information about display groups (if your project
accesses a database) and encodings for HTML templates. You should never edit this file (it does not appear in Project Builder’s browser).
To create a new component:
1.With Web Components selected in the first column of the browser, choose File m New in Project.
2.In the New File panel, type the name of your project and click OK. The WebObjects Component Wizard appears.
3.If you want the Wizard to assist you in creating a component with database access, choose Component Wizard from Available Assistance; otherwise choose None. See “Creating a WebObjects Database Application” inGetting
16
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 theApplication.java and Session.java files. If the primary language is Objective-C, it contains the files Application.m and Session.m. There is a class file for each component that uses Java or Objective-C, as well as any other classes you add to the project.
You can specify that Java classes are client-side, server-side, or common classes. See “Subprojects” for more information on how to do this.
Headers
The Headers suitcase contains header files for projects that use Objective- C.
Other Sources
The Other Sources suitcase contains compiled code that doesn’t belong to a particular class.
Resources
The Resources suitcase contains files that are needed by your application at run time, but which do not need to be in the web server’s document root (and hence will not be accessible to users). It includes:
17
Chapter 1 |
Setting Up WebObjects Applications |
|
|
•The Application.wos and Session.wos files, if your application’s primary language is WebScript
•Configuration files
•EOModel files
•Scripted classes
Web Server Resources
The Web Server Resources suitcase contains files, such as images and sounds that must be under the web server’s document root at run time. When developing your application, you place these files in your project directory and add them to the project (see “Adding or Deleting Items From a Project”). When you build your project, Project Builder copies the files in this suitcase into the WebServerResources folder of your application wrapper (see “The Application Wrapper”).
Subprojects
A subproject has the same structure as a WebObjects Application project. You can use subprojects to divide large projects into manageable chunks.
When you create a new project, ProjectBuilder creates two subprojects (ClientSideJava and CommonJava) in your project folder. By default, they are not added to the Subprojects suitcase. If you need to use them, you must add them to the project. Then you can add your Java classes to the appropriate project as follows:
•Add server-side Java classes to your top-level project.
•Add client-side Java classes to the ClientSideJava subproject.
•Add Java classes that are common to both client and server to the CommonJava subproject.
Note: These subprojects have the makefile variables JAVA_IS_CLIENT_SIDE and JAVA_IS_SERVER_SIDE set in Makefile.preamble so that the appropriate Java code is generated when you build your project.
To create a subproject:
1.Choose Project m New Subproject.
2.Specify the name of your subproject in the New Subproject panel and click OK.
A subproject is created inside the project, with a similar structure to the top-level project. You can add items to the subproject in the same way that you add items to the top-level project.
18
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 first 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 makefile (which you should not edit), as well as Makefile.preamble and Makefile.postamble, which you can modify in order to customize the makefile. You can add other files your project may need (such as Read Me documents) to this suitcase so that they can be edited in Project Builder.
Frameworks
A framework is a collection of classes and resources that an application can use. By storing items such as components and images in frameworks, you can reuse them in multiple projects without having to create multiple copies.
19
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.
You can include additional frameworks in your project if you need to. To add an existing framework to your project:
1.Double-click Frameworks in the first column of the browser.
2.In the Add Frameworks panel that appears, select a framework to add and click Open.
Frameworks are generally installed in the directory
NeXT_ROOT/NextLibrary/Frameworks.
In addition, you can create your own frameworks in order to share WebObjects components and resources across multiple applications. To create a WebObjects Framework:
1.Choose Project m New.
2.Select WebObjectsFramework from the pop-up menu.
3.Select the path where you want to create the framework.
Once you have created a framework, you can add components, images, and other items to it in the same way that you would add them to a project. To have your framework be accessible by other applications, you must install it (see “Installing Your Application” for more information). See “Reusable Components” for more information on using components that live in frameworks.
Libraries
The Libraries suitcase contains libraries that your application links to.
Non Project Files
The Non Project Files suitcase is used for files that you have opened that aren’t part of the current project.
20
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 file and click Open.
To open an existing project from the file system, double-click the PB.project file in the project directory. Project Builder launches (if it is not already running) and opens the project.
Editing Your Project’s Source Files
Every component in your project has a code file whose name is the name of the component followed by the appropriate extension (.java for Java, .m for Objective-C, and .wos for WebScript). Your project may use different languages for different components.
Each component’s code specifies the component’s behavior. Each component is actually a subclass of the class WOComponent (or WebComponent, in Java). This class has standard methods (such as awake and init) that you may want to override (see WebObjects Developer’s Guide for more information on these methods). You can also write your own methods and bind them to dynamic elements in your component (see “Working With Dynamic Elements”, as well as the Dynamic Elements Reference, for information on binding dynamic elements).
In addition to the component’s code, each project has anapplication code file
(Application.java, Application.m, or Application.wos) and a session code file (Session.java,
Session.m, or Session.wos). These files implement
When you first create your project using the Wizard, you specify the language you want to use (see “Choosing the Programming Language”). This language applies to the application and session code, as well as to the code for your initial component, Main. Other components may be written in different languages.
The location of your code in the project suitcases varies somewhat depending on the language used:
21
Chapter 1 |
Setting Up WebObjects Applications |
|
|
•If you use Java or Objective-C, all code files 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 files 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.
To edit your code, select the file name in the project browser. The code appears in the bottom pane of the browser.
To save changes in your code, choose File m Save.
Note: WebObjects Builder gets information from Project Builder about variables and methods in your code. If you add or delete a variable or method, WebObjects Builder doesn’t get the updated information until you save the file.
22
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 files, you typically use WebObjects Builder’s graphical interface to generate the HTML and declarations files. You can, however, also edit these files using Project Builder.
To edit a component in WebObjects Builder:
1.Select Web Components in the first column of Project Builder’s browser.
2.Double-click the component name (for example, Main.wo) in the second column.
WebObjects Builder launches and opens your component in a window.
See “Editing With WebObjects Builder” for information on using
WebObjects Builder to edit your component.
To edit a component in Project Builder:
1.Select Web Components in the first column of Project Builder’s browser.
2.Select the component you want to edit in the second column.
3.Select ComponentName.html or ComponentName.wod in the third column.
The text of the file appears in the lower pane of the browser, where it can be edited.
4.Alternatively, you can double-click the file name or its icon at the top right of the browser, and the file opens in a separate window.
Building Your Application
You must build your application if your project contains any compiled code (Java or Objective-C). If your application uses WebScript only, you do not need to build. In this case, Project Builder runs a default executable (WODefaultApp) when you launch your application.
Once you have built your application, you do not need to rebuild unless you have made changes to your compiled code. You can make
23
Chapter 1 |
Setting Up WebObjects Applications |
|
|
changes to your components (the .html, .wod, or .wos files) 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.
Project Builder has a toolbar with buttons you use to build and launch your application.
Click here to open the Project Find panel.
Click here to open the Launch panel.
Click here to open the Project Build panel. |
Click here to open the Project Inspector. |
1.Click in the toolbar to open the Project Build panel.
2.Click in the Project Build panel to build your project.
Click here to set build options.
Click here to “clean” the project (delete derived files).
Click here to build your project.
The Project Build panel displays the commands that are being executed to build your project. If all goes well, it displays the status message “Build succeeded.”
3. Close the panel.
24
Building Your Application
The Application Wrapper
When you build your project, Project Builder creates anapplication 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 files that are needed by your application at run time.
•The application’s web server resources.
When you build and install your application, Project Builder copies all the files from your Web Server Resources suitcase to a folder called WebServerResources inside the application wrapper. If you have client-side Java components in your project, these are also copied to the WebServerResources folder.
Launching Your Application
To launch your application:
1.Click in the toolbar to open the Launch panel.
2.Click in the Launch panel to launch your application.
25
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.Clickto 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. SeeServing WebObjects for more information on command line options.
Also, on Windows NT systems, you can launch your application by doubleclicking its executable file. When you build your application, Project Builder creates an executable file (ProjectName.exe) inside your application wrapper (.woa) directory.
Installing Your Application
Some files in a web application (such as images and sounds) must be stored under the web server’s document root in order for the server to access them. The remaining files (such as your components and source code) must be accessible to your application but not necessarily by the web server itself.
In previous versions of WebObjects, it was typical to store the entire project under the web server's document root. This practice has advantages for turnaround time during development. However, in deployment, it presents the possibility of allowing users access to your source code. WebObjects 3.5 has a “split installation” feature that allows you to install only those files (such as images) that the web server must have access to under the document root. The remaining files can be stored elsewhere.
The same procedure applies to installing WebObjects applications and WebObjects frameworks. To install:
1.Clickto open the Project Inspector.
2.Under “Install In:”, set the path where the application wrapper will be installed. This should be NEXT_ROOT/NextLibrary/WOApps for applications and
NEXT_ROOT/NextLibrary/Frameworks for frameworks.
3.In Makefile.preamble (in the Supporting Files suitcase), set the make variable INSTALLDIR_WEBSERVER to the path where your WebObjects applications
26
Converting Old Projects
will reside under the document root, usually DocumentRoot/WebObjects. The file 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.
The full application wrapper is copied into the “Install In:” directory, and a wrapper containing only the Web Server Resources is copied into the document root.
See Serving WebObjects for more information about installing your application.
Converting Old Projects
Under version 3.5 of WebObjects, projects are organized differently than under previous versions. This section describes how to convert your old projects to the new organization so that you can work with them in WebObjects 3.5 and beyond.
If your existing project is already a WebObjectsApplication project (that is, it was created by Project Builder and has aPB.project file), you can use Project Builder to convert your project. If your project does not have aPB.project file, you must create a new project and add your existing files to the appropriate suitcases.
In version 3.5, the .woa extension is reserved for the application wrapper. Previously, the project directory itself had the .woa extension. Before converting your project, you should rename its folder to remove the .woa extension.
27