Chapter 8   Designing Forms


This chapter explains how to define forms in Process Builder, and how to use the HTML editing features.

This chapter includes these sections:

• Planning Forms

• Creating Forms

• Modifying Forms

• Adding a Banner to Forms

• Setting Access to Forms

Planning Forms

---

As part of your application, you design the forms that the users are going to use to complete work items or monitor the process. You can assign a custom form for each activity or reuse the same form at multiple activities. You can create separate forms for the people participating in the process and the people monitoring the process. The forms define the data the users get to see and how they can interact with the data.

Before you create a form, you need to know the answers to the following questions:

• What data field should be included in the form?

• Should the data be editable, viewable, or hidden? If a field is designated as editable, only the assignee can edit it. It will be viewable to others.

• Is the form for editing data or monitoring the process?

• How should the form look, and where should the data appear in the form?

Creating Forms

---

To create a form, perform the following steps:

1. From the Insert menu, choose Form.

   The New HTML Form Wizard appears, as shown in Figure 8-1.

Figure 8-1    New Form Layout, Step 1

2. Enter a name for your form.

   Because the form contains HTML, the name typically ends in .html. The name must not exceed 36 alphanumeric characters, including the file extension.

3. Click Next.

   Page 2 of the wizard appears, as shown in Figure 8-2.

Figure 8-2    New Form Layout, Step 2

4. Enter the title that you want to have appear on the top of the form. Enter some introductory text that explains the form to the users.

5. Click Next.

   Page 3 of the wizard appears, as shown in Figure 8-3.

Figure 8-3    New Form Layout, Step 3

6. A list of available fields appears, listed in the order they will appear on the form. Highlight the field you want to add to the form.
   • Click the up and down arrow keys to change the placement order of fields on the form.

   • To select multiple data fields, press and hold the mouse, and drag it across the additional field names.

7. Click Finish.

   The form opens in the form editor for additional editing, as shown in Figure 8-4.

Figure 8-4    Form created by New Form Layout wizard

8. To make additional changes, edit the form using the HTML editor tools provided in the toolbar.

   See Using the HTML Page Editor Toolbar for an explanation of these tools.

9. Add more data fields by dragging them from the Data Dictionary (in the application tree view) to the form.

10. Set the display mode of the field to edit, view, or hidden.

    For more information, see Changing Field Properties for a Form.

11. When you are finished, close the form window and save it.

In addition to the information you create for a form, Process Manager automatically adds two form elements: a header that describes the work item to the end user, and an action bar at the end of the form. These elements appear when the user sees the form in Process Express. The action bar contains two items: the actions included in the activity, and buttons showing the text of the transitions between actions.

If you have designated the activity as "Allow to Add Comment," the form also displays a text field for users to add their comments to a process instance. The comments are included in the process instance history.

Modifying Forms

---

You can modify forms either in Process Builder's form editing tool or in an external editor.

Using Process Builder's Form Editor

To modify a form, double-click its name in the application tree view. The form appears in the Page Editor. Each form appears in its own Page Editor window.

You can edit the text on the form using the HTML editor toolbar. You can copy text and fields from one form and paste them in another. You can also use your right mouse button to bring up a menu of editing commands.

Using an External Editor

You can use an external HTML editor to edit the layout of Process Manager forms for your application with the following cautions:

• You must not change any HTML tags or attributes that you or your editor do not understand. Process Manager data fields are implemented as customized SERVER tags. Some HTML authoring tools will delete tags and attributes that are not standard HTML.

• You must leave these tags in all caps: HEAD, BODY, HTML, and SERVER.

• If you use dynamic HTML or JavaScript in a form created with an external HTML editor, you may find that Process Builder corrupts them and you have to use your external editor to clean up the form.

If you edit the forms in an external editor, be sure not to modify any of the customized SERVER tags, or the data fields on the forms will not work.

If you edit a web page for a form while it is also open in Process Builder, be sure to click on the form again in Process Builder before saving the application. When you click on a form that has been edited externally, Process Builder asks if you want to load the modified form with the latest changes.

Note that the web page for the form only contain a portion of the information the end-user sees on the form. The Process Engine inserts the banner, buttons, and comment areas of the form, as well as the <FORM> tag itself.

The HTML forms for each application are stored in the folder on your local file system where the application is stored.

To edit Process Manager forms using an external HTML editor:

1. Create a form using Process Builder (see Creating Forms) or use a form already created in an external HTML editor.

2. Use Process Builder to add data fields. When you are finished, close the form window and save it.

3. Open the form in your HTML editor.

4. Make and save your changes.

Using the HTML Page Editor Toolbar

The HTML Page Editor toolbar, shown in Figure 8-5, lets you edit and format the HTML forms that you create.

Figure 8-5    HTML Page Editor Toolbar

The drop-down lists and icons assign HTML formatting to the text you choose. You can point your mouse over a toolbar icon to see a "tool tip," or brief description, of these items. In addition, the drop-down lists and icons are described as follows, from left to right:

