Chapter 3   Creating and Managing Projects


This chapter describes the process of creating and managing projects.

This chapter presents the following topics:

• The Development Process

• Creating a Project

• Adding or Removing Files

• Editing Files

• Viewing and Editing Project File Properties

• Building a Project

• Deploying the Project

• Testing and Debugging

The Development Process

---

The following flowchart shows the basic steps for developing an iPlanet Application Server application:

Figure 3-1    Development of an iPlanet Application Server

This section summarizes the development process. Separate sections describe each step in more detail, along with a simple example.

1. Start iPlanet Application Builder.

   This step assumes you have completed the preliminary planning and design tasks, as described in "Designing Applications.".

2. Create a project.

   When you create a project, iPlanet Application Builder generates a minimum set of files, and they serve as the project's foundation.

3. Add files to the project.

   By reviewing the previously established application design, you know what functionality your application needs, and you know how many web pages the application consists of. These considerations determine what kind of files to add, as well as how many. You can add files one at a time, but you can also use wizards to quickly add a set of files associated with a specific application feature, such as a login page.

4. Edit files.

   As you add files to a project, you can edit them by creating content, by inserting or modifying functionality, or by inserting or modifying the links between them. Different types of files appear in different editor windows. During the editing phase, you use the palette with HTML files. You also use the properties window to review or modify parameter-based information.

5. Compile individual files or build the entire project.

   After adding and editing a few files, you may decide to compile the Java files in the project so far. You can compile an individual file, or you can build the project, which compiles all Java files. As indicated in the previous diagram, you may need to return to the editing phase if compilation errors occur.

6. Test and debug individual files or the entire project.

   After you successfully build the project, you can test it on a server to preview runtime behavior. Testing and debugging go hand in hand, because you can run the server in debug mode. As a result of testing and debugging, you may need to continue editing, then build again.

7. Deploy the project.

   After successfully testing the project, you deploy it to one or more servers. You have now created a web-based application.

The remaining sections describe each step of the development process in more detail.

Creating a Project

---

A project is a container for related files that constitute an application. Once you define application requirements and design the application flow, you are ready to create a project. First, launch iPlanet Application Builder. Then, to create a project, choose "New Project" either from the Welcome dialog box or from the File menu.

In either case, the new project wizard appears. This wizard guides you through the creation of a simple project, as shown in the following figure:

The graphic shows the files that the new project wizard can create; the files it actually creates depends on the files you choose to create using the wizard. These files are the foundation of a project. The default files are described in the following table:

Table 3-1 Default Project Files 

File Created	Description	Editing Required After File is Created?
index.html	Default start page for the project.	Yes
validate.js	Implements JavaScript-based validation for form components. For more information, see .	No

The wizard also creates a project.iab file, which contains information about the files in a project and other information used by the iPlanet Application Builder and the Application Server. This .iab file is the file that you choose when you open an existing project.

Working with Existing Projects

---

This section describes how to open projects and either save them or close them.

Opening a Project

Opening a project means opening its associated .iab file. You can open a project by using the File menu to choose Open Project, by clicking the Open Project button from the standard toolbar, or by double-clicking one of the files listed in the Welcome dialog box. When you open a file from the Welcome dialog box, you also can select "Browse for more projects" to search the file system for another .iab file.

When you search the file system, a dialog box appears:

To open the Sample project, you double-click the Sample folder to list its .iab file. After selecting this file, you can double-click on it or click Open.

Only one project can be open at a time. If you try to open a second project when a project is already open, the first project closes after prompting you to save any changed files.

Saving and Closing Projects

Saving a project means saving all files that compose a project. To save a project, pull down the File menu and choose Save All or click on the double-disk icon in the toolbar. To close a project, pull down the File menu and choose Close Project.

When you save a project, the project state is automatically registered with the local application server.

Adding or Removing Files

You can add files to a project in any of the following ways:

• Create files one at a time, from scratch.

• Create multiple files, using wizards.

• Add existing files.

You can also remove files that are not needed in the project.

Whenever you create files in iPlanet Application Builder, they are automatically added to the current project. This means the files appear in the project tree and are tracked by the .iab file. By contrast, previously existing files do not become part of a project unless you specifically add them.

Creating Files

To create files, you can either pull down the Project menu and choose Add Files, or you can pull down the File menu and choose New and then choose Files. In either case, the New Files dialog box appears:

To create files, either double-click an icon, or select an icon and click Add. You can use the New Files dialog box to create the following individual files:

Table 3-2 Individual Files created using the New Files dialog 

