FormsPublisher: FormAPI Developer s Guide Release 6.5

Transcription

1 FormsPublisher: FormAPI Developer s Guide Release 6.5

2 Interwoven, Inc. All rights reserved. No part of this publication (hardcopy or electronic form) may be reproduced, translated into another language, 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, TeamSite, Content Networks, OpenDeploy, MetaTagger, DataDeploy, DeskSite, imanage, MailSite, MediaBin, MetaCode, MetaFinder, MetaSource, OpenTransform, Primera, TeamPortal, TeamXML, TeamXpress, VisualAnnotate, WorkKnowledge, WorkDocs, WorkPortal, WorkRoute, 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, EP / ATRA / BELG / DENM / FINL / FRAN / GBRI / GREC / IREL / ITAL / LUXE / NETH / PORT / SPAI / SWED / SWIT # , US # 6,480,944, US# 5,845,270, US #5,384,867, US #5,430,812, US #5,754,704, US #5,347,600, AUS #735365, GB #GB , US #5,845,067, US #6,675,299, US #5,835,037, AUS #632333, BEL #480941, BRAZ #PI , CAN #2,062,965, DENM / EPC / FRAN / GRBI / ITAL / LUXE / NETH / SPAI / SWED / SWIT #480941, GERM # , JAPA # , NORW #301860, 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,845,270, US #5,923,785, US #5,982,938, US #5,790,131, US #5,721,543, US #5,982,441, US #5,857,036, GERM # or other patents pending application for Interwoven, Inc. This Interwoven product utilizes third-party components under the following copyrights with all rights reserved: Copyright 1997 Eric Young; , Apache Software Foundation ( Copyright 1999, ExoLab Group; Copyright , Intalio, Inc. If you are interested in using these components for other purposes, contact the appropriate vendor. Interwoven, Inc th Ave. Sunnyvale, CA Printed in the United States of America Release 6.5 Part # October 2004

3 Table of Contents Chapter 1: Overview 7 Chapter 2: Using FormAPI 9 The DCT <script> tag Addressing Addressing Syntax Using Item Addresses Addressing Examples Getting and Setting Item Values Restoring Dynamic Options Empty Options Events onitemchange Save Events Visibility and Read-Only Validation and Highlight Mode Remote Server Calls Auto-DCR Functionality How FormAPI Changes FormsPublisher Hidden vs. Invisible <readonly> vs setreadonly() CGI Callouts Chapter 3: FormAPI Reference 35 API object - IWAPI string IWAPI.getTSTVersion () string IWAPI.getVersion () Data Capture Form - IWDatacapture IWDatacapture.callServer (url, data, isget) IWDatacapture.close (confirmclose) IWDatacapture.displayMessage (message) void IWDatacapture.enableImagePreview (enable) number IWDatacapture.getCurrentPageNumber () string IWDatacapture.getDCRPath () string IWDatacapture.getDCTPath () string IWDatacapture.getFormType () IWItem IWDatacapture.getItem (name) number IWDatacapture.getPageCount () string IWDatacapture.getRole () IWItem[] IWDatacapture.getRootItems () Frame (top level of data capture form/parent).getscriptframe () string IWDatacapture.getUser () string IWDatacapture.getWorkarea () IWDatacapture.gotoPage (pagenumber) boolean IWDatacapture.isHighlightMode () boolean IWDatacapture.isModified ()

4 IWDatacapture.save () IWDatacapture.setHighlightMode (highlightmode) IWDatacapture.setIsModified () DCT Items - IWItem IWItem.addInstance (index, [choice_name]) IWItem.addOption (option) boolean IWItem.deleteInstance (index) IwItem IWItem.getChildByName (name) IWItem[] IWItem.getChildren () string IWItem.getName () Option[] IWItem.getOptions () RegExp IWItem.getRegex () string IWItem.getType () string, number, or number[] IWItem.getValue () IWItem.isCollapsed () boolean IWItem.isMultiSelect () boolean IWItem.isReadOnly () boolean IWItem.isRequired () boolean IWItem.isValid () boolean IWItem.isVisible () boolean IWItem.isVisualFormat () boolean IWItem.moveInstance (from_index, to_index) IWItem.removeOption (index) IWItem.setCollapsed (boolean) IWItem.setFocus () IWItem.setOptions (options) boolean IWItem.setReadOnly (readonly, [optional recursive]) IWItem.setRegex (regex) IWItem.setRequired (required) IWItem.setValid (value) IWItem.setValue (value) IWItem.setVisible (visible) string IWItem.toString () Event Registry - IWEventRegistry IWEventRegistry.addFormHandler (eventname func) IWEventRegistry.addItemHandler (itemname eventname func) IWEventRegistry.removeFormHandler (eventname) IWEventRegistry.removeItemHandler (itemname eventname) DCR Information - IWDCRInfo string IWDCRInfo.getDCRName () number IWDCRInfo.getFileSize () Date IWDCRInfo.getModificationDate () string IWDCRInfo.getOwner () number IWDCRInfo.getStatus () boolean IWDCRInfo.isModifiedInWA () boolean IWDCRInfo.setDCRName (path callback) Name Factory - IWNameFactory void IWNameFactory.setAutoDCRPathGenerator (function) function IWNameFactory.getAutoDCRPathGenerator () FormsPublisher: FormAPI Developer s Guide