• The Style drop-down list lets you format text as normal text, HTML headings, or HTML list items.

• The next two drop-down lists let you choose a color and font size for the text.

• The next three icons (letter A) make text bold, italic, or underlined. The icon following it removes changes to the font size or font style (bold, italic, or underline).

• To the right of the style icons are several formatting icons for creating lists, changing indentation, and changing alignment.

• The last two icons display the form in layout mode (the default) or as HTML source. Layout mode displays the form approximately as you would see it in a browser, with all elements laid out. The source view shows the HTML tags. In this view, you can click a "Reformat Source" button. This makes the HTML code more readable by automatically inserting line breaks as appropriate.

Using the Edit, Insert and Format Menus

The menus at the top of Process Builder also contain commands you can use to modify forms. Since the keyboard shortcuts supported by your operating system may not be available, these menus provide you with editing functionality.

Edit

Use the following Edit Menu items to edit your HTML forms.

Cut. Cuts an HTML element from a form.

Copy. Copies an HTML element on a form.

Paste. Pastes an HTML element into a form.

Delete. Deletes the highlighted element or text from the form.

Insert HTML Element

The item on this menu that applies to editing HTML page is HTML Element. You can choose to insert an item from the submenu:

Link. Adds an HTML link. To edit the link, use your right mouse button. When you deploy an application, the structure remains the same as in the local Applications folder, so you can use relative links.

Image. Adds an image to the HTML page. You can double-click on the image to get a property sheet where you can fill out the image name, source, etc. The image must already be in the application directory, or you can import it using the Import command from the file menu. When you deploy an application, the folder structure remains the same as in the local Applications folder, so you can use relative paths when you import images.

Horizontal Line. Adds a horizontal line to the HTML page.

Table (table, row, column, cell). Lets you add a new table (if you are not editing an existing table), or add a row, column, or cell to an existing table.

Client JavaScript. Adds client-side JavaScript to the form. Double-click the Script icon in the form, or use your right-mouse button to get to the properties window. In the properties window, click the ellipsis (...) next to the JavaScript Code property to access the editor window. Type your JavaScript there.

Format

These are standard HTML editing commands. Use them to edit forms.

Size. Applies the font size you select to the text.

Style. Formats text as either bold, italic, underline, or strikethrough.

Remove all styles. Removes size and style formatting from text.

Heading. Applies an HTML heading tag to the text.

List. Applies an HTML list tag to the text. You can choose either a bulleted or a numbered list.

Align. Aligns text at the left, right, or center of the page.

Decrease Indent. Decreases the amount of indention.

Increase Indent. Increases the amount of indention.

Using Right-Mouse-Button Menu Commands

When you edit your HTML forms, your right mouse button lets you perform commands.

When you right-click on a data field on a form, you get a pop-up menu with these commands:

Cut. Cuts selected object.

Copy. Copies selected object.

Paste. Pastes previously copied or cut object.

Table. Displays extra commands for HTML tables, including commands for cutting, copying, and pasting; for deleting rows, columns and cells; and for setting table, row, and cell properties.

Data Dictionary. Displays the data field's inspector window so that you can set any properties. Note that this changes the field's properties on all forms that use it. This option is the same as double-clicking the field in the application tree view.

Properties. Accesses properties of the field on the form. It allows you to change its display mode: EDIT, VIEW, and HIDDEN. It also shows the Field name and the ID of the component. It lists events and methods associated with the field.

Changing Field Properties for a Form

After adding a field to a form, you can change the field's properties on that form. These changes affect only the field on the form; they do not affect other occurrences of the field within the application.

To display the field properties for that form, double-click the field on the form. The Inspector window appears, as shown in Figure 8-6:

Figure 8-6    Field properties on a form

Display Format. The display format of the field. This property is unused for built-in fields. For custom fields that you have implemented through your own Java classes, you can optionally define a display format. Typically, the "default" setting is sufficient.

Display Mode. The drop-down list contains the following values: VIEW, EDIT, and HIDDEN.

• In view mode, a user can see the field but cannot change it.

• In edit mode, users can edit the field if they are the assignee for that work item. For other users, an edit field appears as a view field.

• In hidden mode, the user cannot see the field. However, the value of the hidden field can be accessed by other fields in the form or by client-side JavaScript scripts. One use for the hidden mode is a signature field, which retrieves the values of the fields that need to be signed and presents these values to the user for signature.

Field Name. The name of the field, which you cannot change.

Hints for Setting Field Properties

As you change the display mode, the form updates itself to show the correct visual mode for the field. Editable fields are in boxes on a white background; view-only and hidden fields are on a gray background.

Note that in Process Builder, hidden fields appear on a form. This lets process designers change the mode. It is easier to edit a form if you put all hidden fields at the end of the document. In this way, your view of the form is as close as possible to the user's view.

If you define the same field as editable on more than one form, the value that is stored in the database at the end of the process instance is the last value entered.