File Type	Description	Where Added to
HTML page	A static HTML file.	Project's subdirectory in the web server's document directory.
Servlet	An instance of a Java class that implements the presentation logic of an application.	Project's subdirectory in the iAS applications directory.
Java file	A generic helper class. It starts out as a blank file, with no generated code. Therefore, you can use a Java class to create Java source files from scratch.	Project's subdirectory in the iAS applications directory.
Data model	Specifies the database tables and relationships to be used in the application.	Project's subdirectory in the iAS applications directory.
Query	Lets you define SQL queries. A query can be called from a servlet or a JSP.	Project's subdirectory in the iAS applications directory.
JavaServer Page (JSP)	An HTML file, with Sun-specified extensions, that is executed on the web or application server instead of on the client server, dynamically creating pure HTML, which is then sent to the client.	Project's subdirectory in the iAS applications directory.

You can also use the following wizards to create various sets of files:

Table 3-3 Wizards 

Wizard	Description
Database Forms	Lets you create master/detail forms and reports, with an optional search page. This wizard creates a page containing a data query form; query files and data models to establish interaction with a relational database; and servlets to process and display the query results.
Results	Creates a servlet and a JSP to display the results of a query.
Input	Creates three files: an HTML page containing a data input form, a servlet to process the form, and a JSP to display the results. Can also produce a query if needed.
Login	Creates files that perform the login function: a static HTML page containing a login form, a servlet to process the form, and a JSP to display results.
Session Bean	Creates a session EJB's source files, including the remote interface, home interface, enterprise bean class, and an.ebx file.
Entity Bean	Creates an entity EJB's source files, including the remote interface, home interface, enterprise bean class, and an .ebx file.

Adding Existing Files

Files that were created outside of iPlanet Application Builder are not automatically tracked by a project's .iab file (and are therefore not considered part of a project) unless you add these files explicitly using iPlanet Application Builder. The files you add must exist within the iAS applications directory tree or in the web server's document directory.

To add files that were created outside of iPlanet Application Builder, perform the following steps:

1. Using your operating system, copy the files to the appropriate directory:
   • Copy HTML pages (static files), JavaScript files, and images to your web server's document directory.

   • Copy other files (queries, data models, Java source, Java Server Pages) to your project root.

   Be sure to copy any files referenced by the file you are copying.

2. In iPlanet Application Builder, display the Add Files dialog box by pulling down the Project menu and choosing Add Files. You can also choose New then Files from the File menu and select the Existing tab.

3. Locate and select one or more files to add to the project.

   
   
   

4. Double click to add a file or click Add.

   The file and any files it references are added to the project.

Removing Files from a Project

When you remove a file from a project, you delete the reference to it in the .iab file. The removed file no longer appears in the Project window. By default, removing a file from a project does not delete it from the file system.

---

Note	Do not to remove files that other files depend on.

---

To remove a file from the project, perform the following steps:

1. Select the file in the Project window.

2. From the Project menu, choose Remove File. For example, to remove index.html, choose "Remove index.html". You may also right-click on the file and use the "Remove" command.

   A confirmation dialog box appears.

3. Select the checkbox if you want to remove the file from the file system.

4. Click Yes to remove the file from the project.

Editing Files

---

After you add files to a project, you edit them to fill in the details. You can edit the following types of files within the iPlanet Application Builder environment:

• HTML files

• Java and JavaScript files

• JavaServer Pages

• data models

• query files

You can optionally specify external editors for HTML and Java files. In addition, you can edit image files by designating a third-party image editor to do so. For information on setting external editors, see "Setting Application Builder Options."

You can open a file for editing in any of the following ways:

• Double-click the file in the Project window or project map.

• Right-click the file in the Project window or project map, then choose Open.

• From the File menu, choose Open File.

• From the Edit menu, choose Open Selected File(s).

The type of file you open determines which editor window appears. When a file is open, you can perform standard editing tasks such as copying, pasting, or searching for text. You execute these tasks using either the Edit menu or the standard toolbar.

Saving, Closing, and Renaming Files

If a file has unsaved changes, its name appears in the Project window with boldface type and with an asterisk (*) appended to the name. Saving a file restores the name to its normal appearance in the Project window.

You can save an individual file or save all files in a project. To do so, choose Save or Save All, using either the File menu or the standard toolbar.

To close a file, use the File menu or click the Close button in the editor window. If there are unsaved changes, you are given the option of saving the file first.

To rename a file, choose Save As from the File menu, and enter the new file name.

Viewing and Editing Project File Properties

---

This section describes viewing and editing project file properties. Properties determine the appearance and behavior of objects in a project.

Each object in a project, including HTML and Java files as well as components and structural objects in those files, has a set of properties associated with it. Each property consists of a name, a description, and a value. The value of a property is usually an editable variable that affects the appearance or behavior of the object to which the property belongs.

The following topics are described in this section:

• Viewing Properties

• Editing Properties

• Using Custom Property Editors

Viewing Properties

View and edit properties by using the Properties window.