5 Page Generation - IWPageGeneration IWPresentationTemplate IWPageGeneration.getPresentationTemplate() IWPresentationTemplate.getName[] IWPageGeneration.getValidPresentationTemplates () string IWPageGeneration.getOutputFile () IWPageGeneration.setOutputFile (filename create_directories) boolean IWPageGeneration.setPresentationTemplate (template) Presentation Template - IWPresentationTemplate string IWPresentationTemplate.getExtension () string IWPresentationTemplate.getName () string IWPresentationTemplate.getPath () Appendix A: Sample User Scripts 67 The Contact User Script The Script The DCT The Contact DTD Element The Location User Script Installation The Script The DCT The Location DTD Element The Organization User Script The Script The DCT The Organization DTD Element The Position User Script The Script The DCT The Position DTD Element Index 83 5

6 6 FormsPublisher: FormAPI Developer s Guide

7 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 content 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. 7

8 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 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, 3rd ed, by David Flanagan, O'Reilly and Associates, 1998.! 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. In this way, the user experience of the person entering content is completely under your control. It also means that faulty usage of FormAPI never manifests itself as an error message or dialog. In most cases, the API simply ignores a function call with a bad argument. 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. 8 FormsPublisher: FormAPI Developer s Guide

9 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 one of two changes that the FormAPI enhancements make to the previous data capture template DTD (datacapture5.0.dtd): <!ELEMENT ruleset (label?, description?, script*, (%items;)*)>... <!ELEMENT script (#PCDATA)> <!ATTLIST script language CDATA "javascript" location (webserver template-type) CDATA "webserver" src CDATA #IMPLIED > Note: The other change was making the url attribute of the <cgi-callout> subelement optional; see CGI Callouts. As this snippet from the new 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 only has a JavaScript binding. 9

10 Using FormAPI You may specify a user script in either of two ways:! 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 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 src="hello.js" would be sufficient. You can use the webserver location type to access content that is on the same TeamSite server but in a different location than the template type directory by using the /iw-mount URL prefix: <script src="/iw-mount/default/main/somebranch/edition/someedition/somedirectory/ hello.js"/> 10 FormsPublisher: FormAPI Developer s Guide

11 Addressing 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 called init(). The last line of the user script calls this function to perform initialization when the frame is executed by the browser. There is no requirement that the function be called init. The JavaScript code is simply executed as it is loaded, as it would in any browser frame. 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. 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 ( 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 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. 11

12 Using FormAPI 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. 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); 12 FormsPublisher: FormAPI Developer s Guide

13 Addressing 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); This is called the prototype path for all c instances. A prototype can only be used in registering event handlers for replicants. It cannot be used in finding items. 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"> <item name="section" location="section"> <text required="t" maxlength="100"/> </item> </container> The address for the item Section would be /Story/Section. Example 2: Replicant Addresses For this DCT: <data-capture-requirements name="example"> <ruleset name="example">... <container name="a" combination="and" min="0" max="unbounded"> <item name="c" pathid="c"> <text/> </item> <item name="d" pathid="d"> <text/> </item> </container>... </ruleset> </data-capture-requirements> Examples of addresses for some items: " 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. 13

14 Using FormAPI 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="l_pcdata" pathid="l"> <text/> </item> <item name="j" pathid="j"> <text/> </item> </container>... </ruleset> </data-capture-requirements> 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]/l_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> </data-capture-requirements> The following userscript code returns the item object that corresponds to the element e: item = IWDatacapture.getItem("/b/e"); 14 FormsPublisher: FormAPI Developer s Guide

15 Getting and Setting Item Values 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 zerobased 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.! 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; 15

16 Using FormAPI 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. 16 FormsPublisher: FormAPI Developer s Guide

17 Getting and Setting Item Values 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. Because FormsPublisher uses the empty string to represent the case of no selection, options must never have empty values. 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. 17

18 Using FormAPI 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). 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. 18 FormsPublisher: FormAPI Developer s Guide

19 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. 19

20 Using FormAPI Save Events The save process is more complicated because it involves several steps: 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. 20 FormsPublisher: FormAPI Developer s Guide

21 Events 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. 21

22 Using FormAPI 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..."); 22 FormsPublisher: FormAPI Developer s Guide

23 Visibility and Read-Only 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. 23

24 Using FormAPI A read-only item is rendered exactly like a normal item, but the user is unable to change its value (text or selections): 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); IWDatacapture.redraw(); 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 24 FormsPublisher: FormAPI Developer s Guide

25 Validation and Highlight Mode 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); IWDatacapture.redraw(); 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. 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 25

26 Using FormAPI 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 26 FormsPublisher: FormAPI Developer s Guide

27 Validation and Highlight Mode 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()); IWDatacapture.redraw(); 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); 27