Ts 671sp1 Fpapi v01 en

FormsPublisher:
FormAPI
Developer’s Guide
Release 6.7.1
Service Pack 1
© 2002-2007 Interwoven, Inc. All rights reserved.
No part of this publication (hardcopy or electronic form) may be reproduced or transmitted, in any form
or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior
written consent of Interwoven. Information in this manual is furnished under license by Interwoven, Inc.
and may only be used in accordance with the terms of the license agreement. If this software or
documentation directs you to copy materials, you must first have permission from the copyright owner
of the materials to avoid violating the law which could result in damages or other remedies.
Interwoven, ConfirmSite, ContentServices, ControlHub, DataDeploy, DeskSite, FileSite, iManage,

LiveSite, MediaBin, MetaCode, MetaTagger, OffSite, OpenDeploy, Primera, Scrittura, TeamPortal,
TeamSite, VisualAnnotate, WorkDocs, WorkPortal, WorkRoute, WorkSite, WorkTeam, the respective
taglines, logos and service marks are trademarks of Interwoven, Inc., which may be registered in certain
jurisdictions. All other trademarks are owned by their respective owners. Some or all of the information
contained herein may be protected by patent numbers: US # 6,505,212, GBRI # 1053523, US #
6,480,944, US# 5,845,270, US #5,430,812, US #5,754,704, US #5,347,600, AUS #735365, AU
7830068, GB #GB2333619, US #5,845,067, US #6,675,299, US #5,835,037, AUS #632333, CAN
#2,062,965, FRAN / GRBI / SPAI / SWED #480941, GERM #69020564.3, KORS 10-0576487, JAPA
#2968582, MX #219522, NZ #516340, SING #109524, SG #89006, SG #89086, SG #74973, SG
#85502 US #5,065,447, US #6,609,184, US #6,141,017, US #5,990,950, US #5,821,999, US
#5,805,217, US #5,838,832, US #5,867,221, US #5,923,376, US #6,434,273, US #5,867,603, US
#4,941,193, US #5,822,721, US #5,923,785, US #5,982,938, US #5,790,131, US #5,721,543, US
#5,982,441, US #5,857,036, US #6,697,532, US #6,792, 454, US #6,928,149, US #7,092,969 or other
patents pending application for Interwoven, Inc.
Interwoven, Inc.
160 East Tasman Dr.
San Jose CA 95134
http://www.interwoven.com
FormsPublisher: FormAPI Developer’s Guide

Part 01-014-01-EN
August 2007
Table of Contents
About This Book 7
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Notation Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Manual Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Documentation Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Chapter 1: Overview 9
Chapter 2: Using FormAPI 11
The DCT <script> tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Addressing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Addressing and Form Tabs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Addressing Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Using Item Addresses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Addressing Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Getting and Setting Item Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Restoring Dynamic Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Empty Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
onItemChange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Save Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Visibility and Read-Only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Validation and Highlight Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Remote Server Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Auto-DCR Functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
How FormAPI Changes FormsPublisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Hidden vs. Invisible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
<readonly> vs setReadonly() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
CGI Callouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Chapter 3: FormAPI Reference 37
API object - IWAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
string IWAPI.getTSTVersion () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
string IWAPI.getVersion () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Data Capture Form - IWDatacapture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
IWDatacapture.callServer (url, data, isGet) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
IWDatacapture.close (confirmClose) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
IWDatacapture.displayMessage (message) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
void IWDatacapture.enableImagePreview (enable) . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
number IWDatacapture.getCurrentPageNumber () . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
string IWDatacapture.getDCRPath () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
string IWDatacapture.getDCTPath () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
string IWDatacapture.getFormType () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
string IWDatacapture.getGroups () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Forms Publisher: FormAPI Developer’s Guide 3

Contents
IWItem IWDatacapture.getItem (name) . . . . . . . . . . . . . . . . . . . . . ............... 42

number IWDatacapture.getPageCount () . . . . . . . . . . . . . . . . . . . ............... 42
string IWDatacapture.getRole () . . . . . . . . . . . . . . . . . . . . . . . . . . ............... 42
string IWDatacapture.getRoles () . . . . . . . . . . . . . . . . . . . . . . . . . ............... 43
IWItem[] IWDatacapture.getRootItems () . . . . . . . . . . . . . . . . . . . ............... 43
Frame (top level of data capture form/parent).getScriptFrame () . . . ............... 43
string IWDatacapture.getUser () . . . . . . . . . . . . . . . . . . . . . . . . . . ............... 44
string IWDatacapture.getWorkarea () . . . . . . . . . . . . . . . . . . . . . . ............... 44
IWDatacapture.gotoPage (pagenumber) . . . . . . . . . . . . . . . . . . . . ............... 44
boolean IWDatacapture.isHighlightMode () . . . . . . . . . . . . . . . . . ............... 45
boolean IWDatacapture.isModified () . . . . . . . . . . . . . . . . . . . . . . ............... 45
IWDatacapture.save () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ............... 45
IWDatacapture.setHighlightMode (highlightMode) . . . . . . . . . . . . ............... 46
IWDatacapture.setIsModified () . . . . . . . . . . . . . . . . . . . . . . . . . . ............... 46
DCT Items - IWItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
IWItem.addInstance (index, [choice_name]) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
IWItem.addOption (option) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
boolean IWItem.deleteInstance (index) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
IwItem IWItem.getChildByName (name) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
IWItem[] IWItem.getChildren () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
string IWItem.getDescription () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
string IWItem.getLabel () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
string IWItem.getName () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Option[] IWItem.getOptions (). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
RegExp IWItem.getRegex () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
string IWItem.getType () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
string, number, or number[] IWItem.getValue (). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
boolean IWItem.isCollapsed () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
boolean IWItem.isMultiSelect () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
boolean IWItem.isReadOnly () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
boolean IWItem.isRequired () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
boolean IWItem.isValid () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
boolean IWItem.isVisible () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
boolean IWItem.isVisualFormat () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
boolean IWItem.moveInstance (from_index, to_index) . . . . . . . . . . . . . . . . . . . . . . . . . 53
IWItem.removeOption (index) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
IWItem.setCollapsed (boolean) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
IWItem.setDescription (text) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
IWItem.setFocus () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
IWItem.setLabel (text) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
IWItem.setOptions (options). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
boolean IWItem.setReadOnly (readonly, [optional recursive]) . . . . . . . . . . . . . . . . . . . . 55
IWItem.setRegex (regex) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
IWItem.setRequired (required) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
IWItem.setValid (value) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
IWItem.setValue (value) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
IWItem.setVisible (visible) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
string IWItem.toString () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Interwoven, Inc. 4
Contents
Event Registry - IWEventRegistry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

IWEventRegistry.addFormHandler (eventname func) . . . . . . . . . . . . . . . . . . . . . . . . . 61
IWEventRegistry.addItemHandler (itemname eventname func) . . . . . . . . . . . . . . . . . . 61
IWEventRegistry.removeFormHandler (eventname) . . . . . . . . . . . . . . . . . . . . . . . . . . 62
IWEventRegistry.removeItemHandler (itemname eventname) . . . . . . . . . . . . . . . . . . . 62
DCR Information - IWDCRInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
string IWDCRInfo.getDCRName () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
number IWDCRInfo.getFileSize () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Date IWDCRInfo.getModificationDate () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
string IWDCRInfo.getOwner () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
number IWDCRInfo.getStatus () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
boolean IWDCRInfo.isModifiedInWA () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
boolean IWDCRInfo.setDCRName (path callback) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Name Factory - IWNameFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
void IWNameFactory.setAutoDCRPathGenerator (function) . . . . . . . . . . . . . . . . . . . . 67
function IWNameFactory.getAutoDCRPathGenerator () . . . . . . . . . . . . . . . . . . . . . . . 67
Page Generation - IWPageGeneration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
IWPresentationTemplate IWPageGeneration.getPresentationTemplate() . . . . . . . . . . . 68
IWPresentationTemplate IWPageGeneration.getValidPresentationTemplates () . . . . . . 68
string IWPageGeneration.getOutputFile () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
IWPageGeneration.setOutputFile (filename create_directories) . . . . . . . . . . . . . . . . . . 69
boolean IWPageGeneration.setPresentationTemplate (template) . . . . . . . . . . . . . . . . 69
Presentation Template - IWPresentationTemplate . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
string IWPresentationTemplate.getExtension () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
string IWPresentationTemplate.getName () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
string IWPresentationTemplate.getPath () . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Appendix A: Sample User Scripts 71
The Contact User Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
The Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
The DCT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
The Contact DTD Element. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
The Location User Script. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
The Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
The DCT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
The Location DTD Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
The Organization User Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
The Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
The DCT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
The Organization DTD Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
The Position User Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
The Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
The DCT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
The Position DTD Element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Index 87

Contents
Interwoven, Inc. 6
About This Book
FormsPublisher FormAPI allows a template designer, to create forms that dynamically

respond to user actions and other external events.
Intended Audience
This book is written for those who are developing FormsPublisher forms and wish to
use API calls to enhance those forms.
Notation Conventions
This manual uses the following notation conventions:
Table 1 Notation Conventions

Convention Definition and Usage
Bold Text that appears in a GUI element such as, a menu item, button, or
element of a dialog box, and command names are shown in bold.
For example:
Click Edit File in the Button Bar.
Italic Book titles appear in italics.
Terms are italicized the first time they are introduced.
Important information may be italicized for emphasis.
Monospace Commands, command-line output, and file names are in
monospace type. For example:
The iwextattr command-line tool allows you to set and look up
extended attributes on a file.
Monospaced Monospaced italics are used for command-line variables.For
italic example:
iwckrole role user
This means that you must replace role and user with your values.
Monospaced bold Monospaced bold represents information you enter in response to
system prompts. The character that appears before a line of user
input represents the command prompt, and should not be typed.
For example:
iwextattr -s project=proj1
//IWSERVER/default/main/dev/WORKAREA/andre/products/ind
ex.html

About This Book
Table 1 Notation Conventions

Convention Definition and Usage
Monospaced bold Monospaced bold italic text is used to indicate a variable in user
italic input. For example:
iwextattr -s project=projectname workareavpath
means that you must insert the values of projectname and
workareavpath when you enter this command.
[] Square brackets surrounding a command-line argument mean that
the argument is optional.
| Vertical bars separating command-line arguments mean that only
one of the arguments can be used.
This guide also uses the following conventions:

The term “Windows” indicates any supported version of the Microsoft Windows
operating system, such as Windows 2000.
®
Directory paths use UNIX conventions. These conventions mandate using forward
slashes (/) in path names. (Windows systems use backward slashes.) The Windows
convention is used when referring to a Windows-specific directory. For example:
UNIX: docroot/news/front.html
Windows: docroot\news\front.html
Manual Organization
This manual is organized as follows:
Chapter 1, “Overview,” describes FormAPI.
Chapter 2, “Using FormAPI,” describes how to set up FormAPI to be used with
FormsPublisher forms.
Chapter 3, “FormAPI Reference,” describes the FormAPI objects.
Appendix A, “Sample User Scripts,” describes the sample user scripts that ship with
FormsPublisher.
Documentation Updates
Additions and corrections to this document (when available) can be downloaded in PDF
format from the following Web site: https://support.interwoven.com.
Interwoven, Inc. 8
Chapter 1
Overview
FormsPublisher FormAPI allows you, as a template designer, to create forms that

dynamically respond to user actions and other external events. With FormAPI, browser
templates are no longer simple, static forms. They can become responsive, interactive,
highly customized interfaces that greatly enhance the experience of the user entering
content.
Some of the things you can do with FormAPI include:

Automatically compute the value of one field based on the value of another (for
example, a Totals field is computed from a set of Price replicants).
Change the options in a selection element based on the value of another element (for
example, after the user has entered City and State, a database query automatically
populates the ZIP Code field with the valid ZIP codes for that city).
Make an entry field appear or disappear as needed (for example, the Shipping
Address fields only appear if the user unchecks Same as billing).
Intercept the Save button press to provide custom data validation (for example, warn
if the user has entered a value for Project Start Date that is after the value for
Project End Date).
Automatically set the name of the data record (DCR), based on the value of other
fields (for example, use the value from the Model Number field of a product
description record for the file name, precluding the need to prompt the user for a
name).
You enable this functionality by writing a user script that is included (either in-line or
referenced) in the data capture template (DCT). A user script is custom JavaScript code
that uses FormAPI to interact with the data capture form presented by FormsPublisher.
Almost anything that can be done manually by the user entering content into a form may
be scripted (thus the name “user script”) through FormAPI.
At the heart of FormAPI are the event registry and the form item object. The event
registry allows you to associate a user script function to a user event, such as changing
the value of a selection or clicking the Save As button. The FormAPI item object
represents an individual form element, like the Name entry field or the Gender radio
button set. The item object provides methods that let you dynamically query and change
its value and other attributes. A user script author identifies an item by its address,
which is an XPath(1)-like notation that references an item relative to its position in the
DCR.

Chapter 1: Overview
FormAPI also provides numerous other methods for operating on the form as a whole
and for querying attributes of the DCR.
Some important things to note about FormAPI:

FormAPI supports DCRs from both the Interwoven DTD and from custom DTDs.
FormAPI supports data capture templates based on datacapture6.0.dtd.
FormAPI supports overall FormsPublisher configurations based on
templating6.0.dtd.
FormAPI is a JavaScript API. This documentation assumes the user is familiar with
the language syntax, features and limitations. An excellent reference is JavaScript:
The Definitive Reference, 4th ed, by David Flanagan, O'Reilly and Associates, 2004.
The user script does not interact with the browser document object model (DOM)
interface to the HTML form. Instead, FormAPI provides methods to query and set
the values of items in the form.
This lets FormAPI provide a consistent interface to form items that have no DOM
analog (like VisualFormat textareas or items that are not currently on the displayed
page in multipage forms) or to features that the DOM does not support (such as
custom validation expressions for an item).
JavaScript authors familiar with the DOM will find the FormAPI interface very
similar, however.
While user scripts may interact with the user in a number of ways (like JavaScript
dialogs or new browser windows), FormAPI itself presents no visible elements to
the user.
By providing an interface to FormsPublisher, a new world of possibilities is opened to