The object whose properties are being displayed appears in the top drop-down box. Property names appear in the left column, and their corresponding values appear in the right column. When a property is selected, its description appears in the description box at the bottom of the window.

Some properties have special features to help you edit their values. For more information, see Editing Properties.

Click the alphabetical view button

to view properties in alphabetical order. Click the category view button

to view properties in order by category.

The following illustration shows the Properties window in category view:

You can view the properties of any object in your project.

Editing Properties

The values of many properties are plain text, and can be edited according to the property's constraints by clicking in the property value and typing an appropriate entry.

For properties that must contain one of a restricted set of values, the set of possible values is represented as a drop-down box

. To choose an option, click the down-arrow and select one of the listed options.

Some properties can be edited with a custom property editor, a dialog box created for a specific property. These properties show a button

in the property definition box when you edit the definition. This button launches a custom property editor for that property, which helps you specify various attributes for this property value. For example, click the custom property editor button for the queryName property on a Loop component would help you set the ResultSet and the format for that property. For more information on custom property editors, see Using Custom Property Editors.

Using Custom Property Editors

Custom property editors are specialized dialog boxes that help you provide correct information to complex properties. Custom property editors exist which can help you with the following tasks:

• Editing Data-Bound Properties

• Editing URLs

• Editing List Items

• Editing Colors

Editing Data-Bound Properties

There are three standard data-bound properties that together make up a data-bound object, linking a single column of data to a component. These properties are: a RowSet, which identifies the source of the data (for example, a query); a RowField, which identifies the specific column to display (for example, a field in a query); and, optionally, a Display Format, which determines a format for the data if needed.

A data expression is one or more combinations of a RowSet with a data field, optionally with a display format and/or static characters. You can use a custom data expression to provide multiple combinations of RowSet, RowField, and Display Format inside one component.

For more information on these properties, see "Creating Presentation Layout."

Editing Formats
A display format allows you to format dates or numerical data at run time. This feature is also called a format mask, as it masks the raw data with a different format for viewing.

To use a custom property editor to edit the Display Format property, click the custom property editor button

in the property definition.

Choose one of the following options. When you select a format from the drop-down list, the format string and an example showing runtime appearance appear below. For more information on formatting, see "Creating Presentation Layout".

Table 3-4 Format Options

Option	Usage
None	No display format applied. This is the default.
Numeric	Indicates that the value is numeric. In general, # indicates a digit if necessary (no leading zeros) and 0 indicates a digit absolutely (zero-fill if necessary). Most other punctuation is printed as shown. For example, the data 12345.6 formatted with $###,###.00 yields $12,345.60.
Date	Indicates that the value is a date. In general, D indicates a value for the day, M for month, Y for year, h for hour, m for minute, and s for second. Punctuation appears as shown, if needed. The more times the indicator is repeated, the more complex the format (DD yields 04 for the day, while DDDD yields Friday).
Custom	Custom format. Select from the drop-down list, or develop your own.

Output formatting is ignored for valIn, valOut, and session variables.

Editing Complex Data Expressions
A RowSet/RowField combination yields one column of data from a query. You can provide more than one column of data in a given data-binding, however, by using a custom-built data expression that states which RowSets and RowFields appear in the single display.

To use a custom property editor to create a complex data expression, click the custom property editor button

in the data expression property definition. The custom property editor, shown below, appears:

In general, follow these steps for each RowSet/RowField combination you need in your expression:

1. Choose a RowSet and a RowField.

2. Choose a format mask, if needed.

3. Click Add.

   The expression for that field, represented as <rdbm:field>, is added to the "Data-binding expression" box. At runtime, this expression is replaced with dynamic data.

4. Add any text or HTML markup, such as punctuation or spacing, between fields.

   For example, if you add two RowFields called LastName and FirstName, you might want to add a comma and space between them by first adding LastName, then adding a comma and a space after the expression, then finally adding FirstName. The final product might look something like the following expression (note the comma after the valIn.LastName tag):

   <rdbm:field query="query" name="LastName"/>, <rdbm:field query="myquery" name="FirstName"/>

5. When you have added all the <rdbm:field> tags you require, click OK to insert the data expression into your JavaServer Page.

Editing URLs
There are two types of URLs for developing iPlanet applications:

• A link URL specifies the target for a hypertext link.

• An image URL specifies the location of an image.

For both link and image URLs, the URL can be relative (local server) or absolute (local or remote server). The URL can be determined dynamically if the component that requires it is in a JSP.

Custom property editors exist for both types of URLs, as described in the following sections.

Editing Link URLs
A link URL is a target for a hypertext link. The target can be an HTML page, a servlet, or any other web object accessible from the user's browser.

1. To specify a link URL, click the custom property editor icon. The following illustration shows the resulting dialog box, with some sample data:

   
   
   