Computed fields are always hidden from the user, even in view mode. If you want to display a computed field's information to the user, use a text field instead.

Accessing the Data Dictionary

By right-clicking a field in the form, you get a drop-down list that has a Data Dictionary option. If you choose the Data Dictionary option, you access the properties of the field.

Warning. The properties you edit in the data dictionary are shared by all instances of the field. If you change the properties of a field, you change all occurrences of a field on all forms.

Using Scripts to Validate User Input

You can use client-side JavaScript to validate user input on a form as the user submits it. To validate this input, write a client-side JavaScript script called onSubmitForm() and insert it into the form. This script is invoked just before the form is submitted.

• If the input is not valid, the script returns false, and the form input is not submitted.

• If the input is valid, the script returns true, and the form input is submitted. If the onSubmitForm function returns false, the form is not submitted.

For every data field represented in a form, the form contains a form element that has exactly the same name as the data field. Client-side scripts such as onSubmit functions can access data field values as they are currently displayed in the form. The scripts do this by accessing form elements that have the same name as the data field.

See the section onSubmitForm Example in Chapter 11 "Advanced Techniques for Scripting" for a coded example of an onSubmitForm function.

Adding a Banner to Forms

---

When an end user sees a form, a banner is included at the top. To create a banner, follow these steps:

1. Create a file to be your banner and name it banner.gif.

2. In Process Builder, open the application to which you want to add the banner.

3. From the File menu, choose Import.

4. Click Select and navigate to the banner.gif file to import.

5. Enter "images" in the "into folder" field.

6. Click Import.

   The banner.gif file is imported into the images folder. If the images folder does not already exist, Process Builder creates it.

Note. The file must be named banner.gif and must be in the folder builder/Applications/app_name/images/banner.gif.

Setting Access to Forms

---

Form Access associates forms with specific users and activities at certain steps in the process. To set access control for your forms, click Form Access, which is located near the bottom of the application tree view. As a result, you see the Form Access window. This window displays form access information in a table, as shown in Figure 8-7.

Figure 8-7    Form Access window

The row at the top represents steps in the application. The kind of step involved is indicated by an icon. The column on the side represents the groups and roles used by the application. The groups and roles are in the priority order you set when defining groups and roles.

To assign a form to a group or role at a process step, drag a form from the application tree view into the appropriate square in the process map. If you drag a form to the title box of an activity (top row), it shows up in every square in that column that does not already contain a form. If you drag a form to a role/group name box on the left, the form shows up in every square in the row that does not already contain a form. You cannot drag a form to a box that has an X through it.

At each step in the process, the application looks from top to bottom for the appropriate form to present to the user.

For example, in Figure 8-7, in the "Create New Data Sheet" step, the application presents the same form to everyone (all), regardless of their role in the process. Anyone can initiate a datasheet. However, at the "Approve Pricing" step, the assignee (the product manager who needs to approve the pricing) sees a form for approving pricing. Everyone else is only able to see a form that gives read-only information about the work in process.

To remove a form from the table, click the square the form is in and press the delete key.

Forms for Assignees

The forms for the assignees must contain all the information, both editable and view-only, that assignees need in order to complete a step. You must have a special form for the assignee for every activity. Because entry and exit points do not have work items, they do not require an assignee form. These boxes are crossed out, indicating that you cannot add a form to them. For example, in Figure 8-7 you can see that there is a special form for the assignee in all steps except for entry and exit points.

Forms for Monitoring the Process

Often people who are not necessarily participants in the process may want to monitor its progress. In those cases you might create a special form for all interested parties and assign it to the "all" group, or another group that contains people interested in the process.

In other cases, you do not want to give a nonparticipant view because the process involves sensitive information. For example, in an employee time off request application, an employee's vacation request is private, and should not be available for others to view. In these cases you restrict access by only assigning forms for the people who should have access to the information, for example the assignee and the creator.

Forms for the Administrator

The administrator can perform the following functions on a process instance:

• delegate the work item to a different user

• extend the expiration date of the work item

• change the state of a process instance

• move the work item to a different activity

In order to perform these functions, the administrator must belong to an application's "admin" group. Usually, you make sure the "admin" group has access to a form at each step of the process, so that the administrators have access to the field information they need to make changes to work items. The form can be either a special form for the "admin" group, or a form for the "all" group.

Setting Access to an Entry Point

For many processes, all employees in a company need to be able to initiate a process instance. For example, every employee needs to be able to submit a time off request. In these cases you set up a form for initiating a process instance and assign it to the "all" group (as shown in Figure 8-7).

In other cases you do not want all users to be able to initiate a process instance. For example, if you had a web site that contained the marketing material for a product suite, you might want only people from the marketing department to be able to add documents to the web site. In that case you might make the form for initiating a process instance available only for a "marketing" group.

Please note that you cannot set a form for the creator at the entry point, since the creator role is not used until after the entry point.