you. This flexibility does not come without cost, however. Because of the open nature of
the JavaScript browser platform and the fact that user script code is running alongside
FormsPublisher, it is possible to write code that fails with a JavaScript run time error,
that puts the form in an unusable state, or that corrupts user data. Wherever possible, of
course, FormAPI handles faulty input gracefully (usually, by doing nothing), but you
must take care to use only the methods documented in FormAPI as specified and to test
the template carefully before deployment.
NOTE
User scripts must be valid JavaScript code that use FormsPublisher FormAPI only as
defined in this document. Failure to do so can result in unusable templates.
The next chapter (Chapter 2, “Using FormAPI”) provides details on how to include user
scripts in templates and discusses some of the methods in detail. Chapter 3, “FormAPI
Reference” provides a complete reference to all the methods in FormAPI.
Interwoven, Inc. 10
Chapter 2
Using FormAPI
This chapter provides information on how to set up FormAPI so it can be used in your
data capture templates. It also provides information and examples on other aspects of
FormAPI that will help improve your results.
The DCT <script> tag

Before you can start using FormAPI to enhance your templates, you need to tell
FormsPublisher where to find your user script. This is done by using the data capture
template (DCT) <script> tag.
Code in the <script> tag is loaded by FormsPublisher whenever the user creates a new
data content record (DCR) or edits an existing one. The <script> tag is not read when
the user views a DCR (so user scripts are not executed). This can account for differences
in how the DCR is displayed in the view and edit modes; see “Getting and Setting Item
Values” for more details.
The <script> tag is specified in the current data capture template DTD
(datacapture6.0.dtd) as follows:
<!ELEMENT ruleset (label?, description?, script*, rootcontainer)>
...
<!ELEMENT script (#PCDATA)>
<!ATTLIST script
language CDATA "javascript"
location (webserver|template-type) CDATA "webserver"
src CDATA #IMPLIED
>
As this snippet from the DTD indicates, the <ruleset> element in the DCT now takes
any number of <script> tags. The <script> tag has three attributes: language,
location, and src, and it may also have content.
The language attribute defaults to javascript. Currently, FormAPI has a JavaScript

binding only.
You may specify a user script in either of two ways:

Chapter 2: Using FormAPI
You can include the user script in the DCT in the <script> tag, as a CDATA
section. This has the advantage that the code is always with the template definition
and changes that affect both parts can be maintained in a single file.
You can keep your code separate from your DCT and point FormsPublisher to your
file using the src and location attributes. This makes it easier to share the file
across templates.
To place the code inline in a CDATA section, place the content within the XML CDATA
markers, <![CDATA[ and ]]>. For example, the following code opens an alert when the
template is first loaded:
<ruleset name="TeamSite Templating">
<itemref name="Address"/>
<script>
<![CDATA[
alert ("Hello, world!");
]]>
</script>
</ruleset>
Alternatively, you could save the script in a file called hello.js and specify its location
using the src attribute. The actual location the src attribute points to may be anywhere
on a webserver, in the same directory as the data capture template type definition, or
somewhere else on the same TeamSite server. The value of the location attribute
controls how the src attribute is interpreted:
webserver
The src attribute is the URL of the target, for example

http://myserver/mypath/hello.js. This is the default if the location attribute is not
specified.
template-type
In this case, src specifies a location relative to the template type directory. So if
hello.js lived alongside the DCT in:
/iwmnt/default/main/WORKAREA/user/templatedata/category/type/hello.js
then specifying <script location="template-type" src="hello.js" would be

sufficient.
Multiple <script> tags are allowed, in which case their user scripts are loaded into the
target frame successively.
Typically, a user script consists of a set of functions, usually with one initialization
function. The last line of the user script usually includes a call registering this
initialization function to be called when the onFormInit event occurs that indicates the
form load is complete. This call-back mechanism ensures that certain operations that
might affect form elements are not attempted until the form has been completely
processed (see “Initialization”). In any case, the JavaScript code is simply executed as it
is loaded, as it would in any browser frame.
Interwoven, Inc. 12
Because FormAPI and the user script code loaded by the <script> tag all reside in the
same frame, it is important to adhere to naming conventions to avoid collisions in the
global namespace. Identifiers that start with IW, iw, or _iw are reserved for use by
FormsPublisher.
Initialization
Initialization describes the process by which FormsPublisher creates form objects that
can be manipulated with FormAPI calls. For performance reasons, user script code is
loaded at approximately the same time as the data capture form is initialized. Operations
directly affecting a visual aspect of an item, such as visibility, readonly, and collapse
state, may be sensitive to the timing of form initialization. To ensure that FormAPI
operations (perhaps to make a container invisible) occur after initialization is complete,
FormAPI provides a form event OnFormInit to defer execution of user script code.
Typically this might look like:
function init() {
var containerToHide = IWDatacapture.getItem("/myform/hidden");
if (containerToHide){
containerToHide.setVisible(false);
}
}
IWEventRegistry.addFormHandler("onFormInit", init);
It would be possible to simply call the init function; however, doing so risks that the
form has not completed initialization, and some or all of the items the user script code
will try to modify may not have been completely created. In the example init()
function above, this might result in an apparent failure of the setVisible() operation
(since the setVisible() operation will fail silently). Using the onFormInit event
ensures that the setVisible() operation is not called until the form items are properly
initialized.
Addressing
Addressing is a means of selecting an individual item in the data capture form. It is also
used to register event handlers for an item. The notation of FormAPI item addressing is
similar to the W3C XPath Recommendation (http://www.w3.org/TR/xpath).
NOTE
The similarity to XPath is limited to the simple notation for node names. Other features
of XPath such as wildcard characters, functions, and relative paths are not part of
FormAPI item addresses.

FormAPI addressing provides a single, consistent view of the DCT's item structure
regardless of its source. Hence the address of an item is directly derived from the DCT
that defines it. Each and every item that is directly in the hierarchy of an item in the
DCT needs to be included in the address regardless of whether the item has a pathid or
location attribute. This applies to both Interwoven-style templates as well as custom
DTD templates.
Addressing and Form Tabs

If you use the <tab> element in datacapture.cfg to enable tab views in a data capture
form, you must include the tab name in any absolute paths specified in FormAPI code
that refers to items within the tab. For example:
var containerToHide = IWDatacapture.getItem("myTab1/myform/hidden");
This is necessary because a tab is structurally like a FormsPublisher container, and

FormAPI must be able to distinguish between items that have the same name but are
located in different tabs (containers). If you have existing FormAPI code that specifies a
path to a non-tab item and you modify that item in datacapture.cfg so that it now
resides within a tab, you must update your FormAPI code so that the absolute path for
the item contains the tab name.
NOTE
Tab names are not required in data records because data records pertain only to saved
data. The location and pathid attributes in the <container> and <item> elements in
datacapture.cfg specify the data record location for the item’s data. The <tab>
element, on the other hand, does not have a location attribute. Therefore it is
non-located and has no representation in the data record.
Addressing Syntax
The notation used for item addresses is similar to basic XPath syntax, which is similar to
the UNIX file system addressing. Consider a simple XML file:
<state>
<city>
<street>This is the street node</street>
</city>
</state>
For this XML snippet, the address for node street is /state/city/street, where
street is a child of city, which is a child of state. If the path starts with a forward
slash /, then it represents an absolute path to the required element from the root element.
Absolute paths are the only notations allowed in FormAPI. Relative paths are not
supported.
Interwoven, Inc. 14
If you consider an XML document to be a tree of nodes, then the address to a particular
node is /parent_node_address + /child_node_name. If a parent node has multiple
children with same name, then the address to the child node contains its position as a
number in square brackets next to its name. This address will look like:
/parent_node_address/child_node_name[position], where position is a positive
integer.
There is an important difference between FormAPI address notation and XPath. The
path consists of name attributes, instead of using the tag names to represent an address.
So the corresponding DCT snippet might look like:

..<container name='state' ... >
<container name='city' ... >
<item name='street' ... />
</container>
...
The address for the street item is /state/city/street.
The .. notation can be used in addresses to access the parent node. The “Addressing
Examples” section contains more details on the usage.
FormAPI addresses only reference a single item. There is no support for wildcard
characters such as *.
Using Item Addresses

The FormAPI method IWDatacapture.getItem() takes an item address and returns an
IWItem object that represents it (see “Data Capture Form - IWDatacapture”). Conversely,
the method getName() of the IWItem object returns the address of an item (see “DCT
Items - IWItem”).
Event handlers on items are registered through IWEventRegistry.addItemHandler()

method. It takes the address of the item, the event name and a pointer to the handler as
input (see “Event Registry - IWEventRegistry”).
To illustrate how item addresses are used, consider the following snippet from a DTD:
<data-capture-requirements name="example">
<ruleset name="example">
......
<conatiner name="a" combination="and" location="a">
<container name="b" combination="and" location="b">
<item name="e" pathid="e">
<text/>
</item>
</container>
<item name="c" pathid="c" max="unbounded" min="0">
<text/>

</item>
</container>
......
</ruleset>
</data-capture-requirements>
In the above example, node c is a replicant, while node e is not.
To intercept the onItemChange event for the form item that corresponds to node e with a
function called handle_e_changed, the user script would execute:
IWEventRegistry.addItemHandler("/a/b/e", "onItemChange",
handle_e_changed);
Because node c is a replicant, the address of the first instance is /a/c[1], while that of
second instance is /a/c[2], and so on.
To intercept the onItemChange event on all instances of node c item, register a handler
to the address /a/c:
IWEventRegistry.addItemHandler("/a/c", "onItemChange", handle_c_changed);
To register an event for only a specific instance of a replicant, give the path to that
replicant.
Addressing Examples
Example 1: Container Addresses
For this DCT:

<container name="Story" combination="and" location="story">
<item name="Section" location="Section">
<text required="t" maxlength="100"/>
</item>
</container>
The address for the item Section would be /Story/Section. The address for the item
Story would be /Story.
Example 2: Replicant Addresses
For this DCT:

<data-capture-requirements name="Example">
<ruleset name="Example">
.......
<container name="a" combination="and" min="0" max="unbounded"
location="a">
<item name="c" pathid="c">
<text/>
</item>
Interwoven, Inc. 16
<item name="d" pathid="d">

<text/>
</item>
</container>
......
</ruleset>
Examples of addresses for some items:

Item a, the replicant container: /a.
Item c under the first instance of item a: /a[1]/c.
Item c under the eighth instance of item a: /a[8]/c.
Item d under the second instance of item a: /a[2]/d.
Item d under the tenth instance of item a: /a[10]/d.
NOTE
“and” replicants and “or” replicants are addressed in the same way.
Example 3: Mixed Content Addresses
For this DCT:

<data-capture-requirements name="Example">
<ruleset name="Example">
.......
<container name="MixedContent" combination="or" max="unbounded"
min="0">
<item name="PCDATA" pathid="l">
<text/>
</item>
<item name="j" pathid="j">
<text/>
</item>
</container> ......
……
</ruleset>
In this example, the MixedContent item has a mixture of both PCDATA and subelements
(item j).
Addresses for items are:

The PCDATA item under the first instance of MixedContent
/MixedContent[1]/PCDATA
The j item under the second instance of MixedContent

/MixedContent[2]/j

Note that PCDATA only appears in an address if it is part of a mixed content element.
Example 4: Addressing Parents and Siblings
For this DCT:

<data-capture-requirements name="example">
<ruleset name="example">
......
<container name="b" combination="and" location="b">
<item name="e" pathid="e">
<text/>
</item>
<item name="f" pathid="f">
<text/>
</item>
</container>
......
</ruleset>
The following userscript code returns the item object that corresponds to the element e:
item = IWDatacapture.getItem("/b/e");
To get the parent item that corresponds to the element b, use the '..' notation:
parent = IWDatacapture.getItem(item.getName() + "/..");
To get the sibling item that corresponds to the element f:

siblingItem = IWDatacapture.getItem(item.getName() + "/../f");
Getting and Setting Item Values

The FormAPI item object provides the getValue() and setValue() methods for getting
and setting the value of an item. The value of an item is dependent on its type:
The items <text>, <textarea>, <hidden>, and <browser> have simple string
values. (For VisualFormat controls, the string is the HTML that is generated by the
contents of the field.)
Single <select> and <radio> items have a single integer value that represents the
zero-based index of the currently selected option.
Multiple <select> and <checkbox> items have an array of integers that represent
the zero-based indices of their selected options.
The items that have options use the index of their selections and not the label or the
value of their options. FormAPI provides four methods to access the options of an item:
getOptions() returns an array of JavaScript Option objects.
addOption() appends an Option to the select list for an item.
Interwoven, Inc. 18
removeOption() removes an Option from a select list by specifying its index.

setOptions() replaces the selections for an item.
The getOptions(), addOption(), and setOptions() methods all make use of the
standard JavaScript Option object. This object has text and value properties to access
the label and value of the option, respectively. The text of an option is the label the user
sees in the form. The value of an option is the value that is saved in the DCR.
For example, to set the value of the /a text item to hello:

IWDatacapture.getItem("/a").setValue("hello");
To select the third option in the /b radio button:

IWDatacapture.getItem("/b").setValue(2);
To select the second and third check boxes of the /c item:

IWDatacapture.getItem("/c").setValue([1,2]);
To get the label of the selected option of the /d select item:

item = IWDatacapture.getItem("/d");
label = item.getOptions()[item.getValue()].text;
One of the most powerful features of FormAPI is the ability to dynamically change the
available options of an item. For example, suppose the DCT specifies that the city
selection has options for New York, Chicago, and Los Angeles:
<item name="city">
<label>City</label>
<select>
<option value="ny" label="New York"/>
<option value="chi" label="Chicago"/>
<option value="la" label="Los Angeles"/>
</select>
</item>
A user script may add Boston to the list:

item = IWDatacapture.getItem("/city");
newOption = new Option("Boston", "bos", false, false);
item.addOption(newOption);
Here, we used the JavaScript Option object constructor to create the new entry for
Boston. By specifying false to both the selected and defaultSelected arguments, the
new option is added without changing the current selection.
Alternatively, you could replace the entries in the city selection with a new list of cities:
newOptions = new Array();
newOptions[0] = new Option("London", "lon", false, false);
newOptions[1] = new Option("Paris", "par", false, false);
newOptions[2] = new Option("Madrid", "mad", false, false);
IWDatacapture.getItem("/city").setOptions(newOptions);

Restoring Dynamic Options

It is very important to remember that if a user script dynamically changes the options
available in a selection, the user has the ability to make a selection that was not declared
in the DCT. This can have serious consequences when the form is reopened.
For example, when the user selects Boston and saves the form, the value bos is entered
into the city element of the resultant DCR, as you had intended.
However, when the user reopens this DCR, the value bos does not match any of the
declared options in the DCT. In this case, FormsPublisher implicitly adds the bos option
to the city selection. However, because it has no way of knowing what the label for this
option is, the label of the new option is set to its value. Thus, when the user reopens this
DCR, the city selection looks like this:
bos
New York
Chicago
Los Angeles
with bos selected.
There are several ways to avoid this problem:

The most simplistic approach is to use labels that match values. This is easily
implemented if this constraint is acceptable.
The DCT can be configured to list the superset of all possible options, and the user
script dynamically sets the correct subset it needs on startup. This, too, is easily
implemented but is not acceptable if the options are dynamically generated or
queried from a large external source.
The best solution is to ensure that the user script restores the options of a selection if
the value does not have the right label. This requires querying the option and
checking the label of the selected option. If it is not correct, a new options array is
created that adjusts the problem. Because the user script usually has the ability to
regenerate the option, this approach is the most flexible.
Empty Options
If a single <select> item has no value (and no default value), FormsPublisher renders
the select list with an extra blank option at the top.
Even though this blank entry is physically present in the list to enable the user to make
no selection, it is not returned by the FormAPI option methods. If a single <select> or
<radio> item is unselected, getValue() returns null. Calling setValue(0) selects the
first non-blank option; calling removeOption(0) removes the first non-blank option.
The options array returned by getOptions does not include the blank option.
Interwoven, Inc. 20
Because FormsPublisher uses the empty string to represent the case of no selection,
options should not have empty values. If they do, options with empty values are treated
as if no selection was made.
Multiple <select> items are unaffected by this behavior because they “natively”
support the empty selection when none of their options are selected. If a multiple
<select> has no option selected, getValue() returns an empty array.
Events
To respond to user actions dynamically, the user script needs to be notified that the user
has done something. It does so by listening for a FormAPI event, which is triggered
(generated) as the user interacts with the form. Specifically, FormAPI triggers events
when the user:
Changes the value of an item, for example, by typing text into a text field or
changing the value of a selection (onItemChange). This event is generated for the
specific item.
Tries to close the form (onClose). This event is generated for the entire form.
Clicks the callout button for an item (onCallout). This event is generated for the
specific item.
Adds, moves, deletes, collapses, or expands a replicant. This event is generated for
the specific item.
Previews or generates a form through a presentation template. The event is
generated for the entire form.
Tries to save the form, either by clicking Save or Save As, or by requesting a save
when prompted after clicking Preview or Generate (onSave). This event is
generated for the entire form.
Events are also generated at various stages of the save process (onSaveValid,
onSaveNameSpecified, and onSaveDone).
A user script registers a handler (also known as a callback) to a particular event (or, in
the case of the item-specific events, to an item and an event). A handler is a user script
function that is called when the event triggers. Depending on the event, the handler may
be passed arguments (for example, the onItemChange event handler is passed a copy of
the item object that triggered the event).
FormAPI supports multiple event handlers, allowing the processing of multiple events
from multiple servers in the same form. For example, data from MediaBin and WorkSite
servers can now be used to populate the same data form.
Use the methods of the IWEventRegistry object (see “Event Registry -

IWEventRegistry”) to register (or remove) an event handler. For example, to call the
nameChanged() function every time the user changes the value of the /name item:
IWEventRegistry.addItemHandler("/name", "onItemChange", nameChanged);

The user script author does not use the browser's events or DOM in any way. The user
script only needs to interact with FormAPI events.
The following sections describe the onItemChange and SaveEvents event handlers in
more detail. See “Event Registry - IWEventRegistry” for the complete list of events.
onItemChange
The most commonly used event is onItemChange. It is triggered:
On a <text> or <textarea> when the user finishes typing and the focus leaves the
item with a different value than it had before.
On a single <select>, <checkbox>, or <radio> item whenever the user makes any
selection.
On a multiple <select> list when the user leaves the item, and the set of selections
is different than it was before.
As in the browser event model, this event usually corresponds to the browser's onChange
event. The exception is multiple <select> items, which call onItemChange only when
the focus leaves the item (the browser's onBlur event) and the set of selections changes.
The handler for an onItemChange event is passed a copy of the item object that triggered
the event. This object also has a special property set, oldValue, that stores the value of
the item (as returned by getValue()) before the user made the change.
For example, if onItemChange for the /name is registered to the nameChanged() function
as above, then nameChanged() could restore the original value of the field if the user
erased it:
function nameChanged(nameItem) {
if (nameItem.getValue() == "") {
nameItem.setValue(nameItem.oldValue);
}
}
NOTE
Because of the performance penalty involved in computing VisualFormat values, the
oldValue property is unavailable on these items.
Interwoven, Inc. 22
Save Events
The save process is more complicated because it involves several steps:
Figure 1 Save Events Process
A save may be initiated in several ways. The user might click the Save or Save As
button. The Preview and Generate buttons also give the user the opportunity to save the
DCR before proceeding. All of these conditions trigger an onSave event.

The onSave event handler is passed an integer that indicates what button triggered the
event. In this way, the save handler can determine how the save was triggered and
behave differently if necessary:
function saveHandler(button) {
switch (button) {
case IWDatacapture.SAVE_BUTTON:
case IWDatacapture.SAVEAS_BUTTON:
case IWDatacapture.SAVECLOSE_BUTTON:
// User clicked 'Save', 'Save As' or 'Finish'
...
break;
case IWDatacapture.PREVIEW_BUTTON:
case IWDatacapture.GENERATE_BUTTON:
// User clicked 'Preview' or 'Generate'
...
break;
}
}
NOTE
Code references to SAVECLOSE_BUTTON refer to the Finish button in ContentCenter.
If an onSave event handler is registered, it must return true for the save to proceed. If it
returns false or null, the save is terminated.
If the save proceeds, FormsPublisher validates the form, using the required states and
validation expression set for each item (see “Validation and Highlight Mode”). If
validation fails, the user is alerted and the save is terminated. The form automatically
enters highlight mode, during which all invalid fields are marked with red labels.
If the form is valid, the onSaveValid event is generated, and any registered user script
function is invoked. Here, you can include code that validates the form as a whole (for
example, ensuring that the start date is before the end date):
IWEventRegistry.addFormHandler("onSaveValid", validateForm);
...
function validateForm() {
// Determine if the form is valid.
...
if (formValid) {
return true;
} else {
alert("Form is invalid ...");
return false;
}
}
Note that the onSaveValid event handler is not passed any arguments. As with the
onSave event, the save terminates if the handler returns false.
Interwoven, Inc. 24
If the save proceeds, FormsPublisher next checks to see if it knows the name of the
DCR, or if it needs the user to specify one using the workarea browser. Specifically:
If the user enters the save process by clicking the Save As button, the workarea
browser always displays.
If the DCR currently has no name, either because it is a new DCR or because the
user script reset the current name by calling IWDCRInfo.setDCRName(null), the
workarea browser displays.
If the workarea browser displays and the user clicks Cancel, the save is terminated. If
the user selects a name, FormsPublisher then triggers the onSaveNameSpecified event,
and calls any registered handler. This provides you with a means to validate the user’s
file name selection:
IWEventRegistry.addFormHandler("onSaveNameSpecified", nameChosen);
...
function nameChosen(path) {
// Determine if the path is valid.
...
if (nameOK) {
return true;
} else {
alert("The filename chosen is invalid ...");
return false;
}
}
The onSaveNameSpecified event handler is passed the vpath the user selected. The
event handler can examine this path and decide if it is acceptable, and return true to
continue the save. If the onSaveNameSpecified handler returns false, the save is
terminated.
NOTE
The event handler can also change the name of the DCR by calling
IWDCRInfo.setDCRName(), but because this function is asynchronous, it cannot use the
other methods in IWDCRInfo to check the properties of the file (see “DCR Information -
IWDCRInfo”).
At this point, the system has all the information necessary to save the form, and the data
has passed validation by FormsPublisher and by any custom user script function. When
the save completes, one final event, onSaveDone, is triggered:
IWEventRegistry.addFormHandler("onSaveDone", saveDone);
...
function saveDone(success) {
if (! success) {
alert("The save did not succeed ...");
}
}

The onSaveDone handler is passed a boolean argument indicating whether the save was
successful. The user script can alert the user as needed. Because it is the last step of the
save process, the onSaveDone handler does not have to return a value.
FormAPI also provides the IWDatacapture.save() method, which allows the you to
save the form without any user interaction. This method does not generate the onSave,
onSaveValid, or onSaveNameSpecified events. It also does not validate the form. It
enters the save process near the end, checking only if the DCR name has been specified.
If not (because this is a new DCR or because setDCRName(null) was called),
IWDatacapture.save() does nothing. Otherwise, the form is saved, and the onSaveDone
event is triggered.
Visibility and Read-Only

One of the most powerful features of FormAPI is the ability to dynamically change the
visibility or read-only state of an item. This lets you create forms that let the user edit or
view only those fields that are relevant in the current context.
NOTE
FormsPublisher provides a <readonly> item type that is distinct from the dynamic
read-only state introduced by FormAPI. The <readonly> type is no longer necessary
and is not supported by FormAPI (see “<readonly> vs setReadonly()”).
Use the setVisible() and the setReadOnly() methods of the IWItem object to change
the state of an item. Use the isVisible() and isReadOnly() methods to query the state
of an item.
An invisible item (made so by calling setVisible(false)) is completely absent on the

form. The user will not see the field, its contents, or its label. In addition, the field’s
entry in the navigation tree is removed.
Interwoven, Inc. 26
A read-only item is rendered exactly like a normal item, but the user is unable to change
its value (text or selections):
Figure 2 Normal versus Read-only Items
Normal Items Read-only Items
NOTE
FormsPublisher has no mechanism for recalling the visibility or read-only states of an
item when a DCR is reopened. That information exists only in the running user script
and is not written to the DCR. Unless the user script explicitly changes the state of an
item on load, it is visible and editable. For the same reason, view mode (which does not
enable FormAPI or load user scripts) always displays the contents of all the items in the
form, regardless of the visibility state that was set in edit mode.
Here are some examples:
To make the /a item invisible:

IWDatacapture.getItem("/a").setVisible(false);
To check the read-only state of the /b item:

readOnly = IWDatacapture.getItem("/b").isReadOnly();
More typically, you may want to make some fields invisible in response to other
selections. Consider an address entry form that is designed to accept both domestic and
international addresses. If the country field selection is set to USA, fields for state and
ZIP code should appear. For any other country, they should not be visible.

If the country field has the address /address/country, FormAPI can register an event
handler, countryChange(), on it for the onItemChange event. This function adjusts the
visibility of the state and ZIP code fields. FormAPI calls this function directly on start
up, so the initial state of the fields is set correctly.
function init() {
IWEventRegistry.addItemHandler("/address/country",
"onItemChange", countryChange);
countryChange(IWDatacapture.getItem("/address/country"));
}
The countryChange() function is passed the item object for the country field. It checks
if the value of the currently selected country is USA and sets the visibility of the state and
ZIP code fields accordingly. Finally, it forces a redraw to effect the changes:
function countryChange(item) {
var flag = item.getOptions()[item.getValue()].value == "USA";
IWDatacapture.getItem("/address/state").setVisible(flag);
IWDatacapture.getItem("/address/zip").setVisible(flag);
}
Constructions like this allow for the creation of interactive, customized forms that
significantly improve usability.
Validation and Highlight Mode

One of the most common requirements of any data entry form is validation. Validation
usually involves one or more of the following:
Ensuring that a required field is not blank.
Ensuring that the value of an unbounded field is valid (for example, that a phone
number consists of ten digits), by matching its contents against a regular expression.
A bounded control is a user interface element that restricts its input to a predefined
set of choices, like a selection list or radio button. An unbounded control is a text
field or textarea that lets the user enter free-form content.
Ensuring that the contents of the whole form, including relationships between
separate fields, make sense (for example, that the start date is not after the end date).
When the data a user enters fails validation, the attempt to save must be aborted and the
user must be notified which fields are invalid.
Interwoven, Inc. 28
FormsPublisher provides the means to specify validation rules of the first two categories
through the required and validation-regex item attributes in the DCT. For example, you
can specify that a phone number is required and must be entered in a standard format by
declaring the item like this:
<item name="phone">
<label>Phone Number</label>
<description>Enter the phone number (###-###-####)</description>
<text required="t"
validation-regex="^\d{3}-\d{3}-\d{4}$"
maxlength="12"/>
</item>
When FormsPublisher renders this item, it appends an asterisk to its label indicating that
it is required. If the user fails to enter a valid phone number and clicks the Save button,
an alert displays and FormsPublisher enters highlight mode. In this mode, all invalid
entries are marked with red labels, both on the form and in the navigation tree.
FormsPublisher remains in highlight mode until the user corrects the error and
successfully saves the form.
FormAPI enhances these capabilities by providing you with the ability to dynamically
query and change an item’s required state (with isRequired() and setRequired()) and
validation expression (with getRegex() and setRegex()). It also provides the means to
query and change the highlight mode of the form (with IWDatacapture methods
isHighlightMode() and setHighlightMode()).
NOTE
The description of an item, which appears in a frame directly above the form, is not
dynamically accessible by FormAPI. This is important to remember if the description
includes content entry instructions that may not be accurate if the validation expression
changes. In the example above, the description says Enter the phone number
(###-###-####). If the user script calls setRegex(/\d{10}/) to require the phone
number to be entered without dashes, the description is no longer accurate. This
situation is easily avoided by not relying on the description field for content entry
instructions that are variable, and by using alerts and dialogs to inform the user instead.
The form can enter highlight mode in two ways:

The form fails save validation and automatically enters highlight mode.
The user script calls IWDatacapture.setHighlightMode(true).
Highlight mode stays in effect (with all invalid items marked red since the last redraw)
until either the user requests a save and passes validation or the user script calls
IWDatacapture.setHighlightMode(false).
Normally, an item is considered valid if it meets its required state and validation
expression rules that were set by the required and validation-regex attributes in the
DCT or the setRequired() and setRegEx() in the user script. These are the rules that
FormsPublisher employs when performing save validation of the form.

Many times it is important to be able to mark an item valid or invalid without having to
change its required state or validation expression. This kind of validation checking falls
into the third category described at the beginning of the section—ensuring that the field
value makes sense in the context of the entire form. FormAPI provides the setValid()
method to override the other validation rules and directly declare an item valid or
invalid:
setValid(true) marks this item valid, regardless of its content or required/regex
rules. The item always passes save validation and will never be marked red in
highlight mode.
setValid(false) marks this item invalid, regardless of its content or
required/regex rules. The item always fails save validation and will always be
marked red in highlight mode.
setValid(null) turns off any override previously set on this item. Save validation
examines the required/regex rules on this item to determine if it is invalid.
The isValid() method returns the current validation state of the item. If the item was
explicitly marked with setValid(), that state is returned. Otherwise, the required/regex
rules are examined.
Like labels on dynamically inserted options (see “Getting and Setting Item Values”) and
visibility and read-only states (see “Visibility and Read-Only”), the user script must
restore any dynamically modified validation states or rules on load, or a reopened form
will behave differently from when it was last saved.
Examples
Here are some examples of dynamic validation:
To toggle the required state of the /a item:

item = IWDatacapture.getItem("/a");
item.setRequired(! item.isRequired());
To prevent FormsPublisher from flagging the contents of the /b item, regardless of what
was entered, register handlers for the onSave and onSaveDone events:
IWEventRegistry.addFormHandler("onSave", saveHandler);
IWEventRegistry.addFormHandler("onSaveDone", saveFinished);
The event handler overrides the validation state during the save process:
function saveHandler(item) {
IWDatacapture.getItem("/b").setValid(true);
}
function saveFinished(item) {
IWDatacapture.getItem("/b").setValid(null);
}
To ensure that the date in the /start field is before the date in the /end field, register a
handler on the onSaveValid event:
Interwoven, Inc. 30
The validateForm() function checks if the start date field is invalid:

// Assume that the form is valid.

var result = true;
// Get handles for the start and end date items.

var startItem = IWDatacapture.getItem("/start");
var endItem = IWDatacapture.getItem("/end");
// Create date objects for the start and end dates.

var startDate = Date.parse(startItem.getValue());
var endDate = Date.parse(endItem.getValue());
// Is the start date after the end date?

if (startDate.getTime() > endDate.getTime()) {
// Yes. Set the start date as invalid.

startItem.setValid(false);
// Go into highlight mode.

IWDatacapture.setHighlightMode(true);
// Inform the user of the error.

alert("Start date cannot be after end date.");
// Return false to terminate the save.

result = false;
}
return result;
}
It is important to return false from the validation, so that FormsPublisher aborts the
save request.
Remote Server Calls

FormAPI is client-side technology. The user scripts that the template designer writes are
loaded into the browser and executed by its JavaScript engine. There are many times,
however, when code in the user script needs to access resources on a remote server.
Most commonly, the user script needs to run a database query and use the results to set
the value of an item. The canonical example is the address entry form that automatically
populates the city and state fields after the user has entered the ZIP code. There is no
way the user script can include the entire city/state/ZIP database in the code; that
information is best obtained from a server.

FormAPI provides the callServer() method to make an HTTP request with a set of
attributes-value pairs. The request may take the form of either an HTTP POST or an
HTTP GET call. The target server (which can be any process that can handle an HTTP
request and make a response, such as a servlet or CGI) reads the request and returns
JavaScript code embedded in an HTML page. This page is loaded into a hidden frame,
distinct from the frame that contains the user script and FormAPI. FormsPublisher
provides a special parent.getScriptFrame() function to this hidden frame that returns
the user script frame. In this way, the code returned by the server coexists with the user
script and has full access to its methods and data.
NOTE
FormsPublisher also provides the cgi-callout mechanism to access remote resources
from the client form. The FormAPI callServer() method supersedes CGI callouts (see
“CGI Callouts”).
The callServer() method is asynchronous. A new thread is started with the HTTP
request and completes only when it finishes executing the code returned by the server.
The user script code that made the request continues executing immediately after the
call to callServer(). For this reason, callServer() is usually the last line of code in
an event handler; the logic “picks up” in the hidden frame after the post is complete.
Here is an example illustrating a typical city/state/ZIP code form:

IWEventRegistry.addItemHandler("/zip", "onItemChange", fillCityState);
The fillCityState() handler is a function that queries a remote server for city and
state:
function fillCityState(zipItem) {
if (zipItem.isValid()) {
var parameters = new Object();
parameters.zip = zipItem.getValue();
// Make an HTTP GET to the server.
callServer("http://myserver/getCityState", parameters, true);
}
}
The result from a call to the server (which will be given the request like
http://myserver/getCityState?zip=94086) returns code similar to this:
<html>
<head>
<script language="javascript">
// Get handle to the FormAPI/userscript frame.

api = parent.getScriptFrame();
// Set the city and state.

api.IWDatacapture.getItem("/city").setValue("Sunnyvale");
api.IWDatacapture.getItem("/state").setValue("CA");
</script>
Interwoven, Inc. 32
</head>
<body>
</body>
</html>
One of the hazards of making a remote server request is that it may take too long to
return. Worse, it may not return at all. To guard against this problem, a user script can
use the JavaScript setTimeOut() function to handle a request that does not return within
a specified amount of time. Before it calls the server, setTimeOut() is instructed to
execute an error handler function. The code that returns from the server cancels the
pending error handler call (if it is running, the request succeeded). If the server does not
return in time, the error handler is executed.
Adjust the user script fillCityState() function to set up the time out:
...
// Error handler called in 1 minute. Save ID in global variable
// for hidden frame to cancel if it succeeds.
timeout = setTimeOut("callServerFailed", 60000);
// Make an HTTP GET to the server.

callServer("http://myserver/getCityState", parameters, true);
...
Create a callServerFailed() function to handle the error case:

function callServerFailed() {
alert("ZIP code lookup failed. Be sure to enter city and state.");
}
Finally, modify the JavaScript returned from the server to cancel the time out:
...
// Get handle to the FormAPI/userscript frame.
api = parent.getScriptFrame();
// Cancel the pending time out.

clearTimeout(api.timeout);
...
This does not handle the case where the server is not down, but simply slow. In this
case, after one minute the user is prompted that the ZIP code lookup failed, but several
moments later may suddenly see the city and state fields automatically change. To guard
against this possibility, modify the callServerFailed() function to cancel the server
call:
function callServerFailed() {
alert("ZIP code lookup failed. Be sure to enter city and state.");
// Abort the request by sending a blank page to the hidden frame.

IWDatacapture.callServer("blank.html", new Object(), true);
}

This request cancels the previous request by making a new one to an empty file. This
illustrates an important point about the callServer() method: only one call can be
active at a time. Subsequent calls to callServer() will cancel any previous calls.
The location template included with FormsPublisher illustrates a complete example.
Auto-DCR Functionality
The Auto-DCR function enables unnamed DCRs to be saved with automatically
generated names. When this feature is used, the user does not need to provide a name for
the DCR that is being saved.
Auto-DCR naming:
Is applicable when saving a DCR using the Save or Finish buttons, but not when
saving with the Save As button (because this signifies intent to specify a name for
the DCR file).
Can be configured for a specific category and type.
Is turned off by default.
The Auto-DCR function uses an algorithm based on timestamps that returns unique file
names in the form iwDCRnumber_timestamp. This function may be replaced by a
user-written function that is used to automatically get the names of the saved DCR files.
See “Name Factory - IWNameFactory” on page 67 for more information.
NOTE
All DCR file names generated by Auto-DCR naming are relative to the data directory
of the specified category and type.
How FormAPI Changes FormsPublisher

Registering event handlers changes the behavior of FormsPublisher. Here are some
other important interactions between FormAPI and FormsPublisher.
Hidden vs. Invisible

A hidden item is one defined in the DCT with a <hidden> instance item. Its content is
like a <text> field; that is, it cannot have selections or options. FormAPI can set and
query the value of a hidden item.
Conversely, invisibility is a state of an item. An invisible item is any item that has been
made invisible by using the FormAPI method IWItem.setVisible(false). Unless
Interwoven, Inc. 34
setVisible(false) is called when the user script is first loaded, the item will be visible
when the user opens the form. Note that items that are not on the current page or that are
scrolled out of view are considered visible, even though the user cannot see them.
Hidden items and invisible text items appear to have similar behavior. Use hidden items
in templates to store a value that the user must never change or see, like internal ID
numbers. Use invisible items for fields that are only applicable under certain conditions.
NOTE
Because there is no FormAPI in view mode, all items, whether hidden or previously
invisible, are visible in view mode.
<readonly> vs setReadonly()
Before FormAPI was available, the only way to show uneditable content was to use the
<readonly> item instance. Data in a <readonly> item had to be text because
<readonly> items do not allow selections or options, and it was rendered as a simple
text string in the form.
Using FormAPI, any item may be designated read-only using

IWItem.setReadOnly(true). Non-text items, like radio buttons and check boxes, are
rendered just as they normally would be, but with disabled input controls.
The template designer can easily change the read-only item back to its editable state by
calling setReadOnly(false).
Because <readonly> items can be fully emulated by calling setReadOnly(true) on a

text item at startup, they are no longer required. FormAPI does not support <readonly>
items. It is anticipated that their use will be deprecated in future releases.
CGI Callouts
Before FormAPI was available, the only way to dynamically change the form was to use
a CGI callout, defined in the DCT using the <callout> element. An item with a CGI
callout is rendered with a button beside it. Clicking the button opens a new window that
the template designer can use to present the user with a dialog. The content of the new
window is specified in the url attribute of the <callout> element. This new window
then updates the data capture form.
NOTE
Before FormAPI was available, the url attribute of the <callout> subelement was
required. It is now optional.

With FormAPI, much of the need for the CGI callout is eliminated.The template
designer can achieve the same functionality more easily and with much greater
flexibility in a user script. A user script can open a new window by calling the browser’s
open() command, dynamically specifying any URL it needs. This new window can
access the user script code and FormAPI methods of its parent window by calling
opener().
There, are, however, two reasons why the <callout> element is still important to
FormAPI:
1. You may already have callouts that you need to reuse with templates that have user
scripts.
2. The <callout> element renders a button beside a form element. This is the only
way to get a simple button on the form that does not directly change the value of the
data (unlike a check box or radio button).
FormAPI supports callouts by:

Providing the onCallout event. This event is triggered for an item whenever the
user presses the callout button beside that item.
Making the url attribute of the <callout> element optional. Because the onCallout
handler can process the click, there may be no need for an actual callout.
If the onCallout event is registered and a url attribute is specified to the <callout>
element in the DCT, then the event handler is called first. If it returns true, the callout
specified in the url is called by opening a new window. If the event handler returns
false, the callout window is not opened.
In this way, FormAPI fully supports callouts, allowing them to be executed or not as
determined by the user script at runtime.
Note again that a <callout> element in the DCT is the only way to get a simple button
on the form. To have the button appear rendered by itself (and not beside any particular
input element) set the callout on a hidden item. For example, the DCT may look like
this:
<item name="myButton">
<hidden>
<callout label="My Button"/>
</hidden>
</item>
User script code may then define the button’s behavior:

function sayHello(item) {
alert ("Hello! You pressed the button!");
}
IWEventRegistry.addItemHandler("/myButton", "onCallout", sayHello);
If the buttons do not need to be on the same window as the template, user script code
can also write HTML to a new browser window to create a custom dialog with buttons,
links, and images.
Interwoven, Inc. 36
Chapter 3
FormAPI Reference
This chapter provides details about the various FormAPI objects. Before using these
objects, you should be aware of the following information.
There are eight different objects exposed in this API. These objects are:
API (page 38)
Data Capture Form (page 39)
Item (page 47)
Event Registry (page 58)
DCR Information (page 63)
Name Factory (page 67)
Page Generation (page 68)
Presentation Template (page 70)
Five of these objects, API, Datacapture, Event Registry, DCR Information and Name
Factory, are singletons—users access their methods from a single instance of the object
bearing the name of the class. Methods of the item object IWItem are accessed from a
particular instance of the item.
NOTES
All paths are relative to the data directory of the template.
For all methods that require a path, the path delimiter should be / (forward slash).

Chapter 3: FormAPI Reference
API object - IWAPI

The IWAPI object holds properties of FormAPI itself. This information can be used by
the user script to determine the capabilities of its environment.
string IWAPI.getTSTVersion ()
Returns the version of FormsPublisher.
Arguments:
None.
Returns:
A string representing the version of FormsPublisher.
string IWAPI.getVersion ()
Returns the version of the API.
Arguments:
None.
Returns:
A string representing the version of the API.
Interwoven, Inc. 38
Data Capture Form - IWDatacapture

The IWDatacapture object represents the data capture document. It contains methods
that pertain to the entire form.
It also defines constants that represent the buttons on the form. These may be used by
user script functions that register handlers to the onSave event (see “DCT Items -
IWItem”).
IWDatacapture.SAVE_BUTTON The Save button

IWDatacapture.SAVEAS_BUTTON The Save As button
IWDatacapture.SAVECLOSE_BUTTON The Finish button
IWDatacapture.PREVIEW_BUTTON The Preview button
IWDatacapture.GENERATE_BUTTON The Generate button
IWDatacapture.callServer (url, data, isGet)
Calls url with data using an HTTP POST or HTTP GET, as specified by isGet. The target
of the submit operation is a hidden frame. The response from the post should be
JavaScript that manipulates the form or creates and populates data structures.
The hidden frame where the response is rendered should not be considered a safe place
to hold data; data that spans multiple submit operations (including save) should be
relocated to the script frame:
var scriptFrame = parent.getScriptFrame();
scriptFrame.myData = "from the server";
Arguments:
url
The URL to post to.

data
A JavaScript object that contains a hash of name-value pairs.

isGet
Boolean indicating whether the data should be sent using an HTTP GET (true)
or an HTTP POST (false).
Returns:
Nothing.

IWDatacapture.close (confirmClose)
Closes the current window. Does not trigger the onClose event.
Arguments:
confirmClose
Boolean indicating if close() should behave like clicking the Close button, and
prompt the user to save or regenerate (if necessary) before closing.
Returns:
Nothing.
IWDatacapture.displayMessage (message)
Displays the given message in a frame at the bottom of the screen.
Arguments:
message
A string message. If null or omitted, the information frame displays the default
information.
Returns:
Nothing.
void IWDatacapture.enableImagePreview (enable)
Enables (or disables) display of thumbnail preview images for browse items whose
extension includes one of .gif, .jpg, .jpeg, .avi, .emf, .mov, .mpg, .png, .wmf, .xbm, or
.bmp.
This should be invoked immediately and not deferred until the onFormInit event.
Arguments:
enable
Boolean indicating if this item should be enabled (true) or not (false).
Returns:
Nothing.
Interwoven, Inc. 40
number IWDatacapture.getCurrentPageNumber ()
Returns the page number of the current page.
Arguments:
None.
Returns:
A number representing the page number of the current page. Page numbers start at
1.
string IWDatacapture.getDCRPath ()
Returns the vpath of the data content record. If no vpath was set, the empty string ("") is
returned.
Arguments:
None.
Returns:
The vpath of the data content record.
string IWDatacapture.getDCTPath ()
Returns the vpath to the data capture template.
Arguments:
None.
Returns:
The vpath to the datacapture template.
string IWDatacapture.getFormType ()
Returns the form type as determined by the data_category/data_type directory

structure in the templatedata directory.
Arguments:
None.
Returns:
The form type.

string IWDatacapture.getGroups ()
Returns the group(s) that the currently logged-in user is a member of.
Arguments:
None.
Returns:
An array of the names of the current user’s groups.
IWItem IWDatacapture.getItem (name)
Returns the IWItem object with the given name.
Arguments:
name
The XPath address (name) of the IWItem to be retrieved.
NOTE
If a data capture template uses tabs (through the <tab> element in
datacapture.cfg) you must include the tab’s name in the item address/xpath. See
“Addressing and Form Tabs” on page 14 for more information.
Returns:
An IWItem object that represents the replicant instance container and supports the
setVisible and isVisible operations. Returns null if the item cannot be found.
number IWDatacapture.getPageCount ()
Returns the number of pages in this form.
Arguments:
None.
Returns:
A number representing the number of pages in this form.
string IWDatacapture.getRole ()
This method is deprecated. Use IWDatacapture.getRoles () instead.
Interwoven, Inc. 42
string IWDatacapture.getRoles ()
Returns the role(s) that the currently logged-in user of this form has in the current
workarea.
Arguments:
None.
Returns:
An array of the current user’s role names.
IWItem[] IWDatacapture.getRootItems ()
Returns an array of IWItem objects representing all the items at the top level of the entire
form. Custom DTD templates always return an array of exactly one element because
there may be only one top-level node. Use getChildren() for the individual item to
iterate into a replicant or container.
Arguments:
None.
Returns:
An array of IWItem objects representing the items at the top level of the entire form.
Frame (top level of data capture form/parent).getScriptFrame ()
This function is defined at the top level of a data capture form. If this is being called
from JavaScript returned by callServer(), you will probably need to invoke it from the
parent object.
Returns the frame containing the API and user scripts. It is designed to be used in the
JavaScript returned by the callServer() method to access functions and variables in
the user script frame.
Be careful when using the returned object, as it is possible to completely delete the
contents of this frame and the user scripts in it.
Arguments:
None.
Returns:
The JavaScript frame object where the API and user script reside.

string IWDatacapture.getUser ()
Returns the currently logged-in user of this form.
Arguments:
None.
Returns:
A string representing the currently logged in user of this form. On a Windows
server, the returned name is in the form domain\user.
string IWDatacapture.getWorkarea ()
Returns the current workarea.
Arguments:
None.
Returns:
The current workarea.
IWDatacapture.gotoPage (pagenumber)
Redraws the form at the specified page.
Arguments:
pagenumber
A positive number representing the page to draw. Page numbers start at 1. An

invalid or missing argument does nothing.
Returns:
Nothing.
Interwoven, Inc. 44
boolean IWDatacapture.isHighlightMode ()
Determines whether the form is in highlight mode. In highlight mode, items that are
invalid as determined by isValid() have their labels highlighted in red.
A form may be in highlight mode because either 1) it entered it automatically after the
form failed save validation, or 2) an explicit call to setHighlightMode(true) was
made.
Arguments:
None.
Returns:
True if the form is in highlight mode, false if not.
boolean IWDatacapture.isModified ()
Determines whether the DCR has been modified.
Arguments:
None.
Returns:
True if the DCR has been modified (that is, should be saved), false if not.
IWDatacapture.save ()
Saves the current DCR if there is a name to save it to. Does not trigger onSave,
onSaveValid, or onSaveNameSpecified events. Does invoke onSaveDone event.
If no name is specified, either because it is a new DCR or because setDCRName(null)

was called, save() does nothing.
Arguments:
None.
Returns:
Nothing.

IWDatacapture.setHighlightMode (highlightMode)
Sets the current highlight mode. In highlight mode, items that are invalid (as determined
by isValid()) have their labels highlighted in red.
Highlight mode is set automatically if the form fails save validation.
Arguments:
highlightMode
Boolean indicating whether the form should be redrawn in highlight mode

(true) or not (false).
Returns:
Nothing.
IWDatacapture.setIsModified ()
Saves a DCR even if the form has not been modified. This feature is useful if the form
contains acceptable defaults and the DCR name is automatically determined by
FormAPI. In this situation, the user clicks Finish or Next without making any changes
to the form.
Arguments:
None.
Returns:
Nothing.
Interwoven, Inc. 46
DCT Items - IWItem

The IWItem object represents a DCT item and its form element. Its methods allow you to
query and manipulate the state of each item on the form.
Unlike the other objects in FormAPI, IWItem is not a singleton; each element has its
own IWItem instance. Where the following documentation refers to “this item,” it means
the IWItem instance in the current context.
IWItem.addInstance (index, [choice_name])
Inserts a new replicant instance at index, with choice_name as an optional argument for
“or” containers. Applies only to replicant containers.
Arguments:
index
A whole number of your choice for the index of the new instance. The index is
not zero-based. If index is passed as 0 or less, it is treated as if index=1. If
index is greater than the number of instances, it is appended to the end.
choice_name
For a choice or containers with combination =’or’, it is necessary to specify

which of the possible instances to insert. The instance is specified by the name
attribute of the child. This optional string value is ignored if the replicant is a
container with combination=’and’.
Returns:
IWItem of the instance added, or null if unable to complete the operation.
IWItem.addOption (option)
Adds an entry to the list of options for this item. This method applies only to <select>,
<checkbox>, and <radio> items.
Arguments:
option
The JavaScript Option object to add to this item. An invalid or missing

argument does nothing.
Returns:
Nothing.

boolean IWItem.deleteInstance (index)
Deletes the instance at index. Applies only to replicant containers.
Arguments:
index
The whole-number index of the instance to delete. The index is not zero-based.
It is ignored if index is passed as 0 or is greater than the number of current
instances.
Returns:
False if unable to complete the operation, or if the index argument is out of bounds.
IwItem IWItem.getChildByName (name)
Returns the instance of the immediate child with name.
Arguments:
name
Short name of a child item of a replicant, container, or replicant container.
Returns:
The first immediate child of the item whose name matches the name argument.
IWItem[] IWItem.getChildren ()
Returns an array of children items. Applies only to <container> and <replicant>

types.
Arguments:
None.
Returns:
An array of IWItem objects representing the children of this item or null if it does
not have children.
Interwoven, Inc. 48
string IWItem.getDescription ()
Returns the string representing the description of this item.
Arguments:
None.
Returns:
The string representing the description of this item.
string IWItem.getLabel ()
Returns the string representing the label for this item.
Arguments:
None.
Returns:
The the string representing the label for this item.
string IWItem.getName ()
Returns the XPath-like address of this item.
Arguments:
None.
Returns:
The XPath-like address of this item.
Option[] IWItem.getOptions ()
Returns the options for this item. This method applies only to <select>, <checkbox>,
and <radio> items.
Arguments:
None.
Returns:
An array of JavaScript Option objects representing the list of options in this select,
checkbox, or radio item, in order. Returns null if this item has no options.

RegExp IWItem.getRegex ()
Returns the validation regular expression associated with this item.
Arguments:
None.
Returns:
A JavaScript RegExp object representing the validation expression for this item, or
null if there is none.
string IWItem.getType ()
Returns the type of this item.
Arguments:
None.
Returns:
A string representing this item’s type. Possible values are:
textarea
text
radio
checkbox
select
hidden
browser
andreplicant
orreplicant
andcontainer
orcontainer
andreplicantcontainer
orreplicantcontainer
The string unknown is returned for unsupported item types (such as the <readonly>
item type).
Interwoven, Inc. 50
string, number, or number[] IWItem.getValue ()
Returns the value of this item. For <text> items, including <browser> and <hidden>
items, a string value is returned. For items with options, a number representing the index
(or an array indicating the indices, if this item supports multiple selections) is returned.
For all other items, including <replicants> and <containers>, this method returns
null.
Arguments:
None.
Returns:
String value for <text>, <textarea>, <browser>, or <hidden> items.
Number of selected index (zero-based) for single <select> and <radio> items.
Array of numbers of selected indices (zero-based) for multiple <select> and
<checkbox> items.
boolean IWItem.isCollapsed ()
Returns whether the replicant, container, or replicant container is collapsed.
Arguments:
None.
Returns:
True if this item is collapsed, false if the item is expanded.
boolean IWItem.isMultiSelect ()
Returns whether this item supports options with multiple selections.
Arguments:
None.
Returns:
True if this item is a multiple <select> or <checkbox>, false if not.

boolean IWItem.isReadOnly ()
Returns the value of the read-only flag for this item. This method is not related to the
<readonly> item type, which FormAPI does not support.
Arguments:
None.
Returns:
True if the read-only flag of this item is set, false otherwise.
boolean IWItem.isRequired ()
Returns whether this item is a required item.
Arguments:
None.
Returns:
True if this item is a required item, false if not.
boolean IWItem.isValid ()
Returns whether the value in this item is valid.
Arguments:
None.
Returns:
True if this item is valid, false if not. If setValid() has been called with true or
false, that value is returned. If setValid() has not been called or was called with
null, the system determines validity by checking the requirement status and regular
expression validation rule for this item.
boolean IWItem.isVisible ()
Returns the visibility state of this item.
Arguments:
None.
Returns:
True if this item has a true visibility state, false if it is invisible. Note that an item
can have a true visibility state and still not be seen on the screen. For example, it
may be on a different page or scrolled out of view.
Interwoven, Inc. 52
boolean IWItem.isVisualFormat ()
Returns whether or not this item is a <textarea> with a VisualFormat control.
Arguments:
None.
Returns:
True if this item is a VisualFormat control, false if not.
boolean IWItem.moveInstance (from_index, to_index)
Moves an instance from one index to another. No action is taken if the indexes evaluate
to equivalent values. Applies only to replicant containers.
Arguments:
from_index
The whole-number index of the instance to be moved. The index is not

zero-based. If index is passed as less than 1 or greater than the number of
current instances, it is interpreted as 1 or the last index, respectively.
to_index
A whole number of your choice for the index of the instance. The index is not
zero-based. If index is passed as less than 1, it is interpreted as 1. If the index is
greater than the number of current instances, the item at from_index is moved to
the last position.
Returns:
False if unable to complete the operation.
IWItem.removeOption (index)
Removes an option from the list of options for this item. This method applies only to
<select>, <checkbox>, and <radio> items.
Arguments:
index
The zero-based index of the option to remove. An invalid or missing argument

does nothing.
Returns:
Nothing.

IWItem.setCollapsed (boolean)
Makes a replicant, container, or replicant container collapsed or expanded.
Arguments:
None.
Returns:
Nothing.
IWItem.setDescription (text)
Sets the description displayed in ContentCenter for this item.
Arguments:
text
A string representing the item’s description.
Returns:
Nothing.
IWItem.setFocus ()
Sets the focus to this item. If this item is not on the current page, the form is first
redrawn at the correct page. setFocus() has no effect if this item is currently read-only.
Arguments:
None.
Returns:
Nothing.
IWItem.setLabel (text)
Sets the label displayed in ContentCenter for this item.
Arguments:
text
A string representing the item’s label.
Returns:
Nothing.
Interwoven, Inc. 54
IWItem.setOptions (options)
Sets the option list for this item. This method applies only to <select>, <checkbox>,
and <radio> items.
Arguments:
options
An array of JavaScript Option objects to set as the new list of options for this
item. An invalid or missing argument does nothing.
Returns:
Nothing.
boolean IWItem.setReadOnly (readonly, [optional recursive])
Sets the read-only property of this item. Depending on the value of recursive, it either
sets the readOnly attribute or recursively sets the readOnly property on all descendent
items. A read-only replicant container has all replicant buttons disabled, on both the
container and the instances themselves. This method is not related to the <readonly>
item type, which is unrelated to FormAPI.
Arguments:
readonly
Boolean indicating if this item should be read-only (true) or not (false).
Returns:
Nothing.
IWItem.setRegex (regex)
Sets the regular expression for validation of this item. This method is only valid for
<text>, <textarea>, <hidden>, and <browser> items.
Arguments:
regex
A JavaScript RegExp object to set as the validation expression. An invalid or

missing argument does nothing.
Returns:
Nothing.

IWItem.setRequired (required)
Sets whether this item should be required (empty value fails validation). Required items
are marked with an asterisk (*) in their label.
Arguments:
required
Boolean indicating if this item should be required (true) or not (false).
Returns:
Nothing.
IWItem.setValid (value)
Specifies whether the value in this item is valid. A true argument overrides results of
standard validity tests.
Arguments:
value
Value can have one of three values:

• true: Mark this item as valid. The isValid() method always returns true.
• false: Mark this item as invalid. The isValid() method always returns
false.
• null: Do not mark this item. The isValid() method determines validity by
checking the required status and validation regular expression.
Returns:
Nothing.
Interwoven, Inc. 56
IWItem.setValue (value)
Sets the value of this item.
This method does not apply to <replicant> or <container> items.
Arguments:
value
• For <text>, <textarea>, <browser>, and <hidden items>, value is a string

representing the new value.
• For single <select> and <radio> items, value is the number of the
zero-based index of the option to select.
• For multiple <select> and <checkbox> items, value is an array of numbers
of the zero-based indices of the options to select.
An invalid argument does nothing.
Returns:
Nothing.
IWItem.setVisible (visible)
Sets the visibility state of an item.
Arguments:
visible
True to make this item visible, false to hide it.
Returns:
Nothing.
string IWItem.toString ()
Displays debugging information, including type and name properties.
Arguments:
None.
Returns:
A descriptive string showing the type and name properties.

Event Registry - IWEventRegistry

The event registry is a singleton object provided by FormAPI that allows you to register
JavaScript functions to events. Each function must follow a specific signature dependent
on the event that it is handling.
A handler registered to a replicant is called whenever the specified event occurs on any
instance of that replicant.
FormAPI supports multiple event handlers, allowing the processing of multiple events
from multiple servers in the same form. For example, data from MediaBin and WorkSite
servers can now be used to populate the same data form.
Table 2 lists the events available to user scripts:
Table 2 Events Available to User Scripts

Example Event Handler
Event Description
Signature
onCallout Event triggered after the handle_onCallout(item)
user clicks an item’s If the callout also has a URL
cgi-callout button. attribute, it will be executed if
the event handler returns
true. item is the IWItem
object associated with the
callout that generated the
event.
onClose Event triggered by the Close handle_close()
or Finish button was The event handler should
clicked. return true if the close should
continue or false to cancel
the close.
onCollapseOrExpand Event triggered after the handle_collapse
user clicks on the Collapse (isCollapsed)
{...}
or Expand buttons.
OnGenerate Event triggered before a handle_generate(dcrPath)
form is generated. {...}
IWEventRegistry.addFormHa
ndler("OnGenerate",
handle_generate);
Where dcrPath is the location
of the DCR that will be
generated through a
presentation template.
Interwoven, Inc. 58
Table 2 Events Available to User Scripts (Continued)

Event Description
Signature
onItemChange Event triggered by a change handle_change(item)
in the value of the item. Where item is the IWItem
Custom handler will be object that generated the
called after the target item event.
has been updated with the
new value. The old value is
available as the
item.oldValue property, in
the format returned by
IWItem.getValue().
OnPreview Event triggered before a handle_preview() {...}
form is previewed. IWEventRegistry.addFormHa
ndler("OnPreview",
handle_preview);
OnReplicantAdded Event triggered after a handle_replicant_added
replicant is added. (item) {...}
Where item is the IWItem
representing the replicant
instance that was added.
OnReplicantBeforeAdd Event triggered before a allow_replicant_add(item,
replicant is added (so that index) {...}
IWEventRegistry.addItemHa
by returning false in the ndler ("/contact/phone",
handler, the operation can "OnReplicantBeforeAdd",
be cancelled before the allow_replicant_add);
action is taken). Where item is the IWItem
container that will be added,
and index is a whole number
specifying where the new
replicant will be inserted.
OnReplicantBeforeMove Event triggered before a allow_replicant_move(item
replicant is moved to a new , from_index, to_index)
{...}
index (so that by returning IWEventRegistry.addItemHa
false in the handler, the ndler ("/contact/phone",
operation can be cancelled "OnReplicantBeforeMove",
before the action is taken). handle_replicant_move);
Where item is the IWItem
container that will be moved,
and from_index and to_index
are whole numbers specifying
the replicant’s current and
future indexes, respectively.
OnReplicantDelete Event triggered before a handle_replicant_delete
replicant instance is deleted (item) {...}
IWEventRegistry.addItemHa
(so that by returning false ndler("/contact/phone",
in the handler, the operation "OnReplicantDelete",
can be cancelled before the handle_replicant_delete);
action is taken). Where item is the IWItem
representing the replicant that
will be deleted.

Table 2 Events Available to User Scripts (Continued)

Event Description
Signature
OnReplicantMoved Event triggered after a handle_replicant_moved
replicant is assigned to a (item, old_index) {...}
new index. Where item is the IWItem
instance that was moved, and
old_index is a whole number
specifying the item’s original
index.
onSave Event triggered by user handle_save(button)
requesting save the DCR. Where button is the button
This event is triggered at the (IWDatacapture.SAVE,
beginning of the save. IWDatacapture.SAVEAS, etc.)
that initiated this save request.
The event handler should
return true if the save should
continue or false to cancel
the save.
onSaveNameSpecified Event triggered when the handle_saveNameSpecified
user responds to the (path)
workarea browser to select a Where path is the full vpath
name for this DCR. The the user selected. The event
workarea browser is handler should return true if
presented when the current the save should continue or
DCR has no name during a false to cancel the save.
user-initiated save or if the
user pressed Save As, after
the form has passed save
validation.
onSaveValid Event triggered after the handle_saveValid()
form is validated against the The event handler should
item required status and return true if the save should
regular expression. This continue or false to cancel
step happens after onSave the save.
and before
onSaveNameSpecified.
onSaveDone Event triggered when a save handle_savedone
has finished. (saveSuccessful)
Where saveSuccessful is a
boolean that indicates whether
the save succeeded. This value
is not affected by any errors
that might have been
generated by workflow (such
as, unable to add file to task
within a CGI task).
Interwoven, Inc. 60
IWEventRegistry.addFormHandler (eventname func)
Specifies an event handler for a form event, replacing any previously registered function
(for this event.
Arguments:
eventname
A string representing the name of the event this handler will intercept (see
preceding table).
func
A function that is the event handler for this event.
Returns:
Nothing.
IWEventRegistry.addItemHandler (itemname eventname func)
Specifies a event handler for an event on a particular item, replacing any previously
registered function for this event on this item. Accepts special path expressions
registering default item handlers that are children of replicants. These expressions look
very similar to the XPath-like expressions passed to IWDatacapture.getItem(), except
that they contain no index expressions such as [1]. They are useful for registering event
handlers that will be invoked by default for all indexes of a replicant.
For example, suppose that each phone replicant has a child text field named cell. One
can register an item handler on all the cell fields for all instances of phone with an
expression such as /contact/phone/cell. More specific calls for specific instances can
be made, for example /contact/phone[1]/cell. Any calls to
IWEventRegistry.addItemHandler() with a more specific path expression will
override the default.
Arguments:
itemname
A string identifying a particular item by its XPath address.

eventname
A string representing the name of the event this handler will intercept (see
preceding table).
func
A function that is the event handler for this event.
Returns:
Nothing.

IWEventRegistry.removeFormHandler (eventname)
Removes the event handler for the given event from the form.
Arguments:
eventname
A string representing the name of the event.
Returns:
Nothing.
IWEventRegistry.removeItemHandler (itemname eventname)
Removes the event handler for the given event from the given item.
Arguments:
itemname
A string representing a particular item.

eventname
A string representing the name of the event.
Returns:
Nothing.
Interwoven, Inc. 62
DCR Information - IWDCRInfo

The IWDCRInfo object represents the DCR file. It contains methods that allow the user
script to obtain meta information about the DCR file, such as file size and modified date.
It also defines constants that represent the status of the last setDCRName(). These are
used in comparing the following values returned by getStatus().
IWDCRInfo.AVAILABLE DCR file information is available.

IWDCRInfo.UNAVAILABLE DCR file information is unavailable.
IWDCRInfo.PENDING The request for DCR file information from the
server has not returned yet.
IWDCRInfo.ERROR The request for DCR file information from the
server timed out and was cancelled.
NOTE
All of the query methods in this object rely on the most recent setDCRName() to have
populated the information field when the DCR was most recently named. setDCRName()
is implicitly called when:
The form is first loaded.
The form is saved either by the user or by calling IWDatacapture.save().
string IWDCRInfo.getDCRName ()
Returns the name of the DCR.
Arguments:
None.
Returns:
The current name of the DCR, or null if the DCR is currently unnamed.
number IWDCRInfo.getFileSize ()
Returns the size of the DCR file (in bytes).
Arguments:
None.
Returns:
A number representing the size of the file in bytes. Returns null if the DCR is
currently unnamed.

Date IWDCRInfo.getModificationDate ()
Obtains the last modification date of the DCR file.
Arguments:
None
Returns:
A JavaScript Date object which contains the last modified date of the DCR file.
Returns null if the DCR is currently unnamed.
string IWDCRInfo.getOwner ()
Determines the owner of the file. In the TeamSite file system, the owner of the file is the
last user to have modified the file.
Arguments:
None.
Returns:
A string representing the owner of the file. Returns null if the DCR is currently
unnamed.
number IWDCRInfo.getStatus ()
Determines whether meta information is available. Should be checked before calling the
other methods in this object.
Arguments:
None
Returns:
IWDCRInfo.AVAILABLE: information is available; use the other methods in this
object to obtain it.
IWDCRInfo.UNAVAILABLE: there is no information available for the current DCR
name (probably because the file does not exist).
IWDCRInfo.PENDING: the request to the server to retrieve information for the
current DCR name has not completed yet.
IWDCRInfo.ERROR: the request to the server to retrieve information for the
current DCR name did not return in time (1 minute) and has been cancelled.
Interwoven, Inc. 64
NOTE
When checking for the status of IWDCRInfo object, do not use a tight infinite loop.
Instead, use the setTimeOut() method in Java to poll for the status change. For
example:
function checkInfoStatus()
{
if (IWDCRInfo.getStatus == IWDCRInfo.PENDING)
{
//Check again in 2 sec
setTimeout("checkInfoStatus()",2000);
}
else
{
//Do what you were about to do with the status.
}
}
boolean IWDCRInfo.isModifiedInWA ()
Determines whether the DCR file is marked as modified in the TeamSite workarea
(different from staging).
Arguments:
None.
Returns:
True if the DCR file is marked as modified in the TeamSite workarea, false if it is
not. Returns null if the DCR is currently unnamed.

boolean IWDCRInfo.setDCRName (path callback)
Sets the name of the DCR to the given path and initiates a server request for information
about that file. The path is relative to the current template’s data directory.
NOTE
Do not specify a path with references to the parent directory (..). Doing so can lead to
unpredictable results.
While the request is in progress, its status may be tracked with the getStatus() method,
as described above.
Because it involves an HTTP POST, this is an asynchronous call that spawns a new
thread. To synchronize execution with the completion of this method, specify a callback
function. The callback executes when the request completes or times out (1 minute).
If a request is still pending and setDCRName() is called again, the original request is
cancelled and the new one is initiated.
If path is null, the DCR name is explicitly unset. The callback is not executed if the
path is null. The system prompts the user for a DCR name when the Save button is
clicked.
setDCRName() is implicitly called when the form is opened, and when the form is saved.
Therefore, calls to IWDatacapture.save() followed immediately by a call to
setDCRName() are not safe because when the save completes, the new name will be lost.
Arguments:
path
A string that contains the new path name of the DCR.

callback
A function to execute when the implicit request to refresh the DCR information
returns or times out.
Returns:
Nothing.
Interwoven, Inc. 66
Name Factory - IWNameFactory

The IWNameFactory generates names for saved DCR files and its methods allow you to
set a function to generate names for a saved DCR file.
The dcr-autonaming attribute of the viewoptions element in the templating.cfg file

must be set for these calls to function. Refer to the TeamSite FormsPublisher Developer’s
Guide.
NOTE
The file paths that the function generator returns must be relative to the data directory
of the relevant data capture form. A default function is provided that uses a simple
algorithm based on timestamps to ensure unique file names.
void IWNameFactory.setAutoDCRPathGenerator (function)
Sets the automatic DCR path generator function to be equal to the functionname
argument. This user-written automatic DCR path generator function needs to return a
name relative to the “data” directory of the relevant category and type to which this
DCR belongs.
Arguments:
function
The function will automatically return the name of the file that should be used to save
the current DCR.
function IWNameFactory.getAutoDCRPathGenerator ()
Gets the user-set automatic DCR path generator function.
Returns:
The user-set automatic DCR path generator function. If a user has not previously set
the automatic DCR path generator function, then null will be returned.

Page Generation - IWPageGeneration

The IWPageGeneration object provides access to some properties of the Form Settings
dialog. Setters modify the underlying form settings, so that the Form Settings dialog will
reflect the changes made here.
IWPresentationTemplate IWPageGeneration.getPresentationTemplate()
Gets the presentation template to be used for previewing and generating.
Arguments:
None.
Returns:
An IWPresentationTemplate object of the current presentation template. Null is
returned if there is no current presentation template.
IWPresentationTemplate
IWPageGeneration.getValidPresentationTemplates ()
Gets an array of valid presentation templates for this data content record.
Arguments:
None.
Returns:
An array of presentation templates.
string IWPageGeneration.getOutputFile ()
Gets the output file name to be used for previewing and generating.
Arguments:
None.
Returns:
The string path representing the templatedata relative path of the file. The empty
string ("") is returned if the output file has not been set.
Interwoven, Inc. 68
IWPageGeneration.setOutputFile (filename create_directories)
Sets the output file name to be used for previewing and generating. This modifies the
corresponding form settings option.
Arguments:
filename
The string path representing the templatedata relative path of the file.
create_directories
Creates the directory paths for filename if they do not exist (optional).
Returns:
Nothing.
boolean IWPageGeneration.setPresentationTemplate (template)
Sets the presentation template to be used for previewing and generating. This modifies
the corresponding form settings option.
Arguments:
template
The IWPresentationTemplate object of a valid presentation template.
Returns:
False if the presentation template is invalid.

Presentation Template - IWPresentationTemplate

IWPresentationTemplate is a wrapper object for presentation templates. All access to
IWPresentationTemplate objects is through the following methods:
IWPageGeneration.getValidPresentationTemplates ()
IWPageGeneration.getPresentationTemplate ()
string IWPresentationTemplate.getExtension ()
Gets the extension for the presentation template.
Arguments:
None.
Returns:
The extension attribute of the presentation template as defined in the
templating.cfg file.
string IWPresentationTemplate.getName ()
Gets the name of the presentation template.
Arguments:
None.
Returns:
The name of the presentation template as defined in the templating.cfg file.
string IWPresentationTemplate.getPath ()
Gets the workarea-relative path to the presentation template. To get the full vpath to the
presentation template, concatenate this result to IWDatacapture.getWorkarea ().
Arguments:
None.
Returns:
The workarea-relative path of the presentation template.
Interwoven, Inc. 70
Appendix A
Sample User Scripts
The following sections contain descriptions of the sample user scripts that are
packaged with FormAPI.
The Contact User Script

This example allows the user to create a basic phone book entry. The user enters a
contact name and one or more phone numbers for that contact. The phone number is
validated after the user enters the value and moves out of the field. A confirmation
window displays when the user saves the form.
This script illustrates the following:

How an event handler for a replicant field is invoked for the replicant instances.
How to loop through all the fields on the form including the replicant instances.
The sample script directory also contains:

datacapture.cfg. The data capture template for this example.
contact.dtd. The custom DTD for this example.
contact.js. The user script for this example.
data. A directory for storing generated data records.
presentation. A directory of presentation templates that go with this example.
The Script
The following is contact.js, the user script for this example.
// File contact.js
// Userscript for the 'userscript/contact' Templating FormAPI example.
//
//-----------------------------------------------------------------------
// The init() function is executed at the end of this script.

// It register registers the event handlers.

Appendix A: Sample User Scripts
function init() {
// Register a function to popup a confirmation window on save
// *after* the form has passed basic validation.
IWEventRegistry.addFormHandler("onSaveValid", displayContact);
// Register a function to perform Phone number validation. Note

// that an event handler registered on a replicant will be
// triggered for the individual replicant instances.
IWEventRegistry.addItemHandler("/contact/phone", "onItemChange",
checkPhoneNumbers);
}
// This function is called when the user tries to save the form. It
// displays the contact details and request confirmation.
function displayContact() {
// Build the confirmation message from the current form values.
var message = "Do you want to save following contact details:\n";
message += "\nName: " +

IWDatacapture.getItem("/contact/name").getValue();
// Loop through existing phone items, append contents to the

// confirmation message.
var i = 1;
var phoneItem;
while (phoneItem = IWDatacapture.getItem("/contact/phone[" + i + "]"))
{
message += "\nPhone(" + i++ + "): " + phoneItem.getValue();
}
// Continue with the save if the user approves confirmation.
return confirm(message);
}
// checkPhoneNumbers() is called every time the user changes a phone

// number field.
function checkPhoneNumbers(phoneItem) {
// Is this phone number valid?
if (! phoneItem.isValid()) {
Interwoven, Inc. 72
// No. Use a regular expression to extract this item's

// ordinality from its name.
var i = phoneItem.getName().match(/\d+/)[0];
// Warn the user.
alert("Please specify a valid value for phone #" + i + ".");

phoneItem.setFocus();
}
}
// Call the initialization routine on load.

The DCT
The following is datacapture.cfg, the data capture template that invokes contact.js.
<?xml version="1.0" encoding="UTF-8"?>

<data-capture-requirements
dtd-system-identifier="http://localhost/iw/contact.dtd"
dcr-validation="none" name="">
<ruleset name="dct">
<root-container combination="and" location="contact" name="contact">
<item max="1" min="1" name="name" pathid="name">
<label>Name</label>
<description>Enter the contact name</description>
<text required="t" validation-regex="^\D+$" maxlength="50" />
</item>
<item max="6" min="1" name="phone" pathid="phone">
<label>Phone</label>
<description>Enter the phone number (###-###-####)</description>
<text required="t" validation-regex="^\d{3}-\d{3}-\d{4}$"
maxlength="12"/>
</item>
<description>Enter contact details</description>
</root-container>
<script language="javascript" location="template-type"
src="contact.js"/>
</ruleset>

The Contact DTD Element


<!ELEMENT contact (name,phone+)>

<!ELEMENT name (#PCDATA)>

<!ELEMENT phone (#PCDATA)>
The Location User Script

This example displays a list of regions and cities in a region. A list of cities is
dynamically populated whenever the user changes region.

An event handler to make a CGI call to compute a list of cities in a region.
A callback function to populate the city field.
A callback function invoked from a CGI script.

datacapture.cfg. The data capture template for this example
location.dtd. The custom DTD for this example.
getLocations.cgi. CGI perl script to return a list of countries for a given region.
Installation
The Location user script requires the following installation steps:
1. Copy the getLocations.cgi to iw-home/httpd/iw-bin.
2. Edit the first line of getLocations.ipl to point to the path for the iwperl interpreter
and replace '__IW_HOME__' with the location of iw-home.
3. Change the dtd-system-identifier attribute in the datacapture.cfg file to point
to the correct location of location.dtd.
Interwoven, Inc. 74
The Script
The following is the user script for this example.
<script>
<![CDATA[
function init() {
// Register a function to validate data before for gets submitted.
IWEventRegistry.addItemHandler("/location/region", "onItemChange",
fetchLocations);
// Set the City list for the selected region(if any)
var regionItem = IWDatacapture.getItem("/location/region");
var cityItem = IWDatacapture.getItem("/location/city");
var myOptions = cityItem.getOptions();
fetchLocations(regionItem,
cityItem.getOptions()[parseInt(cityItem.getValue())].value);
}
function fetchLocations(item, defaultCity) {

var params = new Object();
var myOptions = item.getOptions();
params.region = myOptions[parseInt(item.getValue())].value;
params.defaultCity = defaultCity;
//alert the user that an external call is being made.

IWDatacapture.displayMessage("Retrieving locations in " +
myOptions[parseInt(item.getValue())].text + "...");
top.hiddenFrameRunning = true;
var server = window.location.hostname;

IWDatacapture.callServer("http://"+server+"/iw-bin/getLocations.cgi",
params);
}
function populateLocations(locations) {
//Clear the message display...
IWDatacapture.displayMessage();
var locationsItem = IWDatacapture.getItem("/location/city");
locationsItem.setOptions(locations);
}
//Now do the initialization...

]]>
</script>

The DCT
The following is datacapture.cfg, the data capture template that invokes the above
script.
NOTE
For this example the script is contained in the datacapture.cfg file.

dtd-system-identifier="http://localhost/iw/location.dtd" dcr-
validation="accept-invalid" name="">
<root-container combination="and" location="location" name="location">
<item max="1" min="1" name="region" pathid="region">
<label>Region</label>
<description>Geography/region.</description>
<select>
<option selected="t" value="NorthAmerica" label="North
America"/>
<option value="SouthAmerica" label="South America"/>
<option value="AsiaPac" label="Asia Pacific"/>
<option value="EMEA" label="Europe Middle East Asia"/>
</select>
</item>
<item max="1" min="1" name="city" pathid="city">
<label>City</label>
<description>City where the job resides.</description>
<select>
<option selected="t" value="Sunnyvale" label="Sunnyvale, CA"/>
<option value="Bathesda" label="Bathesda, NC"/>
<option value="NewYork" label="New York City, NY"/>
<option value="Vancouver" label="Vancouver, Canada"/>
</select>
</item>
</root-container>
<script>

</script>
</ruleset>
Interwoven, Inc. 76
The Location DTD Element



<!ELEMENT location (region,city)>
<!ELEMENT region (#PCDATA)>
<!ELEMENT city (#PCDATA)>
The Organization User Script

This example displays a drop down list of departments from which the user can select a
department and provide the description for it. When the input is saved, a DCR name is
automatically selected to match the department name. If the file already exists and is
owned by a different user, a confirmation dialog displays.

Use of the IWDCRInfo object to set or query the DCR associated with this form.
Automatic naming of the DCR based on the content entered.
Protection that changes made by another user (in case of shared workareas) are not
inadvertently overwritten.

organization.dtd. The custom DTD for this example.
organization.js. The user script for this example.
The Script
The following is organization.js the user script for this example.

// It register registers the event handlers.
function init() {
// Register a function to handle Save.
IWEventRegistry.addFormHandler("onSave", saveHandler);
// Register a function to change the DCR name based on the department.

IWEventRegistry.addItemHandler("/organization/department",
"onItemChange", departmentHandler);
// Call the departmentHandler() on load to set the initial status.
departmentHandler(IWDatacapture.getItem("/organization/department"));
}
// The departmentHandler() function sets the DCR named based on the

// currently selected department.
function departmentHandler(item) {
// Get the department name.
var department = item.getOptions()[item.getValue()].value;
// Is the current DCR name different from the department?
var dcrName = IWDCRInfo.getDCRName();

if (dcrName != department) {
// Yes - set the DCR name to the department name. This is an

// asynchronous call - but at this time we are not interested
// in the return values, so we specify a null callback
// function.
IWDCRInfo.setDCRName(department, null);
}
}
// This function is called when user saves the form. It sets the DCR
// name, if not set already. It also ensures that someone else's
// changes are not being inadvertently overwritten (which can happen
// in shared workareas).
function saveHandler() {
var result;
// Before calling IWDCRInfo methods, always check the status.
switch (IWDCRInfo.getStatus()) {
case IWDCRInfo.AVAILABLE:
// We have information on this DCR avaiable, so we can

// check a few extra things.
Interwoven, Inc. 78
if (IWDCRInfo.isModifiedInWA() &&
IWDCRInfo.getOwner() != IWDatacapture.getUser()) {
// If it's been changed by another user, prompt to confirm.
var message = "DCR was modified by another user.";

message += "\nFile details are:\n";
message += "\nSize: " + IWDCRInfo.getFileSize();
message += "\nOwner: " + IWDCRInfo.getOwner();
message += "\nLast modified: " +
IWDCRInfo.getModificationDate();
message += "\n\nDo you still want to save?" ;
result = confirm(message);
} else {
// Otherwise, we're in great shape.
result = true;
}
break;
case IWDCRInfo.PENDING:
// The query for information on this DCR hasn't returned yet.

// Let the user decide if they want to proceed with the save.
var message = "The form will be saved to the file: \"" +

IWDCRInfo.getDCRName() + "\".\n\n";
message += "The system is still waiting for information about this
file.\n\n";
message += "You may Cancel and try again in a few moments,\n";
message += "or press OK to continue with the save."
result = confirm(message);
break;
case IWDCRInfo.UNAVAILABLE:
default:
// There's no information available on the current DCR name,

// most likely because it doesn't exist. Proceed with the save.
result = true;
}
return result;
}

The DCT
The following is datacapture.cfg, the data capture template that invokes
organization.js.

dtd-system-identifier="http://localhost/iw/organization.dtd"
dcr-validation="none" name="">
<root-container combination="and" location="organization"
name="organization">
<item max="1" min="1" name="department" pathid="department">
<label>Department</label>
<select>
<option selected="t" value="ENG" label="Engineering"/>
<option value="MKT" label="Marketing"/>
<option value="SLS" label="Sales"/>
<option value="IS" label="Information Systems"/>
<option value="FAC" label="Facilities"/>
</select>
</item>
<item max="1" min="1" name="description" pathid="description">
<label>Description</label>
<textarea />
</item>
<description>Organization/Department.</description>
</root-container>
src="organization.js"/>
</ruleset>
The Organization DTD Element


<!ELEMENT organization (department, description)>
<!ELEMENT department (#PCDATA)>
<!ELEMENT description (#PCDATA)>
Interwoven, Inc. 80
The Position User Script

This example allows the user to create a basic job posting. The user can select a job title
and position type (temporary or permanent). Depending on their selections, different
fields are shown, for example, for temporary positions, the hourly rate and
hours-per-week fields become visible and required. For permanent positions, the
yearly salary field is visible and required. In addition, the yearly salary field's
requirements vary with the title of the position (executives must earn 7-digit salaries,
etc.). A confirmation window is displayed when the user saves the form.

Use of the displayMessage() function to communicate with the user.
An event handler to make certain fields visible and required based on the value of
other field(s).
An event handler to change the validation regex of a field depending on the value of
another field.

position.dtd. The custom DTD for this example.
position.js. The user script for this example.
The Script
The following is position.js the script for this example.
// File position.js
// Userscript for the 'userscript/position' Templating FormAPI example.
//
//-----------------------------------------------------------------------
------

// It register registers event handlers, and calls them to
// set the initial state of the form.
function init() {
// Register callback handlers for changes in the values of

// position type and title.
IWEventRegistry.addItemHandler("/position/type",
"onItemChange", typeHandler);

IWEventRegistry.addItemHandler("/position/title",
"onItemChange", titleHandler);
// Register a function to validate the form before save.

// This is a form-level validation that will occur *after*
// individual fields pass regex/required validation.
// To set the initial state of the form, call the event

// handlers now.
typeHandler(IWDatacapture.getItem("/position/type"));
titleHandler(IWDatacapture.getItem("/position/title"));
}
// The typeHandler() function changes the form based on the currently

// value of the 'type' field. It is passed a reference to the 'type'
// form item.
function typeHandler(typeItem) {
// If this is a temporary position, make the 'hours' and 'rate'

// fields required and visible, and the 'yearly' field optional
// and hiddden. Do the opposite for full-time positions.
var flag = isPositionTemporary(typeItem);
setItemStatus (IWDatacapture.getItem("/position/hours"), flag);

setItemStatus (IWDatacapture.getItem("/position/rate"), flag);
setItemStatus (IWDatacapture.getItem("/position/yearly"), ! flag);
// Turn off highlight mode. If the user entered invalid data, and
// then attempted to save, highlight mode is automatically turned
// on. If at this point they decide to change the position type,
// we shut off highlight mode so fields that were previously
// hidden don't appear to be the cause of the validation failure.
IWDatacapture.setHighlightMode(false);
// setItemStatus() is a helper function used by typeHandler(). It

// changes the visibility, required state, and the value of the
// specified item.
function setItemStatus(item, status) {

item.setVisible(status);
item.setRequired(status);
Interwoven, Inc. 82
// If we're hiding this item and making it optional, clear

// its value. This prevents irrelevant data from being saved
// in the DCR, and avoids validation errors in hidden fields.
if (! status) {
item.setValue("");
}
}
// The titleHandler() function changes the input requirements for the

// 'yearly' field based on the current value of the 'title' field. It
// is passed a reference to the 'title' item.
function titleHandler(titleItem) {
// We only bother changing the input requirements of the 'yearly'

// field if it's visible (which is the case if this is a full-time
// position).
var yearlyItem = IWDatacapture.getItem("/position/yearly");

if (yearlyItem.isVisible()) {
// Get the actual string value of the 'title' field by looking

// up the selected option.
var title = titleItem.getOptions()[titleItem.getValue()].value;
// Is this an executive position?
if (title == "CEO" || title == "COO" ||

title == "CTO" || title == "CIO") {
// Yes, executive position - require a hefty salary.
yearlyItem.setRegex(/^[1-9]\d{6,9}$/);
var message = "Yearly compensation for executives must be at
least $1,000,000.";
} else {
// Non-executive position: salary is modest.
yearlyItem.setRegex(/^[1-9]\d{2,4}$/);
var message = "Yearly compensation range is $100-$99,999.";
}
// Display the compensation limits message.
IWDatacapture.displayMessage(message);

// Make the message go away after 5 seconds.
setTimeout("IWDatacapture.displayMessage()", 5000);
}
}
// Validate the form before it gets saved. Ensure that number of

// "hours" for hourly positions is less than 50 per week. Show a
// confirmation window with position details.
// Is this a temporary position?
var typeItem = IWDatacapture.getItem("/position/type");

if (isPositionTemporary(typeItem)) {
// Yes. Is the number of hours over 50?

var hoursItem = IWDatacapture.getItem("/position/hours");
if (parseInt(hoursItem.getValue()) > 50) {
// Yes. Show a warning, return focus to the hours item.
alert("Number of hours per week may not be over 50.");

hoursItem.setFocus();
// Return false to abort the save.
return false;
}
}
// Either have a valid temporary position or a yearly position.

// Put up a confirmation message.
var message = "Do you want to save the following position:\n";
var titleItem = IWDatacapture.getItem("/position/title");

var title = titleItem.getOptions()[titleItem.getValue()].text;
message += "\nTitle: " + title;
var type = typeItem.getOptions()[typeItem.getValue()].text;

message += "\nType: " + type;
if (isPositionTemporary(typeItem)) {
var rate = IWDatacapture.getItem("/position/rate").getValue();
message += "\nHourly rate: " + rate;
var hours = IWDatacapture.getItem("/position/hours").getValue();
message += "\nWeekly hours: " + hours;
} else {
Interwoven, Inc. 84
var salary = IWDatacapture.getItem("/position/yearly").getValue();

message += "\nSalary: " + salary;
}
// Continue with the save if the user approves confirmation.
return confirm(message);
}
// isPositionTemporary() uses a reference to the 'type' field to

// determine if this position is temporary or full-time.
function isPositionTemporary (typeItem) {

return (typeItem.getOptions()[typeItem.getValue()].value == "T");
}
The DCT
The following is datacapture.cfg, the data capture template that invokes
position.js.

<data-capture-requirements dtd-system-identifier=
"http://localhost/iw/position.dtd" dcr-validation="none" name="">
<root-container combination="and" location="position" name="position">
<item max="1" min="1" name="title" pathid="title">
<label>Job title</label>
<select>
<option selected="t" value="ENG" label="Software Engineer"/>
<option value="MGR" label="Engineering Manager"/>
<option value="DIR" label="Engineering Director"/>
<option value="CIO" label="Chief Information Officer"/>
<option value="CEO" label="Chief Executive Officer"/>
<option value="COO" label="Chief Operating Officer"/>
<option value="CTO" label="Chief Technology Officer"/>
</select>
</item>
<item max="1" min="1" name="type" pathid="type">
<label>Fulltime/Temporary</label>
<radio>
<option selected="t" value="F" label="Full time"/>
<option value="T" label="Temporary"/>
</radio>

</item>
<item max="1" min="1" name="rate" pathid="rate">
<label>Hourly Rate</label>
<description>Hourly rate (required for temporary positions only)
</description>
<text maxlength="4" validation-regex="^\d+$" />
</item>
<item max="1" min="1" name="hours" pathid="hours">
<label>Hours Per Week</label>
<description>Number of hours per week(required for temporary
positions only)</description>
<text maxlength="2" validation-regex="^[0-9]+$"></text>
</item>
<item max="1" min="1" name="yearly" pathid="yearly">
<label>Yearly Salary</label>
<description>Job Listing(required for permanent positions only)
</description>
<text maxlength="10" validation-regex="^\d{3,5}$" />
</item>
<description>Job Listing</description>
</root-container>
src="position.js"/>
</ruleset>
The Position DTD Element


<!ELEMENT position (title, type, rate, hours, yearly)>

<!ELEMENT title (#PCDATA)>

<!ELEMENT type (#PCDATA)>

<!ELEMENT rate (#PCDATA)>

<!ELEMENT hours (#PCDATA)>

<!ELEMENT yearly (#PCDATA)>
Interwoven, Inc. 86
Index
A DTD
changes to 11
addFormHandler 61
dynamic options 19
addInstance 47
addItemHandler 61
addOption 18, 47 E
addressing 13 eableImagePreview 40
syntax 14 errata 8
using item 15 error handling
API version 38 server time-out 33
event handlers 21, 58
B onSave 24
registering 13
buttons
removing 62
defining 39
specifying 61
EventRegistry 58
C events 59
callServer 32, 39 available to user scripts 58
CGI callouts 35 onCallout 36, 58
close 40 onClose 58
contact user script 71 onCollapseOrExpand 58
OnGenerate 58
onItemChange 22, 59
D OnPreview 59
data capture template OnReplicantAdded 59
path 41 OnReplicantBeforeMove 59
DCR OnReplicantDelete 59
file size 63 OnReplicantMoved 60
generate names 67 onSave 23, 60
information 63 onSaveDone 25, 60
meta information 64 onSaveNameSpecified 25, 60
modification date 64 onSaveValid 24, 60
modified 45, 65 when triggered 21
name 63, 66
obtaining information 63
owner 64
path 41
path generator 67
saving 45, 67
saving unchanged 46
DCT
path 41
debugging 57
deleteInstance 48
displayMessage 40

Index
F getValue 18, 51
Form Settings getVersion 38
modify 68 getWorkarea 44
form type gotoPage 44
obtaining 41 groups 42
FormAPI
changes to FormsPublisher 34 H
forms
highlighted 46 handler 21
items in 43
items on 47 I
methods for 39 instances
redrawing 44 moving 53
validation 24 invalid items
FormsPublisher version 38 highlighting 45
frame isCollapsed 51
obtaining 43 isHighlightMode 45
isModified 45
G isModifiedInWA 65
isMultiSelect 51
getAutoDCRPathGenerator 67
isReadOnly 26, 52
getChildByName 48
isRequired 52
getChildren 48
isValid 30, 52
getCurrentPageNumber 41
isVisible 26, 52
getDCRName 63 items
getDCRPath 41 children 48
getDCTPath 41 collapsed 51
getDescription 49 multiple selections 51
getExtension 70 name 49
getFileSize 63 options 47, 49
getFormType 41 read-only 55
getGroups 42 removing options 53
getItem 42, 50 required 52, 56
getLabel 49 setting description 54
getModificationDate 64 setting focus 54
getName 49, 70 setting label 54
getOptions 18, 49 setting value of 57
getOutputFile 68 type of 50
getOwner 64 valid 52
getPageCount 42 value of 51
getPath 70 visible 52, 57
getPresentationTemplate 68 VisualFormat 53
getRegex 50 IWAPI 38
getRoles 43 IWDatacapture 15, 19, 39
getRootItems 43 IWDCRInfo 63
getScriptFrame 43 constants 63
getStatus 64 IWEventRegistry 15, 21, 58
getTSTVersion 38 IWItem 26, 47
getUser 44 IWNameFactory 67
getValidPresentationTemplates 68 IWPageGeneration 68
IWPresentationTemplate 70
Interwoven, Inc. 88
Index
L iscCollapsed 51
labels isHighlightMode 45
highlighted in red 45, 46 isModified 45
lists of options 47 isModifiedInWA 65
location user script 74 isMultiSelect 51
isReadOnly 26, 52
isRequired 52
M isValid 30, 52
message isVisible 26, 52
displaying 40 isVisualFormat 53
methods moveInstance 53
addFormHandler 61 removeFormHandler 62
addInstance 47 removeItemHandler 62
addItemHandler 61 removeOption 18, 53
addOption 18, 47 save 45
callServer 32, 39 setAutoDCRPathGenerator 67
close 40 setCollapsed 54
deleteInstance 48 setDCRName 66
displayMessage 40 setDescription 54
enableImagePreview 40 setFocus 54
getAutoDCRPathGenerator 67 setHighlightMode 46
getChildByName 48 setIsModified 46
getChildren 48 setLabel 54
getCurrentPageNumber 41 setOptions 18
getDCRName 63 setOutputFile 69
getDCRPath 41 setPresentationTemplate 69
getDCTPath 41 setReadOnly 26, 55
getDescription 49 setRegex 55
getExtension 70 setRequired 56
getFileSize 63 setValid 30
getFormType 41 setValue 18, 57
getGroups 42 setVisible 26, 57
getItem 42, 50 toString 57
getLabel 49 moveInstance 53
getModificationDate 64
getName 49, 70
getOptions 18, 49
O
getOutputFile 68 objects
getOwner 64 IWAPI 38
getPageCount 42 IWDatacapture 15, 19, 39
getPath 70 IWDCRInfo 63
getPresentationTemplate 68 IWEventRegistry 15, 21
getRegex 50 IWItem 26, 47
getRoles 43 IWNameFactory 67
getRootItems 43 IWPageGeneration 68
getScriptFrame 43 IWPresentationTemplate 70
getStatus 64 returning 42
getTSTVersion 38 onCallout 36, 58
getUser 44 onClose 58
getValidPresentationTemplates 68 onCollapseOrExpand 58
getValue 18, 51 OnGenerate 58
getVersion 38 onItemChange 22, 59
getWorkarea 44 OnPreview 59
gotoPage 44 OnReplicantAdded 59

Index
OnReplicantBeforeAdd 59 S
OnReplicantBeforeMove 59 save 45
OnReplicantDelete 59 script tag 11
OnReplicantMoved 60 server
onSave 23, 60 time-out 33
onSaveDone 25, 60 setAutoDCRPathGenerator 67
onSaveNameSpecified 60 setCollapsed 54
onSavenameSpecified 25 setDCRName 66
onSaveValid 24, 60 setDescription 54
options setFocus 54
IWEventRegistry 58 setHighlightMode 46
removing 53 setIsModified 46
organization user script 77 setLabel 54
output file 69 setOptions 18
outputfile 68 setOutputFile 69
setPresentationTemplate 69
P setReadOnly 26, 55
page number setRegex 55
obtaining 41 setRequired 56
pages setValid 30
number of 42 setValue 18, 57
paths setVisible 26, 57
absolute 14
position user script 81 T
presentation template 68, 69, 70
extension 70 thumbnails
name 70 displaying 40
path 70 toString 57
previewing 68, 69
U
R URL 39
read-only 26 user 42, 43
example 27 groups 42
read-only flag 52 obtaining name 44
read-only items 55 obtaining workarea 44
redraw roles 43
specified page 44 user script
regular expressions 50, 55 contact 71
removeFormHandler 62 location 74
removeItemHandler 62 location of 11
removeOption 18, 53 naming guidelines 13
replicants organization 77
adding 47 position 81
collapsing 54
deleting 48
expanding 54
required items 52, 56
roles 43
Interwoven, Inc. 90
Index
V
validation 50, 52, 55
dynamic 30
form 24
save 30
version
API 38
FormsPublisher 38
visibility 26, 52, 57
VisualFormat control 53
W
window
close 40

Index
Interwoven, Inc. 92

Ts 671sp1 Fpapi v01 en

Caricato da

Informazioni sul documento

Descrizione originale:

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

Ts 671sp1 Fpapi v01 en

Caricato da

Copyright:

Formati disponibili

FormsPublisher:

Interwoven, ConfirmSite, ContentServices, ControlHub, DataDeploy, DeskSite, FileSite, iManage,

FormsPublisher: FormAPI Developer’s Guide

Forms Publisher: FormAPI Developer’s Guide 3

IWItem IWDatacapture.getItem (name) . . . . . . . . . . . . . . . . . . . . . ............... 42

Event Registry - IWEventRegistry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Forms Publisher: FormAPI Developer’s Guide 5

FormsPublisher FormAPI allows a template designer, to create forms that dynamically

Table 1 Notation Conventions

Forms Publisher: FormAPI Developer’s Guide 7

Table 1 Notation Conventions

This guide also uses the following conventions:

FormsPublisher FormAPI allows you, as a template designer, to create forms that

Some of the things you can do with FormAPI include:

Forms Publisher: FormAPI Developer’s Guide 9

Some important things to note about FormAPI:

By providing an interface to FormsPublisher, a new world of possibilities is opened to

The DCT <script> tag

The language attribute defaults to javascript. Currently, FormAPI has a JavaScript

You may specify a user script in either of two ways:

Forms Publisher: FormAPI Developer’s Guide 11

The src attribute is the URL of the target, for example

then specifying <script location="template-type" src="hello.js" would be

Forms Publisher: FormAPI Developer’s Guide 13

Addressing and Form Tabs

This is necessary because a tab is structurally like a FormsPublisher container, and

So the corresponding DCT snippet might look like:

The address for the street item is /state/city/street.

Using Item Addresses

Event handlers on items are registered through IWEventRegistry.addItemHandler()

Forms Publisher: FormAPI Developer’s Guide 15

In the above example, node c is a replicant, while node e is not.

Example 1: Container Addresses

For this DCT:

Example 2: Replicant Addresses

For this DCT:

<item name="d" pathid="d">

Examples of addresses for some items:

Example 3: Mixed Content Addresses

For this DCT:

Addresses for items are:

 The j item under the second instance of MixedContent

Forms Publisher: FormAPI Developer’s Guide 17

Example 4: Addressing Parents and Siblings

For this DCT:

To get the sibling item that corresponds to the element f:

Getting and Setting Item Values

 removeOption() removes an Option from a select list by specifying its index.

For example, to set the value of the /a text item to hello:

To select the third option in the /b radio button:

To select the second and third check boxes of the /c item:

To get the label of the selected option of the /d select item:

A user script may add Boston to the list:

Forms Publisher: FormAPI Developer’s Guide 19

Restoring Dynamic Options

with bos selected.

There are several ways to avoid this problem:

Use the methods of the IWEventRegistry object (see “Event Registry -

Forms Publisher: FormAPI Developer’s Guide 21

Figure 1 Save Events Process

Forms Publisher: FormAPI Developer’s Guide 23

Forms Publisher: FormAPI Developer’s Guide 25

The j item under the second instance of MixedContent

removeOption() removes an Option from a select list by specifying its index.