2. You can specify an object in your project by selecting an HTML page or a servlet from the drop-down boxes, or you can enter a URL by hand in the URL text box.

3. To add arguments (name/value pairs linked with = and separated by &), click Add and specify a name and value.

4. If this link is in an HTML page, you can bind any part of the URL to dynamic data from a servlet by clicking the associated Data-Bind button. Create a data-binding expression using the resulting dialog box as described in Editing Complex Data Expressions.

Editing Image URLs
The source code for an image on an HTML page or template is located by a URL. The URL can be relative to the page, or a fixed, absolute address. If the URL is in a JSP, it cannot be relative to the page; it must be either absolute or relative to the application root. If the image resides on a JSP, the source can be determined dynamically by a data binding.

1. To edit an image URL, click the custom property editor for the Image Source or Low Res. Source property.

   The following dialog box appears:

   
   
   

1. To insert a relative URL to an image in your project, choose an image from the drop-down box.

2. To insert an absolute URL, click the Absolute URL radio button and enter the URL.

3. If this image is in an HTML template, you can determine the URL with dynamic data from a servlet by clicking the Data-Bound URL radio button and then clicking the associated Data-Bind button. Create a data-binding expression using the resulting dialog box as described in Editing Complex Data Expressions.

Editing List Items

Form list components, such as Drop-Down List, List Box, and Radio Button Group, are often populated by dynamic data in templates. On static pages or in templates where the list options are not dynamically generated, you can edit lists that are not data-bound by selecting the List Items property and clicking the custom property editor icon.

The following dialog box helps you create list items:

Set up list items by creating name/value pairs. If you want an item to be selected by default at runtime, click the Selected checkbox for that option. To add or delete an item, click the appropriate button on the right. When you are finished editing list items, click OK, or click Cancel to abandon changes.

The Drop-Down List component creates a drop-down list with an HTML select statement with the attribute size=1. This implies that only one option can be selected at a time. If you check the Selected checkbox for more than one option, behavior at runtime is undetermined. In iPlanet Navigator 4.x, the drop-down box becomes a scrolling list one item high.

Similarly, to enable multiple values to be initially selected in the List Box component, you must ensure that the Multiple property is set to true.

Editing Colors

Some properties indicate a color, which must be specified using either RGB (a hexadecimal number representing a combination of red, green, and blue) or HSB (a number representing hue, saturation, and value).

You can edit color properties by specifying HSB values. The custom color editor helps you choose colors using either method. Click the tab corresponding with the method you prefer. When specify a color in one mode, the other mode is updated. In both tabs, the selected color is shown in the rectangle on the bottom right.

The following illustrations show the color property editor in HSB mode:

Building a Project

---

The Build menu includes commands for compiling Java files. Shortcuts to these commands appear on the build toolbar. Building a project is comparable to using a make utility to compile a set of source files. If building generates errors, check the Messages window to determine which file or files require editing.

Your personal preference determines how often you decide to compile code. For example, with complex code, you might compile one source file every time you make a small change to it. By contrast, you might decide to wait until there are several Java files in the project, then compile all of them using the Build Project command.

Furthermore, you can choose to skip the build commands altogether and proceed to the testing phase, because building happens implicitly whenever you test a file or project.

For more information, see "Compiling, Testing, and Debugging Applications."

Deploying the Project

---

When a project is complete, and it runs as expected on the test server, you are ready to deploy it as an application. Deploying the project means copying the files to a live server and registering them with the server. In other words, the application becomes available to end users.

You can deploy an application using the Deployment Tool, a separate tool accessible from the iPlanet Application Server (iAS) Administration Tool, or from the iPlanet Application Builder. When you deploy an application, the Deployment Tool installs all the application files and registers all the components on the destination server.

When you deploy the application .ear file using the iAS Deployment Tool, some archived application files are automatically distributed to their appropriate directories on one or more servers and registered with iAS. For example, Java class files, static HTML files, JSP files, and files in your web application module are all automatically sent to the application directory of your application server. EJBs remain and are accessed inside the .ear file.

For more information on deploying or downloading applications, see "Deploying Applications."

Testing and Debugging

---

You can test an individual file or an entire project. Testing an individual file lets you preview it in a web browser. Similarly, testing a project lets you preview its behavior. In this case, the browser displays the project's start page.

When you test a file or a project, iPlanet Application Builder first saves and compiles files as needed. If compilation fails, you must edit the affected files, then build or test again. Once the build succeeds, the application server starts, and the test page appears in the browser.

At this point, you can test the file or project for intended behavior. For example, you can click links, click buttons, and enter data into text fields to see whether the project produces the desired results.

If the application does not work as intended, you may need to edit one or more files, or you may need to debug the project to isolate the problem.

For more information, see "Compiling, Testing, and Debugging Applications."