Description

This method adds a namespace declaration to the node it is called on. Each namespace is defined in the form using the XML xmlns namespace declaration as shown in these two sample declarations:

   xmlns:xfdl="http://www.ibm.com/xmlns/prod/XFDL/7.7" 
   xmlns:custom="http://www.ibm.com/xmlns/prod/XFDL/Custom"

Each namespace declaration defines a prefix and a URI for the namespace. In the samples shown, the prefix for the XFDL namespace is xfdl and the URI is http://www.ibm.com/xmlns/prod/XFDL/7.7. The prefix for the custom namespace is custom and the URI is http://www.ibm.com/xmlns/prod/XFDL/Custom.

Tags within the form are assigned specific namespaces by using the defined prefix. For example, to declare that an option is in the custom namespace, use the prefix custom as shown:

   <field sid="testField">
      <custom:custom_option>value</custom:custom_option>
   </field>

Method

void addNamespace(
   String uri,
   String prefix
);

Parameters

http://www.ibm.com/xmlns/prod/XFDL/7.7

Returns

Nothing. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

The sample function adds a new namespace to the form that is passed in. It also adds a namespace with the prefix "myspace" to the PAGE1.FIELD1 node on the form.

function AddNamespace(theForm) {
  var s;
  var fieldNode;

  s = "--- Results of addNamespace test ---\n";
  theForm.addNamespace("http://www.example.com/xmlns/newspace", "news");
  s += " Namespace added to form.\n";

  fieldNode = theForm.dereferenceEx(null, "PAGE1.FIELD1", 0, 
              FormNodeP.UFL_ITEM_REFERENCE, null);
  if(fieldNode == null) {
    s += " Could not locate FIELD1 node.\n";
  } else {
     fieldNode.addNamespace("http://www.example.com/xmlns/myspace", "myspace");
     s += " Namespace added to PAGE1.FIELD1.\n";
  }
  alert(s);
}

--- Results of addNamespace test ---
 Namespace added to form.
 Namespace added to PAGE1.FIELD1.

Description

Method

void addOnBlur (
   Function handler
);

Parameters

Returns

Nothing. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Notes

Example

The sample code adds an onBlur event handler to BUTTON1. The event handler is given the name button1OnBlur, but you can use any name that you want. The event handler displays the type of event and the local name of the source node.

function registerButtonEvent(theForm) {
  var buttonNode;
  var s;
  
  s = "- Results of registerButtonEvent function call -\n";
  buttonNode = theForm.dereferenceEx(null, "PAGE1.BUTTON1", 0, 
               FormNodeP.UFL_ITEM_REFERENCE, null);
  if(buttonNode == null) {
    s += " Could not find BUTTON1 on the form.\n";
  } else {
    buttonNode.addOnBlur(button1OnBlur);
    s += " function button1OnBlur registered.\n";
  }
  alert(s);

}

function button1OnBlur(xfdlEvent) {
   alert(xfdlEvent.type);
   alert(xfdlEvent.source.getLocalName());
}

Description

Method

void addOnChange (
   Function handler
);

Parameters

Returns

Nothing. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Notes

Example

The sample code adds an onChange event handler to BUTTON1. The event handler is given the name button1OnChange, but you can use any name that you want. The event handler displays the type of event and the local name of the source node.

function registerButtonEvent(theForm) {
  var buttonNode;
  var s;
  
  s = "--- Results of registerButtonEvent function call ---\n";
  buttonNode = theForm.dereferenceEx(null, "PAGE1.BUTTON1", 0, 
               FormNodeP.UFL_ITEM_REFERENCE, null);
  if(buttonNode == null) {
    s += " Could not find BUTTON1 on the form.\n";
  } else {
    buttonNode.addOnChange(button1OnChange);
    s += " Function button1OnChange registered.\n";
  }
  alert(s);
}

function button1OnChange(xfdlEvent) {
   alert(xfdlEvent.type);
   alert(xfdlEvent.source.getLocalName());
}   

Description

Method

void addOnClick (
   Function handler
);

Parameters

Returns

Nothing. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Notes

Example

The sample code adds an onClick event handler to BUTTON1. The event handler is given the name button1OnClick, but you can use any name that you want. The event handler displays the type of event and the local name of the source node.

function registerButtonEvent(theForm) {
  var buttonNode;
  var s;
  
  s = "--- Results of registerButtonEvent function call ---\n";
  buttonNode = theForm.dereferenceEx(null, "PAGE1.BUTTON1", 0, 
               FormNodeP.UFL_ITEM_REFERENCE, null);
  if(buttonNode == null) {
    s += " Could not find BUTTON1 on the form.\n";
  } else {
    buttonNode.addOnClick(button1OnClick);
    s += " function button1OnClick registered.\n";
  }
  alert(s);
}

function button1OnClick(xfdlEvent) {
  alert(xfdlEvent.type);
  alert(xfdlEvent.source.getLocalName());
}

Description

Method

   void addOnFocus (
   Function handler
);   

Parameters

Returns

Nothing. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Notes

function button1OnFocus(xfdlEvent) {
   alert(xfdlEvent.type);
   alert(xfdlEvent.source.getInfoEx(FormNodeP.IDENTIFIER));
}

Example

The sample code adds an onFocus event handler to BUTTON1. The event handler is given the name button1OnFocus, but you can use any name that you want. The event handler displays the type of event and the local name of the source node.

function registerButtonEvent(theForm) {
  var buttonNode;
  var s;
  
  s = "--- Results of registerButtonEvent function call ---\n";
  buttonNode = theForm.dereferenceEx(null, "PAGE1.BUTTON1", 0, 
               FormNodeP.UFL_ITEM_REFERENCE, null);
  if(buttonNode == null) {
    s += " Could not find BUTTON1 on the form.\n";
  } else {
    buttonNode.addOnFocus(button1OnFocus);
    s += " function button1OnFocus registered.\n";
  }
  alert(s);
}

function button1OnFocus(xfdlEvent) {
   alert(xfdlEvent.type);
   alert(xfdlEvent.source.getLocalName());
}

Description

This method checks the format of either all items on the form or all items on a single page. It returns a list of items that have non valid formats.

Method

   FormNodeP[] checkValidFormats( );

Parameters

There are no parameters for this method.

Returns

The list of all nodes with non valid formats. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

The sample code takes the root node of the form as input, calls checkValidFormats, then displays the results in a JavaScript alert window.

function testCheckValidFormats(theForm) {
  var nodes = new Array();
  var s;
  
  s = "--- Results of checkValidFormats test ---\n";
  nodes = theForm.checkValidFormats();
  if(nodes == null || nodes.length == 0) {
    s += " All nodes have valid formats.\n";
  } else {
    s += " These nodes have non valid formats:\n"
    for(i = 0; i < nodes.length; i++) {
      s += "  Node: " + nodes[0].getReferenceEx(null, null, null, false) + "\n";
    }
  }
  alert(s);
}   

--- Results of checkValidFormats test ---
  These nodes have non valid formats:
   Node: PAGE1.FIELD1

Description

Use this method to create a new cell item for a combobox, list, or popup. The createCell method adds one new cell to a group on a page in the form. Note that this method can only assign a name to the new cell; it cannot set the value of the cell. To set the value of a cell, you must use the setLiteralByRefEx method.

This method is called from a page level node, and creates the new cell in that page. Note that you cannot call this method from the global page node.

Method

FormNodeP createCell(
   String cellName,
   String groupName
);

Parameters

Returns

A FormNodeP containing the new cell. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

This sample code makes two calls to createCell to add two new cells to the same group. Each call to createCell is followed by a call to setLiteralByRefEx to set the value for the new cell.

function testCreateCell(theForm) {
  var newCell;
  var pageNode;
  var s;
  
  s = "--- Results of createCell test ---\n";
  pageNode = theForm.dereferenceEx(null, "PAGE1", 0,
             FormNodeP.UFL_PAGE_REFERENCE, null);
  if(pageNode == null) {
    s += "Could not find PAGE1 on the form.";
  } else {
    newCell = pageNode.createCell("ORANGE_CELL", "POPUP1_GROUP");
    newCell.setLiteralByRefEx(null, "value", 0, null, "Orange");
  	
    newCell = pageNode.createCell("PURPLE_CELL", "POPUP1_GROUP");
    newCell.setLiteralByRefEx(null, "value", 0, null, "Purple");
  	
    s += " Cells added to the popup item.";
  }
  alert(s);
}  

--- Results of createCell test ---
 Cells added to the popup item.

Description

This method deletes the specified digital signature in the form. For security reasons, the form must meet certain criteria before this is allowed. None of the following should be locked by another signature: the signature, its descendants, the associated signature button, and its signer option. If these criteria are met, then the signature's locks are removed, the signature item is deleted, and the signer of the associated signature button is set to empty ("").

Method

void deleteSignature(
    FormNodeP signatureItem 
);  

Parameters

Returns

Nothing. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Notes

If the signatureItem item contains a layoutinfo option, deleteSignature will not remove the entire signature from the form. Instead, the signature item and the layoutinfo option will remain. To completely delete the signature item, you must delete the remaining nodes manually by using destroy to delete the signature item.

Example

function testDeleteSignature(theForm) {
  var s;
  var node;
  
  s = "--- Results of deleteSignature test ---\n";
  node = theForm.dereferenceEx(null, "PAGE1.BUTTON1_SIGNATURE_405824760", 0,
         FormNodeP.UFL_ITEM_REFERENCE, null);
  if(node == null) {
    s += " Could not find PAGE1.BUTTON1_SIGNATURE_405824760 on the form.\n";
  } else {
    theForm.deleteSignature(node);
    s += " The signature has been deleted.\n";
  }
  alert(s);
}   

--- Results of deleteSignature test --
 The signature has been deleted.

Description

Use this function to locate a particular FormNodeP, to locate a cell in a particular group, or to locate a data item in a particular datagroup.

Method

   FormNodeP dereferenceEx(
      String scheme,
      String reference,
      Number referenceCode,
      Number referenceType,
      FormNodeP NSNode
   );

Parameters

Returns

The FormNodeP defined by the reference string or null if the referenced node does not exist and FormNodeP.UFL_SEARCH_AND_CREATE is not specified. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Notes

FormNodeP

Before you decide which FormNodeP to use this method on, be sure you understand the following:

1. The FormNodeP supplied can never be more than one level in the hierarchy above the starting point of the reference string. For example, if the reference string begins with an option, then the FormNodeP can be no higher in the hierarchy than an item.
2. If the FormNodeP is at the same level or lower in the hierarchy than the starting point of the reference string, the method will attempt to locate a common ancestor. The method will locate the ancestor of the FormNodeP that is one level in the hierarchy above the starting point of the reference string. The method will then attempt to follow the reference string back down through the hierarchy. If the reference string cannot be followed from the located ancestor (for example, if the ancestor is not common to both the FormNodeP and the reference string), the function will fail. For example, given a FormNodeP that represents field_1 and a reference of field_2, the function will access the page node above field_1, and will then try to locate field_2 below that node. If the two fields are not on the same page, the function fails.
3. dereferenceEx does not support the XForms scheme.

Creating a reference string

For general information about creating a reference string, see About references .

Reference strings for groups or datagroups follow this format:

   page.group. or page.datagroup

In both cases, the page component is optional. It is only required if you want to search a different page than the one containing your reference node.

For example, to refer to the "State" group of cells on PAGE1 of the form, use:

   PAGE1.State

Locating cells or data items

If you want to locate a cell or a data item, you must perform a bitwise OR with UFL_FIRST or UFL_NEXT. UFL_FIRST will locate the first cell or data item in the page. UFL_NEXT will locate the next cell or data item. This allows you to loop through all the cells or data item on a page until you have found the one you want.

Note that groups and datagroups are limited to a single page, and that your search will likewise be limited to a single page.

Creating a node

For an option or argument reference, you can have the library create a node that does not exist. To do so, perform a bitwise OR of UFL_SEARCH_AND_CREATE to the referenceType parameter; otherwise, perform a bitwise OR of UFL_SEARCH to the referenceType variable and the function will return null if the node does not exist.

Determining namespace

In some cases, you may want to use the dereferenceEx method to locate a node that does not have a globally defined namespace. For example, consider the following form:

   <label sid="Label1">
      <value>Field1.processing:myValue</value>
   </label>
   <field sid="Field1" xmlns:processing="URI">
      <value></value>
      <processing:myValue>10<processing:myValue>
   </field>

In this form, the processing namespace is declared in the Field1 node. Any elements within Field1 will understand that namespace; however, elements outside of the scope of Field1 will not.

In cases like this, you will often start your search at a node that does not understand the namespace of the node you are trying to locate. For example, you might want to locate the node referenced in the value of Label1. In this case, you would first locate the Label1 value node and get its literal. Then, from the Label1 value node, you would attempt to locate the processing:myValue node as shown:

   Label1Node.dereferenceEx(null, "Field1.processing:myValue", 0,
      FormNodeP.UFL_OPTION_REFERENCE, null)

In this example, the dereferenceEx method would fail. The method cannot properly resolve the processing namespace because this namespace is not defined for the Label1 value node. To correct this, you must also provide a node that understands the processing namespace (in this case, any node in the scope of Field1) as the last parameter in the method:

   Label1Node.dereferenceEx(null, "Field1.processing:myValue", 0,
      FormNodeP.UFL_OPTION_REFERENCE, Field1Node)

Example

The sample code makes a variety of calls to dereferenceEx and displays the results in a JavaScript alert() message.

function testDereferenceEx(theForm) {
  
  var s;
  var tempNode;
  
  s = "--- results of dereferenceEx test ---\n";
  /* find PAGE2 */
  s += "1. ";
  tempNode = theForm.dereferenceEx(null, "PAGE2", 0, 
             FormNodeP.UFL_PAGE_REFERENCE, null);
  if(tempNode == null) {
    s += "Could not find PAGE2 on the form.\n";
  } else {
    s += "PAGE2 found.\n";
  }
  
  /* find PAGE1.FIELD3 */
  s += "2. ";
  tempNode = theForm.dereferenceEx(null, "PAGE1.FIELD3", 0, 
             FormNodeP.UFL_ITEM_REFERENCE, null);
  if(tempNode == null) {
    s += "Could not find PAGE1.FIELD3 on the form.\n";
  } else {
    s += "PAGE1.FIELD3 found.\n";
  }
  
  /* find fontinfo of FIELD3, create if not found*/
  s += "3. ";
  tempNode = theForm.dereferenceEx(null, "PAGE1.FIELD3.fontinfo[fontname]", 0, 
             FormNodeP.UFL_ARRAY_REFERENCE | FormNodeP.UFL_SEARCH_AND_CREATE, null);
  if(tempNode == null) {
    s += "Could not create PAGE1.FIELD3.fontinfo[fontname].\n";
  } else {
    s += "PAGE1.FIELD3.fontinfo[fontname] created.\n";
  }
  
  /* find the first node in the COMBOBOX1_GROUP group */
  s += "4. ";
  tempNode = theForm.dereferenceEx(null, "PAGE1.COMBOBOX1_GROUP", 0, 
             FormNodeP.UFL_GROUP_REFERENCE | FormNodeP.UFL_FIRST, null);
  if(tempNode == null) {
    s += "Could not find PAGE1.COMBOBOX1_GROUP.\n";
  } else {
    s += "The first COMBOBOX1_GROUP on PAGE1 is: ";
    s += tempNode.getAttribute("http://www.ibm.com/xmlns/prod/XFDL/7.5", "sid");
  }
  alert(s);
}

--- Results of dereferenceEx test ---
 1. Could not find PAGE2 on the form.
 2. PAGE1.FIELD3 found.
 3. PAGE1.FIELD3.fontinfo[fontname] created.
 4. The first PAGE1.COMBOBOX1_GROUP is: ORANGE_CELL.

Description

This method destroys the indicated FormNodeP and all of its child nodes.

Method

void destroy( );

Parameters

There are no parameters for this method.

Returns

Nothing. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Notes

Attempting to destroy a form or a digitally signed item causes an error.

Example

The sample code destroys PAGE1.FIELD2.

function testDestroy(theForm) {
  var s;
  var node;
  
  s = "--- Results of destroy test ---\n";
  node = theForm.dereferenceEx(null, "PAGE1.FIELD2", 0,
         FormNodeP.UFL_ITEM_REFERENCE, null);
  if(node == null) {
    s += " Could not find PAGE1.FIELD2 on the form.\n";
  } else {
    node.destroy();
    s += " PAGE1.FIELD2 has been destroyed.\n";
  }
  alert(s);
} 

--- Results of destroy test ---
 PAGE1.FIELD2 has been destroyed.

Description

This method makes a copy of a node. The duplicated node can be attached to any other node as either a sibling or a child, or can be stored as a separate node structure. The new node can also be assigned a new identifier with the identifier parameter. All of the properties of the original node are duplicated, including any children and any namespace settings.

Method

   FormNodeP duplicate(
      FormNodeP baseNode,
      Number where,
      String identifier
   );   

Parameters

Returns

The new node. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

The sample code makes a duplicate of PAGE1.FIELD1 and gives it the sid FIELD5. Because the new node is an exact copy of PAGE1.FIELD1, it will also have the same value and location as PAGE1.FIELD1. For this reason, the sample code uses setLiteralByRefEx to give FIELD5 a new value and location.

function testDuplicate(theForm) {
  var tempNode, newNode;
  var s;
  
  s = "--- Results of duplicate test ---\n";
  fieldNode = theForm.dereferenceEx(null, "PAGE1.FIELD1", 0, 
              FormNodeP.UFL_ITEM_REFERENCE, null);
  if(fieldNode == null) {
     s += " Could not locate FIELD1 node.";
  } else {
    newNode = fieldNode.duplicate(null, XFDL.UFL_AFTER_SIBLING, "FIELD5");
    if(newNode == null) {
      s += " Could not duplicate FIELD1 node.\n";
    } else {
      /* give the new node a new value and location */
      newNode.setLiteralByRefEx(null, "value", 0, 
              null, "this field is a duplicate of FIELD1");
      newNode.setLiteralByRefEx(null, "itemlocation[y]", 0, 
              null, "300");
      s += " FIELD1 duplicated and new field relocated.\n";
    }
  }
  alert(s);
}  

--- Results of duplicate test ---
 FIELD1 duplicated and new field relocated.

Description

This method encloses file data in a form. The formNodeP object can be either a page node or an item node. If the formNodeP is a page node, the method creates a data item in that page to contain the enclosure. If the formNodeP is an item node, it must be a data item, and the method encloses the file in that node.

Method

FormNodeP encloseFile(
   String data,
   String dataEncoding,
   String mimeType,
   String dataGroup,
   String identifier
 );   

Parameters

Returns

The item formNodeP that contains the enclosure on success or null on failure.On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

The sample code encloses a short string in the form and displays the result in a JavaScript alert() message.

function testEncloseFile(theForm) {
  var pageNode, newNode;
  var s, sData;
  
  s = "--- Results of encloseFile test ---\n";
  
  pageNode = theForm.dereferenceEx(null, "PAGE1", 0,
             FormNodeP.UFL_PAGE_REFERENCE, null);
  if(pageNode == null) {
    s += " Could not find PAGE1 on the form.";
  } else {
    s += " XML encoding test:\n";
    sData = "data to enclose as xml encoding";
    newNode = pageNode.encloseFile(sData, "xml", null, "dGroup", "xmldata");
    if(newNode == null) {
      s += "  Fail. The data was not enclosed.\n";
    } else {
      s += " Success. The data was enclosed.\n";
    }
  }
  alert(s);
}
   

--- Results of encloseFile test ---  
 XML encoding test:
 Success. The data was enclosed.

Description

This method modifies one instance in the data model, either updating information or appending information. Note that the form must have an existing data model.

Method

   void encloseInstance(
      String instanceID,
      String  data,
      Number flags,
      String scheme,
      String rootReference,
      FormNodeP NSNode,
      boolean replaceNode
   );   

Parameters

Returns

Nothing. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

The sample code encloses some XML data in the form, then uses extractInstance for display in a JavaScript alert box. Note that in the sample, the instance "instance1" must exist in the XML data model.

function testEncloseInstance(theForm) {
  var s, xmlData;
  
  s = "--- Results of encloseInstance test ---\n";
  xmlData = "<data><flower>Rose</flower></data>";
  theForm.encloseInstance("instance1", xmlData, 0, null, null, null, true);
  s += " New contents of instance1:\n  ";
  s += theForm.extractInstance("instance1",null, "", 0, null, null, null) + "\n";
  
  alert(s);
}   

--- Results of encloseInstance test ---
 New contents of instance1:
  <data xmlns="" xmlns:custom="http://www.ibm.com/xmlns/prod/XFDL/Custom"
 xmlns:designer="http://www.ibm.com/xmlns/prod/workplace/forms/designer/2.6"
 xmlns:test="http://www.ibm.com/xmlns/prod/XFDL/Custom"
 xmlns:xfdl="http://www.ibm.com/xmlns/prod/XFDL/7.5"
 xmlns:xforms="http://www.w3.org/2003/xforms">
    <flower>Rose</flower>
 </data>

Description

This method will extract an enclosure contained in a node and return it as a string. Note that this method does not remove the enclosure from the form.

Method

String extractFile(
   String dataEncoding
);   

Parameters

Returns

The data is returned as a string in the encoding specified by the dataEncoding parameter. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

<data sid="data">
   <mimetype>text/base64-gzip</mimetype>
   <filename>base64-gzip.txt</filename>
   <mimedata encoding="base64-gzip">H4sIAAAAAAAAAEtJLElUKMlXSM1LzskvT
       lVILFZISixONTMBieSnZOalAwBjuqgyIgAAAA==</mimedata>
</data>

In the above fragment, the plain-text version of the mimedata is: "data to enclose as base64 encoding".

function testExtractFile(theForm) {
  var fieldNode;
  var s, sData;
  
  s = "--- Results of extractFile test ---\n";
  fieldNode = theForm.dereferenceEx(null, "PAGE1.data", 0,
              FormNodeP.UFL_ITEM_REFERENCE, null);
  if(fieldNode == null) {
    s += " Could not find PAGE1.data on the form.";
  } else {
    s += " XML encoding test:\n";
    sData = fieldNode.extractFile("xml");
    if(sData == "") {
      s += "  Failed XML extract test.\n";
    } else {
      s += " The data with no encoding is:\n  '";
      s += sData + "'\n";
    }
    sData = fieldNode.extractFile("base64");
    if(sData == "") {
      s += "  Failed BASE64 extract test.\n";
    } else {
      s += " The data with base64 encoding is:\n  '";
      s += sData + "'\n";
    }
    sData = fieldNode.extractFile("base64-gzip");
    if(sData == "") {
      s += "  Failed BASE64-GZIP extract test.\n";
    } else {
      s += " The data with base64-gzip encoding is:\n  '";
      s += sData + "'";
    }
  }
  alert(s);
}

--- Results of extractFile test ---
 XML encoding test:
  The data with no encoding is:
   'data to enclose as base64 encoding'
  The data with base64 encoding is:
   'ZGF0YSB0byBlbmNsb3NlIGFzIGJhc2U2NCBlbmNvZGluZw==' 
  The data with base64-gzip encoding is: 
   'H4sIAAAAAAAAC0tJLElUKMlXSM1LzskvTlVILFZISixONTMBieSnZOalAwBjuqgyIgAAAA=='

Description

This method returns the XML instance data as a string. It does not remove the instance from the form.

Call this method on the root node of the form or an XML instance node.

Method

String extractInstance (
   String instanceID,
   FormNodeP triggerItem,
   String includeNamespacePrefixes,
   Number flags,
   String scheme,
   String rootReference,
   FormNodeP NSNode
);
  

Parameters

   xfdl custom

Returns

The instance as a string. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

The sample code encloses some XML data in the form then uses extractInstance for display in a JavaScript alert box. Note that in the sample, the instance "instance1" must exist in the XML data model.

function testExtractInstance(theForm) {
  var s, xmlData;

  s = "--- Results of extractInstance test ---\n";
  xmlData = "<data><flower>Rose</flower></data>";
  theForm.encloseInstance("instance1", xmlData, 0, null, null, null, false);
  s += " New contents of instance1:\n  ";
  s += theForm.extractInstance("instance1",null, "", 0, null, null,null) + "\n";
  
  alert(s);
}   

--- Results of extractInstance test ---
 New contents of instance1:
  <data xmlns="" xmlns:custom="http://www.ibm.com/xmlns/prod/XFDL/Custom"
 xmlns:designer="http://www.ibm.com/xmlns/prod/workplace/forms/designer/2.6"
 xmlns:test="http://www.ibm.com/xmlns/prod/XFDL/Custom"
 xmlns:xfdl="http://www.ibm.com/xmlns/prod/XFDL/7.5"
 xmlns:xforms="http://www.w3.org/2003/xforms">
     <flower>Rose</flower>
 </data>

Description

This method returns the XForms instance data as a string. It does not remove the instance from the form.

Call this method on the root node of the form or an instance node.

Method

   String extractXFormsInstance(
      String modelID,
      String instanceXPath,
      boolean respectRelevantMIP,
      boolean ignoreFailures,
      FormNodeP NSNode,
   );  

Parameters

Returns

XForms instance data as a string. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Notes

XForms data model

Example

The sample code extracts various portions of an instance and places the results in a string. It then displays the string in a JavaScript alert window.

<xformsmodels>
   <xforms:model>
      <xforms:instance id="instance1" xmlns="">
         <document>
            <cities>
               <city>Paris</city>
               <city>Beijing</city>
            </cities>
         </document>
      </xforms:instance>
   </xforms:model>
</xformsmodels>

Sample code:

function testExtractXFormsInstance(theForm) {
  var s, sData;

  s = "--- Results of extractXFormsInstance test ---\n\n";
  
  s += "Entire instance:\n"
  sData = theForm.extractXFormsInstance(null,
                  "",
                  true, true, null);
  s += sData + "\n\n";
  
  s += "Cities data only:\n"
  sData = theForm.extractXFormsInstance(null,
                  "instance('instance1')/cities",
                  true, true, null);
  s += sData + "\n\n";
  
  s += "The first city element:\n"
  sData = theForm.extractXFormsInstance(null,
                  "instance('instance1')/cities/city[1]",
                  true, true, null);
  s += sData + "\n\n";
  
  alert(s);
}   

--- Results of extractXFormsInstance test ---

Entire instance:
<document>
   <cities>
      <city>Paris</city>
      <city>Beijing</city>
   </cities>
</document>

Cities data only:
<cities>
   <city>Paris</city>
   <city>Beijing</city>
</cities>

The first city element:
<city>Paris</city>

Description

This method returns the value of an attribute in a node. For example, in the XFDL fragment shown, the mimedata node has an attribute called encoding with the value base64.

   <mimedata encoding="base64"></mimedata>

Method

String getAttribute(
   String namespaceURI,
   String localName
);
   

Parameters

http://www.ibm.com/xmlns/prod/XFDL/7.7

Returns

The value of the attribute. If the attribute is empty or does not exist, the method returns an empty string. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Notes

Namespaces

If you refer to an attribute with a namespace prefix, getAttribute first looks for a complete match, including both prefix and attribute name. If it does not find a match, it will look for a matching attribute name that has no prefix but whose containing element has the same namespace.

For example, assume that the custom namespace and the test namespace both resolve to the same URI. In the following case, looking for the id attribute would locate the second attribute (test:id), since it has an explicit namespace declaration:

   <a xmlns:custom="ABC" xmlns:test="ABC">
      <custom:myElement id="1" test:id="2">
   </a>

However, in the next case, the id attribute does not have an explicit namespace declaration. Instead, it inherits the custom namespace. However, since the inherited namespace resolves to the same URI, the id attribute is still located:

   <custom:myElement id="1">

Special attributes

Forms generally use three special attributes that are not in an explicitly defined namespace and which require special commands to retrieve.

The first is the default namespace attribute, which looks like this:

   xmlns="http://www.ibm.com/xmlns/prod/XFDL/7.7"

To retrieve this attribute, you must use a namespace URI of null and the attribute name xmlns.

The second special attribute is a namespace declaration, which looks like this:

   xmlns:custom="http://www.ibm.com/xmlns/prod/XFDL/Custom"

To retrieve this sort of attribute, you must use the namespace URI http://www.w3.org/2000/xmlns and the appropriate attribute name, such as custom.

Finally, there is the language attribute, which looks like this:

   xml:lang="en-GB"

To retrieve this sort of attribute, you must use the namespace URI http://www.w3.org/XML/1998/namespace and the attribute name lang.

Example

The following example shows a method that gets the value of the encoding attribute for a node. The node is passed to the method which calls getAttribute to get the value of encoding attribute. This sample method assumes that the attribute is always in the XFDL namespace.

The sample code uses getAttribute to retrieve the sid of the first child node on PAGE1 of the form that is passed in, and to retrieve the lang attribute of the form.

function testGetAttribute(theForm) {
  var pageNode, childNode;
  var s;
  
  s = "--- Results of getAttribute test ---\n";
  pageNode = theForm.dereferenceEx(null, "PAGE1", 0,
             FormNodeP.UFL_PAGE_REFERENCE, null);
  if(pageNode == null) {
     s += " FAILED: Could not find PAGE1 on the form.\n";
  } else {
      childNode = pageNode.getChildren();
  }
  if(childNode == null) {
     s += " FAILED: Could not find first child of PAGE1.\n";
  } else {
     s += " The sid of the first child node of PAGE1: '";
     s += childNode.getAttribute("http://www.ibm.com/xmlns/prod/XFDL/7.7", "sid");
     s += "'\n";
  }

  s += " The language of the form is: '"; 
  s += theForm.getAttribute("http://www.w3.org/XML/1998/namespace", "lang");
  s += "'\n";
  alert(s);
}   

--- Results of getAttribute test ---
 The sid of the first child node of PAGE1: 'global'
 The language of the form is: 'en-US'

Description

This method returns a list of either the namespace URIs of all attributes of the node on which it is called, or the local names of all attributes of the node on which it is called. The returned list depends on the value of the namespaces parameter. If the parameter is FormNodeP.NAMESPACE, a list of the namespace URIs is returned. If the parameter is FormNodeP.LOCALNAME, a list of the local names of all attributes is returned. The lists are ordered such that element 1 of one list corresponds to element 1 of the other list.

Method

String[] getAttributeList(
   Number namespaces
);

Parameters

Returns

The requested list. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

 <field sid="FIELD3" custom:id="2">
   <value>This is the value for FIELD3</value>
 </field>

function testGetAttributeList(theForm) {
  var namespaceURIList, localNameList;
  var fieldNode;
  var s;
  
  s = "--- Results of getAttributeList test ---\n";
  fieldNode = theForm.dereferenceEx(null, "PAGE1.FIELD3", 0,
              FormNodeP.UFL_ITEM_REFERENCE, null);
  if(fieldNode == null) {
    s += " Could not find PAGE1.FIELD3 on the form.\n";
  } else {
    namespaceURI = fieldNode.getAttributeList(FormNodeP.NAMESPACE);
    localName = fieldNode.getAttributeList(FormNodeP.LOCALNAME);
    for(i=0, j=1; i < namespaceURI.length; i++,j++) {
      s += "  Attribute " + j + ": '";
      s += namespaceURIList[i] + "', '";
      s += localNameList[i] + "'\n";
    }
  }
  alert(s);
}   

--- Results of getAttributeList test --
  Attribute 1: 'http://www.ibm.com/xmlns/prod/XFDL/Custom', 'id'.
  Attribute 2: 'null', 'sid'.

Description

This method, along with getParent, is used to traverse vertically along the form hierarchy. getChildren returns the first child of the indicated node. If the node has no children, null is returned. All child nodes of a FormNodeP can be traversed using a while loop in combination with getNext.

Method

FormNodeP getChildren( );   

Parameters

There are no parameters for this method.

Returns

The FormNodeP that represents the first child or null if no child nodes exist. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

The sample code returns the first child node of PAGE1.FIELD1 and displays the result in a JavaScript alert() message.

function testGetChildren(theForm) {
  var parentNode, tempNode;
  var s;
	
  s = "--- Results of getChildren test ---\n";
  parentNode = theForm.dereferenceEx(null, "PAGE1.FIELD3", 0, 
               FormNodeP.UFL_ITEM_REFERENCE, null);
  if(parentNode == null) {
    s = " Cannot find PAGE1.FIELD3";
  } else {
    tempNode = parentNode.getChildren();
    s += " The first child node of PAGE1.FIELD3 is: "
      + tempNode.getLocalName() + "\n";
  }
  alert(s);
}

--- Results of getChildren test ---
 The first child node of PAGE1.FIELD3 is: itemlocation.

Description

This method determines the XFDL version of a form.

Method

   Number getFormVersion( );   

Parameters

There are no parameters for this method.

Returns

A decimal number that when converted to base 16, is in the form of MMmm300. The example below shows how to convert the return value to base 16.

Example

The sample code retrieves the version of the form and converts it to a string for display in a JavaScript alert() window.

function testGetFormVersion(theForm)
{
  var version;
  var s;
  
  s = "--- Results of getFormVersion test ---\n";
  version = theForm.getFormVersion().toString(16);
  s += " Form Version: " + version;
  alert(s);
}

--- Results of getFormVersion test ---
 Form Version: 7050300

Description

This method retrieves information about a particular node. If you do not want information about a particular property, set it to null.

Method

String getInfoEx(
  Number property
);   

Parameters

Returns

The value that corresponds to the parameter that is passed in, or null if the requested value does not exist. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Notes

If you are getting information about a node that is not in the XFDL namespace, getInfoEx may return values that include namespace prefixes as follows:

• Any item node in a non-XFDL namespace will return a Type that includes a namespace prefix. For example, myNamespace:Field1.
• Any option node in a non-XFDL namespace will return an Identifier that includes a namespace prefix. For example, myNamespace:value.

Example

The sample code makes four calls to getInfoEx to retrieve the type, literal, compute, and identifer properties of the node PAGE1.FIELD1.value, and displays the results in a JavaScript alert() message.

function testGetInfoEx(theForm) {
  var fieldNode;
  var s, sType, sLiteral, sCompute, sIdentifier;
  
  s = "--- Results of getInfoEx test ---\n";
  fieldNode = theForm.dereferenceEx(null, "PAGE1.FIELD1.value", 0,
              FormNodeP.UFL_OPTION_REFERENCE, null);
  if(fieldNode == null) {
    s += "Cannot find PAGE1.FIELD1.value";
  } else {
    sType = fieldNode.getInfoEx(FormNodeP.TYPE);
    sLiteral = fieldNode.getInfoEx(FormNodeP.LITERAL);
    sCompute = fieldNode.getInfoEx(FormNodeP.COMPUTE);
    sIdentifier = fieldNode.getInfoEx(FormNodeP.IDENTIFIER);
    
    s += " Type: " + sType + "\n";
    s += " Literal: " + sLiteral + "\n";
    s += " Formula: " + sCompute + "\n";
    s += " Identifier: " + sIdentifier + "\n";
  }
  alert(s); 
}

--- Results of getInfoEx test --- 
 Type: undefined
 Literal: This is the value for FIELD3
 Formula: PAGE1.FIELD3.value
 Identifier: value

Description

This method finds a particular FormNodeP on the basis of a reference string. Once the FormNodeP is found, its literal is retrieved.

Method

String getLiteralByRefEx(
   String scheme,
   String reference,
   Number referenceCode,
   FormNodeP NSNode
);   

Parameters

Returns

The literal string. If the literal is empty or does not exist, the method returns null. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Notes

   aNode.dereferenceEx(scheme, reference, referenceCode,
      UFL_OPTION_REFERENCE | UFL_SEARCH_AND_CREATE,
      theNamespaceNode).getLiteralEx();

FormNodeP

Before you decide which FormNodeP to call the method on, be sure you understand the following:

1. The FormNodeP supplied can never be more than one level in the hierarchy above the starting point of the reference string. For example, if the reference string begins with an option, then the FormNodeP can be no higher in the hierarchy than an item.
2. If the FormNodeP is at the same level or lower in the hierarchy than the starting point of the reference string, the method will attempt to locate a common ancestor. The method will locate the ancestor of the FormNodeP that is one level in the hierarchy above the starting point of the reference string. The method will then attempt to follow the reference string back down through the hierarchy. If the reference string cannot be followed from the located ancestor (for example, if the ancestor is not common to both the FormNodeP and the reference string), the method will fail.

   For example, given a FormNodeP that represents "field_1" and a reference of "field_2", the method will access the "page" node above "field_1", and will then try to locate "field_2" below that node. If the two fields are not on the same page, the method will fail.

3. If the FormNodeP is at the argument level, the search will not start from that point. Instead, the nearest ancestor that is at the option level will be used as the starting point for the search.

   <label sid="LABEL1">
      <value>FIELD1.processing:myValue</value>
   </label>
   <field sid="FIELD1" xmlns:processing="URI">
      <value>This is Field 1</value>
      <processing:myValue>10</processing:myValue>
   </field>

In this form, the processing namespace is declared in the FIELD1 node. Any elements within FIELD1 will understand that namespace; however, elements outside of the scope of FIELD1 will not.

In cases like this, you will often start your search at a node that does not understand the namespace of the node you are trying to locate. For example, you might want to locate the node referenced in the value of LABEL1. In this case, you would first locate the LABEL1 value node and get its literal. Then, from the LABEL1 value node, you would attempt to locate the processing:myValue node as shown:

   Label1Node.getLiteralByRefEx(null, "FIELD1.processing:myValue", 0, null)

In this example, the getLiteralByRefEx method fails. The method cannot properly resolve the processing namespace because this namespace is not defined for the LABEL1 value node. To correct this, you must also provide a node that understands the processing namespace (in this case, any node in the scope of LABEL1) as a parameter in the method:

   Label1Node.getLiteralByRefEx(null, "FIELD1.processing:myValue", 0, Field1Node)

Example

Using the form fragment described above, the sample code retrieves the literal of PAGE1.FIELD1.value, which is "This is Field 1". The code then attempts to retrieve the literal of PAGE1.FIELD1.processing:myValue, which is in the processing namespace. The first attempt returns "null" because the namespace is not understood. The second attempt returns the correct value of "10" because the node representing FIELD1.PAGE1 is passed in as the NSNode parameter. The results are displayed in a JavaScript alert window.

function testGetLiteralByRefEx(theForm) {
  var fieldNode, labelNode;
  var s, sLiteral;
  
  s = "--- testGetLiteralByRefEx results ---\n";
  fieldNode = theForm.dereferenceEx(null, "PAGE1.FIELD1", 0,
              FormNodeP.UFL_ITEM_REFERENCE, null);
  labelNode = theForm.dereferenceEx(null, "PAGE1.LABEL1", 0,
              FormNodeP.UFL_ITEM_REFERENCE, null);
  if(fieldNode == null) {
    s += "Cannot find PAGE1.FIELD1";
  } else {
    sLiteral = labelNode.getLiteralByRefEx(null,
               "PAGE1.FIELD1.value", 0, null);
    s += " First test: " + sLiteral + "\n";
    sLiteral = labelNode.getLiteralByRefEx(null,
               "PAGE1.FIELD1.processing:myValue", 0, null);
    s += " Second test: " + sLiteral + "\n";
    sLiteral = labelNode.getLiteralByRefEx(null,
               "PAGE1.FIELD1.processing:myValue", 0, fieldNode);
    s += " Third test: " + sLiteral + "\n";
  }
  alert(s);
}   

--- getLiteralByRefEx results ---
 First test: This is Field 1
 Second test: null
 Third test: 10

Description

This method retrieves the literal of a node. The literal is returned in the specified character set.

Method

String getLiteralEx( );  

Parameters

There are no parameters for this method.

Returns

A string containing the literal of the node, or null if the literal is empty or does not exist. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

The following example uses dereferenceEx to locate a specific node. getLiteralEx is then used to get the literal value for that node.

function testGetLiteralEx(theForm) {
  var valueNode;
  var s, value;

  s = "--- Results of getLiteralEx test ---\n";
  valueNode = theForm.dereferenceEx(null, "PAGE1.FIELD4.value", 0, 
              FormNodeP.UFL_OPTION_REFERENCE, null);
  if(valueNode == null) {
    s += "Cannot find PAGE1.FIELD4.value";
  } else {
    value = valueNode.getLiteralEx();
    s += " The value is: " + value + "\n";
  }
  alert(s);
}

--- Results of getLiteralEx test ---
 The value is: This is FIELD4

Description

This method returns the local name of a given node. The local name is determined by the XML tag that represents that node. For example, examine the following XML fragment:

   <page sid="PAGE1">
      <global sid="global"></global>
      <field sid="testField">
         <value>Hello</value>
         <bgcolor>120, 120, 120</bgcolor>
      </field>
   </page>

In this sample, the name of the page node is "page", the name of the field node is "field", the name of the value node is "value", and the name of the bgcolor node is "bgcolor".

Note that the local name does not include any namespace prefix that might exist. For example, you might have a custom option in a different namespace as shown:

   <field sid="testField">
      <custom:my_option>value</custom:my_option>
   </field>

In this case, the local name of the custom option is returned without the prefix, resulting in "my_option".

Method

String getLocalName ( );   

Parameters

There are no parameters for this method.

Returns

The name of the node. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

The sample code retrieves the local name of all child nodes of PAGE1.FIELD4 and displays the results in a JavaScript alert() message.

function testGetLocalName(theForm) {
  var fieldNode, tempNode;
  var s;
  
  s = "--- Results of testGetLocalName test ---\n";
  fieldNode = theForm.dereferenceEx(null, "PAGE1.FIELD4", 0, 
              FormNodeP.UFL_ITEM_REFERENCE, null);
  if(fieldNode == null){
    s += "Cannot find PAGE1.FIELD4";
  } else {
    tempNode = fieldNode.getChildren();
    while(tempNode != null){
      s += "Local Name: " + tempNode.getLocalName() + "\n";
      tempNode = tempNode.getNext();
    }
  }
  alert(s);
}

--- Results of getLocalName test ---
 Local Name: myValue
 Local Name: value
 Local Name: focused
 Local Name: mouseover
 Local Name: itemprevious
 Local Name: itemnext

Description

This method returns the namespace URI for the node.

Each namespace is defined in the form by a namespace declaration, as shown:

   xmlns:xfdl="http://www.ibm.com/xmlns/prod/XFDL/7.5" 
   xmlns:custom="http://www.ibm.com/xmlns/prod/XFDL/Custom"

Each namespace declaration defines both a prefix and a URI for the namespace. In this sample, the prefix for the XFDL namespace is xfdl and the URI is http://www.ibm.com/xmlns/prod/XFDL/7.5.

Tags within the form are assigned specific namespaces by using the defined prefix. For example, to declare that an option was in the custom namespace you would use the prefix custom as shown:

   <field sid="testField">
      <custom:custom_option>value</custom:custom_option>
   </field>

Method

String getNamespaceURI ( );   

Parameters

There are no parameters for this method.

Returns

The namespace URI. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

The sample code retrieves the namespace URI for each child node of PAGE1.FIELD4 and displays the results in a JavaScript alert() message.

function testGetNamespaceURI(theForm) {
  var fieldNode, tempNode;
  var s;
  
  s = "--- Results of testGetNamespaceURI test ---\n";
  fieldNode = theForm.dereferenceEx(null, "PAGE1.FIELD4", 0, 
              FormNodeP.UFL_ITEM_REFERENCE, null);
  if(fieldNode == null){
    s += "Cannot find PAGE1.FIELD4";
  } else {
    tempNode = fieldNode.getChildren();
    while(tempNode != null){
      s += "Local Name: " + tempNode.getNamespaceURI() + "\n";
      tempNode = tempNode.getNext();
    }
  }
  alert(s);
}

--- Results of getNamespaceURI test ---
 Namespace: http://www.sample.uri/processing
 Namespace: http://www.ibm.com/xmlns/prod/XFDL/7.5
 Namespace: http://www.ibm.com/xmlns/prod/XFDL/7.5
 Namespace: http://www.ibm.com/xmlns/prod/XFDL/7.5
 Namespace: http://www.ibm.com/xmlns/prod/XFDL/7.5
 Namespace: http://www.ibm.com/xmlns/prod/XFDL/7.5

Description

This method returns the namespace URI that corresponds to a specific prefix. You can call this method from any node in the form, as long as that node either declares or inherits the namespace in question.

Each namespace is defined in the form by a namespace declaration, as shown:

   xmlns:xfdl="http://www.ibm.com/xmlns/prod/XFDL/7.5" 
   xmlns:custom="http://www.ibm.com/xmlns/prod/XFDL/Custom"

Each namespace declaration defines both a prefix and a URI for the namespace. In this sample, the prefix for the XFDL namespace is xfdl and the URI is http://www.ibm.com/xmlns/prod/XFDL/7.5.

Tags within the form are assigned specific namespaces by using the defined prefix. For example, to declare that an option was in the custom namespace you would use the prefix custom as shown:

   <field sid="testField">
      <custom:custom_option>value</custom:custom_option>
   </field>

Method

String getNamespaceURIFromPrefix (
   String prefix
);

Parameters

Returns

The namespace URI. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

The sample code retrieves the namespace URI associated with the prefix "xfdl", the prefix "custom", and the prefix "temp". The results are displayed in a JavaScript alert() message.

function testGetNamespaceURIFromPrefix(theForm) {
  var fieldNode;
  var s, sPrefix;
  
  s = "--- Results of getNamespaceURIFromPrefix test ---\n";
  fieldNode = theForm.dereferenceEx(null, "PAGE1.FIELD4", 0, 
              FormNodeP.UFL_ITEM_REFERENCE, null);
  if(fieldNode == null) {
    s += "Cannot find PAGE1.FIELD4";
  } else {
    sPrefix = fieldNode.getNamespaceURIFromPrefix("xfdl");
    s += " Namespace for prefix 'xfdl': " + sPrefix + "\n";
    sPrefix = fieldNode.getNamespaceURIFromPrefix("custom");
    s += " Namespace for prefix 'custom': " + sPrefix + "\n";
    sPrefix = fieldNode.getNamespaceURIFromPrefix("processing");
    s += " Namespace for prefix 'processing': " + sPrefix + "\n";
    sPrefix = fieldNode.getNamespaceURIFromPrefix("temp");
    s += " Namespace for prefix 'temp': " + sPrefix + "\n";
  }
  alert(s);
}

--- Results of getNamespaceURIFromPrefix test ---
 Namespace for prefix 'xfdl': http://www.ibm.com/xmlns/prod/XFDL/7.5
 Namespace for prefix 'custom': http://www.ibm.com/xmlns/prod/XFDL/Custom
 Namespace for prefix 'temp': null

Description

This method, along with getPrevious, is used to traverse horizontally along the form hierarchy. getNext returns the next node in the tree. For instance, the page node corresponding to the first page of your form can be reached by calling getNext on the global page node.

Method

FormNodeP getNext( );   

Parameters

There are no parameters for this method.

Returns

The FormNodeP that represents the next node or null if the next node does not exist. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

The example uses the getNext method to retrieve all child nodes of the field PAGE1.FIELD4. The results are formatted into a string and displayed in a JavaScript alert() message.

function testGetNext(theForm) {
  var fieldNode, tempNode;
  var s;
  
  s = "--- Results of getNext test ---\n";
  fieldNode = theForm.dereferenceEx(null, "PAGE1.FIELD4", 0, 
              FormNodeP.UFL_ITEM_REFERENCE, null);
  if(fieldNode == null){
    s += "Cannot find PAGE1.FIELD4";
  } else {
    tempNode = fieldNode.getChildren();
    while(tempNode != null){
      s += " Local Name: " + tempNode.getLocalName() + "\n";
      tempNode = tempNode.getNext();
    }
  }
  alert(s);
}

--- Results of getNext test ---
 Local Name: myValue
 Local Name: value
 Local Name: focused
 Local Name: mouseover
 Local Name: itemprevious
 Local Name: itemnext

Description

This method returns the type for a node (for example, page, item, option, and array). This allows you to quickly determine the type of node you are working with and what depth you are at in the node hierarchy.

Method

Number getNodeType( );   

Parameters

There are no parameters for this method.

Returns

Example

The sample code calls getNodeType on each node that it finds while traversing down the node tree, starting at the second child node of PAGE1. It also collects the localname of each node and displays the results in a JavaScript alert() message.

function testGetNodeType(theForm) {
  var pageNode, tempNode;
  var s, nodeType;
  
  s = "--- Results of getNodeType test ---\n";
  pageNode = theForm.dereferenceEx(null, "PAGE1", 0,
             FormNodeP.UFL_PAGE_REFERENCE, null);
  if(pageNode == null){
    s += "Cannot find PAGE1";
  } else {
    /* get the second child node of PAGE1 */
    tempNode = pageNode.getChildren().getNext();
    
    while(tempNode != null){
      nodeType = tempNode.getNodeType();
      switch (nodeType) {
        case FormNodeP.UFL_FORM:
          s += " Node type for " 
            + tempNode.getLocalName() + ": Form\n";
            break;
        case FormNodeP.UFL_PAGE:
          s += " Node type for "
            + tempNode.getLocalName() + ": Page\n";
            break;
        case FormNodeP.UFL_ITEM:
          s += " Node type for " 
            + tempNode.getLocalName() + ": Item\n";
            break;
        case FormNodeP.UFL_OPTION:
          s += " Node type for " 
            + tempNode.getLocalName() + ": Option\n";
            break;
        case FormNodeP.UFL_ARRAY:
          s += " Node type for " 
            + tempNode.getLocalName() + ": Array\n";
            break;
        default:
          s += " Node type: Unknown\n"; break;
      }
      tempNode = tempNode.getChildren();
    }
  }
  alert(s);
}

--- Results of getNodeType test ---
 Node type for field: Item
 Node type for itemlocation: Option
 Node type for x: Array

Description

This method, along with getChildren, is used to traverse vertically along the form hierarchy. getParent returns the parent of a node. If the node has no parent, null is returned. A form's structure can be traversed up to the root node using an iterator such as a while loop.

Method

FormNodeP getParent ( );   

Parameters

There are no parameters for this method.

Returns

The FormNodeP that represents the parent node or null if no such parent exists. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

The sample code retrieves the parent node of PAGE1.FIELD4.value and each subsequent parent node, all the way up to the root node. It also collects the local name of each node and displays the result in a JavaScript alert() window.

function testGetParent(theForm) {
  var valueNode, tempNode;
  var s;
  
  s = "--- Results of getParent test ---\n";
  valueNode = theForm.dereferenceEx(null, "PAGE1.FIELD4.value", 0,
              FormNodeP.UFL_OPTION_REFERENCE, null);
  if(valueNode == null){
    s += "Cannot find PAGE1.FIELD4.value";
  } else {
    tempNode = valueNode.getParent();
    while(tempNode != null){
      s += " Local Name: " + tempNode.getLocalName() + "\n";
      tempNode = tempNode.getParent();
    }
  }
  alert(s);
}   

--- Results of getParent test ---
 Local Name: field
 Local Name: page
 Local Name: XFDL

Description

This method returns the namespace prefix for the node.

Each namespace is defined in the form by a namespace declaration, as shown:

   xmlns:xfdl="http://www.ibm.com/xmlns/prod/XFDL/7.5" 
   xmlns:custom="http://www.ibm.com/xmlns/prod/XFDL/Custom"

Each namespace declaration defines both a prefix and a URI for the namespace. In this sample, the prefix for the XFDL namespace is xfdl and the URI is http://www.ibm.com/xmlns/prod/XFDL/7.5.

Tags within the form are assigned specific namespaces by using the defined prefix. For example, to declare that an option is in the custom namespace, use the prefix custom as shown:

   <field sid="testField">
      <custom:custom_option>value</custom:custom_option>
   </field>

Method

String getPrefix ( );   

Parameters

There are no parameters for this method.

Returns

The prefix for the node's namespace. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

<field sid="FIELD4" xmlns:processing="http://www.sample.uri/processing">
   <processing:myValue>10</processing:myValue>
   <value>This is FIELD4</value>
</field>

function testGetPrefix(theForm) {
  var fieldNode, tempNode;
  var s;
  
  s = "--- Results of getPrefix test ---\n";
  fieldNode = theForm.dereferenceEx(null, "PAGE1.FIELD4", 0,
              FormNodeP.UFL_ITEM_REFERENCE, null);
  if(fieldNode == null){
    s += "Cannot find PAGE1.FIELD4";
  } else {
    tempNode = fieldNode.getChildren();
    s += " Namespace prefix for "  + tempNode.getLocalName() 
      + ": " + tempNode.getPrefix() + "\n";
  } 
  alert(s);
}   

--- Results of getPrefix test ---
 Namespace prefix for myValue: processing

Description

This method returns the namespace prefix for a specific namespace URI. You can call this method from any node in the form, as long as that node either declares or inherits the namespace in question.

Each namespace is defined in the form by a namespace declaration, as shown:

   xmlns:xfdl="http://www.ibm.com/xmlns/prod/XFDL/7.5" 
   xmlns:custom="http://www.ibm.com/xmlns/prod/XFDL/Custom"

Each namespace declaration defines both a prefix and a URI for the namespace. In this sample, the prefix for the XFDL namespace is xfdl and the URI is http://www.ibm.com/xmlns/prod/XFDL/7.5.

Tags within the form are assigned specific namespaces by using the defined prefix. For example, to declare that an option is in the custom namespace, use the prefix custom as shown:

   <field sid="testField">
      <custom:custom_option>value</custom:custom_option>
   </field>

Method

String getPrefixFromNamespaceURI(
   String uri
);

Parameters

http://www.ibm.com/xmlns/prod/XFDL/7.5

Returns

The namespace prefix. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

<field sid="FIELD4" xmlns:processing="http://www.sample.uri/processing">
   <processing:myValue>10</processing:myValue>
   <value>This is FIELD4</value>
</field>

function testGetPrefixFromNamespaceURI(theForm) {
  var fieldNode;
  var s, prefix;
  
  s = "--- Results of getPrefixFromNamespaceURI test ---\n";
  s += " First: (Form) \n";
  prefix = theForm.getPrefixFromNamespaceURI(
           "http://www.ibm.com/xmlns/prod/XFDL/Custom");
  s += "  Namespace prefix for http://www.ibm.com/xmlns/prod/XFDL/Custom: " 
          + prefix + "\n";
  prefix = theForm.getPrefixFromNamespaceURI(
           "http://www.sample.uri/processing");
  s += "  Namespace prefix for http://www.sample.uri/processing: "
          + prefix + "\n";
  
  s += " Second: (PAGE1.FIELD4) \n";
  fieldNode = theForm.dereferenceEx(null, "PAGE1.FIELD4", 0, 
              FormNodeP.UFL_ITEM_REFERENCE, null);
  if(fieldNode == null){
    s += "Cannot find PAGE1.FIELD4";
  } else {
    prefix = fieldNode.getPrefixFromNamespaceURI(
             "http://www.ibm.com/xmlns/prod/XFDL/Custom");
    s += "  Namespace prefix for http://www.ibm.com/xmlns/prod/XFDL/Custom: " 
            + prefix + "\n";
    prefix = fieldNode.getPrefixFromNamespaceURI(
             "http://www.sample.uri/processing");
    s += "  Namespace prefix for http://www.sample.uri/processing: " 
            + prefix + "\n";
  }
  alert(s);
}   

--- Results of getPrefixFromNamespaceURI test ---
 First: (Form) 
  Namespace prefix for http://www.ibm.com/xmlns/prod/XFDL/Custom: custom
  Namespace prefix for http://www.sample.uri/processing: null
 Second: (PAGE1.FIELD4) 
  Namespace prefix for http://www.ibm.com/xmlns/prod/XFDL/Custom: custom
  Namespace prefix for http://www.sample.uri/processing: processing

Description

This method, along with getNext, is used to traverse horizontally along the form hierarchy. getPrevious returns the previous node in the tree. For instance, if you call getPrevious on the Page1 node in your form, it will return the global page node.

Method

FormNodeP getPrevious ( );   

Parameters

There are no parameters for this method.

Returns

The FormNodeP that represents the previous node or null if no such node exists. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

The sample code retrieves the list of nodes that are previous to PAGE1.FIELD4. The local name of each of the previous nodes is saved in a string and displayed in a JavaScript alert() window.

function testGetPrevious(theForm) {
  var fieldNode, tempNode;
  var s;
  
  s = "--- Results of getPrevious test ---\n";
  fieldNode = theForm.dereferenceEx(null, "PAGE1.FIELD4", 0, 
              FormNodeP.UFL_ITEM_REFERENCE, null);
  if(fieldNode == null){
    s += "Cannot find PAGE1.FIELD4";
  } else {
    tempNode = fieldNode.getPrevious();
    while(tempNode != null){
      s += " Local Name: " + tempNode.getLocalName() + "\n";
      tempNode = tempNode.getPrevious();
    }
  }
  alert(s);
}

--- Results of getPrevious test ---
 Local Name: label
 Local Name: field
 Local Name: label
 Local Name: list
 Local Name: popup
 Local Name: combobox
 Local Name: field
 Local Name: global

Description

This method returns the reference string that identifies the node. For example, a value node might return a reference of Page1.Field1.value. The reference will either begin at the page level of the form or at a level specified by the caller.

Method

String getReferenceEx(
   String scheme,
   FormNodeP NSNode,
   FormNodeP startPoint,
   boolean addNamespaces
);

Parameters

Returns

A string containing a reference to the node. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Notes

   <label sid="Label1" xmlns:data="URI">
      <value></value>
   </label>
   <field sid="Field1" xmlns:processing="URI">
      <value></value>
      <processing:myValue>10<processing:myValue>
   </field>

   <page sid="Page1" xmlns:processing="URI1">
      <global sid="global">
         <processing:info></processing:info>
      </global>
      <field sid="Field1" xmlns:data="URI2">
         <value></value>
         <data:info>data</data:info>
      </field>

   dataNode.getReferenceEx(Null, pageGlobalNode, Null, true)

   <global sid="global" xmlns:data="URI2">

Example

 <field sid="FIELD4" xmlns:processing="http://www.sample.uri/processing">
   <processing:myValue>10</processing:myValue>
   <value>This is FIELD4</value>
 </field>

function testGetReferenceEx(theForm) {
  var fieldNode, childNode;
  var s, value;
  
  s = "--- testGetReferenceEx results ---\n";
  fieldNode = theForm.dereferenceEx(null, "PAGE1.FIELD4", 0, 
              FormNodeP.UFL_ITEM_REFERENCE, null);
  if(fieldNode != null) {
    childNode = fieldNode.getChildren();
  }
  if(fieldNode == null | childNode == null) {
    s += "Cannot find either PAGE1.FIELD4 or its first child node";
  } else {
    value = childNode.getReferenceEx(null, null, null, false);
    s += " Test 1: " + value + "\n";
    value = childNode.getReferenceEx(null, null, fieldNode, false);
    s += " Test 2: " + value + "\n";
    value = childNode.getReferenceEx(null, fieldNode.getParent(), null, false);
    s += " Test 3: " + value + "\n";
    value = childNode.getReferenceEx(null, fieldNode.getParent(), null, true);
    s += " Test 4: " + value + "\n";
  }
  alert(s);
} 

--- Results of getReferenceEx test ---
 Test 1: PAGE1.FIELD4.processing:myValue
 Test 2: processing:myValue
 Test 3: PAGE1.FIELD4.(null):myValue
 Test 4: PAGE1.FIELD4.processing:myValue

Description

This method returns the name of the appropriate security engine for a given button or signature node. This is useful for determining which validation call you need to make to validate the signature.

Method

String getSecurityEngineName (
   Number operation
);

Parameters

Returns

Example

The sample code retrieves the security engine name for each of the operations and displays the results in a JavaScript alert() window.

function testGetSecurityEngineName(theForm) {
  var buttonNode;
  var s, value;
  
  s = "--- testGetSecurityEngineName results ---\n";
  buttonNode = theForm.dereferenceEx(null, "PAGE1.BUTTON1", 0, 
               FormNodeP.UFL_ITEM_REFERENCE, null);
  if(buttonNode == null) {
    s += "Cannot find PAGE1.BUTTON1";
  } else {
    value = buttonNode.getSecurityEngineName(
            FormNodeP.SEOPERATION_SIGN);
    s+= " Test 1: " + value + "\n";
    
    value = buttonNode.getSecurityEngineName(
            FormNodeP.SEOPERATION_VERIFY);
    s+= " Test 2: " + value + "\n";
    
    value = buttonNode.getSecurityEngineName(
            FormNodeP.SEOPERATION_LISTIDENTITIES);
    s+= " Test 3: " + value + "\n";
  }
  alert(s);
}

--- Results of getSecurityEngineName test ---
 Test 1: ClickWrap
 Test 2: ClickWrap
 Test 3: ClickWrap

Description

This method returns the signature lock count of a node. If 0 is returned, the node is not signed by any digital signature, but it may have descendants that are signed.

Method

Number getSigLockCount ( );   

Parameters

There are no parameters for this method.

Returns

The number of locks on the given node. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

The sample code retrieves the number of signature locks on PAGE1.FIELD1 and displays the result in a JavaScript alert() window.

function testGetSigLockCount(theForm) {
    var fieldNode;
    var s;
    
    s = "--- testGetSigLockCount results ---\n";
    fieldNode = theForm.dereferenceEx(null, "PAGE1.FIELD1", 0,
                FormNodeP.UFL_ITEM_REFERENCE, null);
    if(fieldNode == null) {
      s += "Cannot find PAGE1.FIELD1";
    } else {
      s += " Signature lock count for PAGE1.FIELD1: " 
        + fieldNode.getSigLockCount() + "\n";
    }
    alert(s);
}

--- Results of getSigLockCount test ---
 Signature lock count for PAGE1.FIELD1: 1

Description

When called, this method checks to see if the digital signatures in a given form are valid.

Method

Number getSignatureVerificationStatus ( );   

Parameters

There are no parameters for this method.

Returns

a Number having one of the following values:

On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

The sample code determines the validity of the signatures on a form and displays the results in a JavaScript alert() window.

function testGetSignatureVerificationStatus(theForm) {
    var s;
    var status;
    
    s = "--- Results of getSignatureVerificationStatus test ---\n";
    status = theForm.getSignatureVerificationStatus();
    switch (status) {
    case FormNodeP.UFL_SIGS_OK:
      s += " All signatures are valid.\n";
      break;
    case FormNodeP.UFL_SIGS_NOTOK:
      s += " One or more signatures are broken.\n";
      break;
    case FormNodeP.UFL_SIGS_UNVERIFIED:
      s += " One or more signatures are unverifiable.\n";
      break;
    default:
      s += " Unknown status.\n";
      break;
    }
    alert(s);
} 

--- Results of getSignatureVerificationStatus test ---
 All signatures are valid.

Description

This method determines whether a node is signed.

Method

boolean isSigned (
  boolean excludeSelf
);

Parameters

Returns

Returns true if the node is signed, false if it is not. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

The sample code checks PAGE1.FIELD1 and PAGE1.FIELD2 for signatures. The results are displayed in a JavaScript alert() window.

function testIsSigned(theForm) {
    var s;
    var node;
		
    s = "--- Results of isSigned test ---\n";
    node = theForm.dereferenceEx(null, "PAGE1.FIELD1", 0,
           FormNodeP.UFL_ITEM_REFERENCE, null);
    if(node == null) {
      s += "Could not find FIELD1 on the form.\n";
    } else {
      s += " FIELD1 is ";
      if(node.isSigned(true) == false) s += "not ";
      s += "signed.\n";
    }
    node = theForm.dereferenceEx(null, "PAGE1.FIELD2", 0,
           FormNodeP.UFL_ITEM_REFERENCE, null);
    if(node == null) {
      s += "Could not find FIELD2 on the form.\n";
    } else {
      s += " FIELD2 is ";
      if(node.isSigned(true) == false) s += "not ";
      s += "signed.\n";
    }
    alert(s);
}   

--- Results of isSigned test ---
 FIELD1 is signed.
 FIELD2 is not signed.

Description

This method returns the boolean result of whether a string is valid according to the setting of the node's format option.

Method

boolean isValidFormat (
   String string
);

Parameters

Returns

The method returns true if the string matches the format, but false if the string does not match the format. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

The sample code checks to see if the strings '42' and '20071001' are valid for PAGE1.FIELD1. The results are displayed in a JavaScript alert message.

 function testIsValidFormat(theForm) {
  var s;
  var node;
  
  s = "--- Results of isValidFormat test ---\n";
  node = theForm.dereferenceEx(null, "PAGE1.FIELD1", 0,
         FormNodeP.UFL_ITEM_REFERENCE, null);
  if(node == null) {
    s += "Could not find FIELD1 on the form.\n";
  } else {
    s += " The value '42' is ";
    if(node.isValidFormat("42") == false) s += "not ";
    s += "a valid format for FIELD1.\n";
    s += " The value '20071001' is ";
    if(node.isValidFormat("20071001") == false) s += "not ";
    s += "a valid format for FIELD1.\n";
  }
  alert(s);
}

--- Results of isValidFormat test ---
 The value '42' is not a valid format for FIELD1.
 The value '20071001' is a valid format for FIELD1.

Description

This method determines whether a node belongs to the XFDL namespace.

Each namespace is defined in the form by a namespace declaration, as shown:

   xmlns:xfdl="http://www.ibm.com/xmlns/prod/XFDL/7.5" 
   xmlns:custom="http://www.ibm.com/xmlns/prod/XFDL/Custom"

Each namespace declaration defines both a prefix and a URI for the namespace. In this sample, the prefix for the XFDL namespace is xfdl and the URI is http://www.ibm.com/xmlns/prod/XFDL/7.5.

Tags within the form are assigned specific namespaces by using the defined prefix. For example, to declare that an option is in the custom namespace, use the prefix custom as shown:

   <field sid="testField">
      <custom:custom_option>value</custom:custom_option>
   </field>

Method

boolean isXFDL ( );   

Parameters

There are no parameters for this method.

Returns

Returns true if the node is in the XFDL namespace, false if it is not. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

The sample code calls the isXFDL function on several nodes, starting with the global page node and moving down the hierarchy one child node at a time. The results are displayed in a JavaScript alert() window.

function testIsXFDL(theForm)
{
    var fieldNode, tempNode;
    var s;
    
    s = "--- Results of isXFDL test ---\n";
    fieldNode = theForm.dereferenceEx(null, "global", 0,
                FormNodeP.UFL_PAGE_REFERENCE, null);
    if(fieldNode == null) {
      s += "Cannot find the global page on this form.\n";
    } else {
      tempNode = fieldNode;
      while(tempNode != null) {
        s += " The node '" + tempNode.getLocalName() + "' is ";
        if(tempNode.isXFDL() != true) s += "NOT ";
        s += "in the XFDL namespace.\n";
        tempNode = tempNode.getChildren();
      }
    }
    alert(s);
}   

If the form is created in the designer (which adds the <designer:date> element to the global page) then the message displayed in the alert box should be similar to this:

--- Results of isXFDL test ---
 The node 'globalpage' is in the XFDL namespace.
 The node 'global' is in the XFDL namespace.
 The node 'date' is NOT in the XFDL namespace.

Description

This method removes a specific attribute from a node. For example, the following XFDL represents a value node:

   <value custom:myAtt="x"></value>

To remove the custom attribute from this node, you would use removeAttribute.

Method

void removeAttribute(
   String uri,
   String localName
);

Parameters

http://www.ibm.com/xmlns/prod/XFDL/7.5

Returns

Nothing. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Notes

   <custom:processing custom:stage="2" user="tjones">

   <a xmlns:custom="ABC" xmlns:test="ABC">
      <custom:myElement id="1" test:id="2">
   </a>

   <custom:myElement id="1">

Example

The sample code removes two attributes from PAGE1.LABEL1. Note that it is not an error to attempt to remove attributes that do not exist.

function testRemoveAttribute(theForm) {
  var s;
  var pageNode;
  
  s = "--- Results of removeAttribute test ---\n";
  pageNode = theForm.dereferenceEx(null, "PAGE1.LABEL1", 0,
             FormNodeP.UFL_ITEM_REFERENCE, null);
  if(pageNode == null) {
    s += " Could not find PAGE1.LABEL1 on the form.";
  } else {
    pageNode.removeAttribute("http://www.ibm.com/xmlns/prod/XFDL/Custom", "test");
    pageNode.removeAttribute(null, "test");
    s += " Attributes were removed from PAGE1.LABEL1\n";
  }
  alert(s);
}   

--- Results of removeAttribute test ---
 Attributes were removed from PAGE1.LABEL1

Description

This method will either remove an enclosure from a specific datagroup or delete the enclosure from the form. Call this method on the FormNodeP that contains the enclosure that you want to remove.

Method

void removeEnclosure(
   String dataGroup
);

Parameters

Returns

Nothing. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

The sample code locates a data node with dereferenceEx then removes it from the form with removeEnclosure. The results are displayed in a JavaScript alert box.

function testRemoveEnclosure(theForm) {
  var s;
  var groupNode;
  
  s = "--- Results of encloseFile test ---\n";
  groupNode = theForm.dereferenceEx(null, "PAGE1.xmldata", 0,
              FormNodeP.UFL_ITEM_REFERENCE, null);
  if(groupNode == null) {
    s += " Could not find data group.";
  } else {
    groupNode.removeEnclosure(null);
    s += " The enclosure was removed from the form";
  }
  
  alert(s);
}   

--- Results of encloseFile test ---
 The enclosure was removed from the form

Description

This method deregisters an event handling function that was previously registered with the addOnBlur method.

Method

void removeOnBlur (
   Function handler
);

Parameters

Returns

Nothing. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

The sample code removes an onBlur event handler from BUTTON1.

function deregisterButtonEvent(theForm) {
  var buttonNode;
  var s;
  
  s = "--- Results of deregisterButtonEvent function call ---\n";
  buttonNode = theForm.dereferenceEx(null, "PAGE1.BUTTON1", 0, 
               FormNodeP.UFL_ITEM_REFERENCE, null);
  if(buttonNode == null) {
    s += " Could not find BUTTON1 on the form.\n";
  } else {
    buttonNode.removeOnBlur(button1OnBlur);
    s += " Function button1OnBlur deregistered.\n";
  }
  alert(s);
}   

--- Results of deregisterButtonEvent function call ---
  Function button1OnBlur deregistered.

Description

This method deregisters an event handling function that was previously registered with the addOnChange method.

Method

void removeOnChange (
   Function handler
);

Parameters

Returns

Nothing. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

The sample code removes an onChange event handler from BUTTON1.

function deregisterButtonEvent(theForm) {
  var buttonNode;
  var s;
  
  s = "--- Results of deregisterButtonEvent function call ---\n";
  buttonNode = theForm.dereferenceEx(null, "PAGE1.BUTTON1", 0, 
               FormNodeP.UFL_ITEM_REFERENCE, null);
  if(buttonNode == null) {
    s += " Could not find BUTTON1 on the form.\n";
  } else {
    buttonNode.removeOnChange(button1OnChange);
    s += " Function button1OnChange deregistered.\n";
  }
  alert(s);
}   

--- Results of deregisterButtonEvent function call ---
 Function button1OnChange deregistered.

Description

This method deregisters an event handling function that was previously registered with the addOnClick method.

Method

void removeOnClick (
   Function handler
);

Parameters

Returns

Nothing. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

The sample code removes an onClick event handler from BUTTON1.

function deregisterButtonEvent(theForm) {
  var buttonNode;
  var s;
  
  s = "--- Results of deregisterButtonEvent function call ---\n";
  buttonNode = theForm.dereferenceEx(null, "PAGE1.BUTTON1", 0, 
               FormNodeP.UFL_ITEM_REFERENCE, null);
  if(buttonNode == null) {
    s += " Could not find BUTTON1 on the form.\n";
  } else {
    buttonNode.removeOnClick(button1OnClick);
    s += " Function button1OnClick deregistered.\n";
  }
  alert(s);
}   

--- Results of deregisterButtonEvent function call ---
  Function button1OnClick deregistered.

Description

This method deregisters an event handling function that was previously registered with the addOnFocus method.

Method

void removeOnFocus (
   Function handler
);

Parameters

Returns

Nothing. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

The sample code removes an onFocus event handler from BUTTON1.

function deregisterButtonEvent(theForm) {
  var buttonNode;
  var s;
  
  s = "--- Results of deregisterButtonEvent function call ---\n";
  buttonNode = theForm.dereferenceEx(null, "PAGE1.BUTTON1", 0, 
               FormNodeP.UFL_ITEM_REFERENCE, null);
  if(buttonNode == null) {
    s += " Could not find BUTTON1 on the form.\n";
  } else {
    buttonNode.removeOnFocus(button1OnFocus);
    s += " Function button1OnFocus deregistered.\n";
  }
  alert(s);
}   

--- Results of deregisterButtonEvent function call ---
   Function button1OnFocus deregistered.

Description

This method sets whether the computational system is active. When active, all computes in the form are evaluated on an on-going basis. When inactive, no computes are evaluated.

Note that turning the computational system on causes all computes in the form to be re-evaluated, which can be time consuming.

Method

void setActiveForComputationalSystem ( 
   boolean activeFlag
);

Parameters

Returns

Nothing. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

The sample code turns the compute system off before creating a compute on PAGE1.FIELD2 that copies the value of FIELD1. It then uses getLiteralByRefEx to store the value of FIELD2 before turning the compute system back on and making another call to getLiteralByRefEx. Finally, it displays the results in a JavaScript alert box.

function testSetActiveForComputationalSystem(theForm) {
  var s;
  var fieldNode;
  
  s = "--- Results of setActiveForComputationalSystem test ---\n";
  fieldNode = theForm.dereferenceEx(null, "PAGE1.FIELD2.value", 0,
              FormNodeP.UFL_OPTION_REFERENCE, null);
  if(fieldNode == null) {
    s += " Could not find PAGE1.FIELD2.value on the form.";
  } else {
    theForm.setActiveForComputationalSystem(false);
    fieldNode.setFormula("PAGE1.FIELD1.value");
    s += theForm.getLiteralByRefEx(null, "PAGE1.FIELD2.value", 0, null) + "\n";

    theForm.setActiveForComputationalSystem(true);
    s += theForm.getLiteralByRefEx(null, "PAGE1.FIELD2.value", 0, null) + "\n";
  }
    alert(s);
}
   

--- Results of setActiveForComputationalSystem test ---
This is field 1
This is field 2

Description

This method sets the value of a specific attribute for a node. For example, the following XFDL represents a value node:

   <value custom:myAtt="x"></value>

To change the custom attribute, you would use setAttribute. If the attribute does not already exist, setAttribute will create it and assign the appropriate value.

Method

void setAttribute (
   String uri,
   String localName,
   String value
);

Parameters

   http://www.ibm.com/xmlns/prod/XFDL/7.5

Returns

Nothing. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Notes

   <custom:processing custom:stage="2" user="tjones">

   <a xmlns:custom="ABC" xmlns:test="ABC">
      <custom:myElement id="1" test:id="2">
   </a>

   <custom:myElement id="1">

Example

The sample code adds two attributes to PAGE1.LABEL1. The first attribute is in the custom namespace, and the second attribute is in the null namespace.

function testSetAttribute(theForm) {
  var s;
  var pageNode;
  
  s = "--- Results of setAttribute test ---\n";
  pageNode = theForm.dereferenceEx(null, "PAGE1.LABEL1", 0,
             FormNodeP.UFL_ITEM_REFERENCE, null);
  if(pageNode == null) {
    s += " Could not find PAGE1.LABEL1 on the form.";
  } else {
    pageNode.setAttribute(
             "http://www.ibm.com/xmlns/prod/XFDL/Custom",
             "test", "value");
    pageNode.setAttribute(null, "test", "value");
    s += " Attributes were added to PAGE1.LABEL1\n";
  }
  alert(s);
}

--- Results of setAttribute test ---
 Attributes were added to PAGE1.LABEL1

Description

This method sets the formula for a node.

Method

void setFormula(
   String theFormula
);

Parameters

Returns

Nothing. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

The sample code adds a simple compute to the PAGE1.FIELD3.value node. The compute copies the value of PAGE1.FIELD1 into the value of PAGE1.FIELD3.

function testSetFormula(theForm) {
  var s;
  var node;
  
  s = "--- Results of setFormula test ---\n";
  node = theForm.dereferenceEx(null, "PAGE1.FIELD3.value", 0,
         FormNodeP.UFL_OPTION_REFERENCE, null);
  if(node == null) {
    s += " Could not find PAGE1.FIELD3.value on the form.";
  } else {
    node.setFormula("PAGE1.FIELD1.value");
    s += " Compute was added to PAGE1.FIELD3.value\n";
  }
  alert(s);
}

--- Results of setFormula test ---
 Compute was added to PAGE1.FIELD3.value

Description

This method finds a particular FormNodeP as specified by a reference string. Once the FormNodeP is found, its literal will be set as specified. If the FormNodeP does not exist, this method will create it, but only if the FormNodeP would be an option or argument node.

If necessary, this method can create several nodes at once. For example, if you set the literal for the second argument of an itemlocation, this method will create the itemlocation option node and the two argument nodes and then set the literal for the second argument node.

The node that you call this method on is used as the starting point for the search.

Method

void setLiteralByRefEx(
   String scheme,
   String reference,
   Number referenceCode,
   FormNodeP NSNode,
   String literal
);
   

Parameters

Returns

Nothing. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Notes

   <label sid="Label1">
      <value>Field1.processing:myValue</value>
   </label>
   <field sid="Field1" xmlns:processing="URI">
      <value></value>
      <processing:myValue>10<processing:myValue>
   </field>

   Label1Node.setLiteralByRefEx(null, "Field1.processing:myValue", 0,
      null, null, "20")

   Label1Node.setLiteralByRefEx(null, "Field1.processing:myValue", 0,
      null, Field1Node, "20")

Example

The sample code sets several values on the node PAGE1.FIELD3 then displays a success or failure message in an alert box.

function testSetLiteralByRefEx(theForm) {
  var s;
  var node;
  
  s = "--- Results of setLiteralByRefEx test ---\n";
  node = theForm.dereferenceEx(null, "PAGE1.FIELD3", 0,
         FormNodeP.UFL_ITEM_REFERENCE, null);
  if(node == null) {
  	s += " Cannot locate PAGE1.FIELD3 on the form.\n";
  } else {
      node.setLiteralByRefEx(null, "fontinfo[fontname]", 0, null, "Verdana");
      node.setLiteralByRefEx(null, "fontinfo[fontsize]", 0, null, "10");
      node.setLiteralByRefEx(null, "bgcolor", 0, null, "#ff0000");
      node.setLiteralByRefEx(null, "fontcolor", 0, null, "white");
      node.setLiteralByRefEx(null, "value", 0, null, "This is field 3");
      s += " New properties added to PAGE1.FIELD3.\n";
    }
  }
  alert(s);
}   

--- Results of setLiteralByRefEx test ---
 New properties added to PAGE1.FIELD3.

Description

This method sets the literal of a node. You should only set the literal for option or argument nodes.

Method

void setLiteralEx(
   String literal
);
   

Parameters

Returns

Nothing. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Notes

Example

The sample code moves PAGE1.FIELD3 to a new location.

function testSetLiteralEx(theForm) {
  var s;
  var nodeX, nodeY;
  
  s = "--- Results of setLiteralEx test ---\n";
  nodeX = theForm.dereferenceEx(null, "PAGE1.FIELD3.itemlocation[x]", 0,
          FormNodeP.UFL_ARRAY_REFERENCE, null);
  nodeY = theForm.dereferenceEx(null, "PAGE1.FIELD3.itemlocation[y]", 0,
          FormNodeP.UFL_ARRAY_REFERENCE, null);
  if(nodeX == null || nodeY ==null) {
    s += " Could not find PAGE1.FIELD3.itemlocation[x] or [y] on the form.\n";
  } else {
    nodeX.setLiteralEx("150");
    nodeY.setLiteralEx("350");
    s += " The node 'PAGE1.FIELD3' has been relocated.\n";
  }
  alert(s);
}   

--- Results of setLiteralEx test ---
  The node 'PAGE1.FIELD3' has been relocated.

Description

Updates the XForms model by inserting data anywhere within the XForms instance data, or by replacing it entirely. Call this method on the root node of the form or an instance node.

Typically, the default behavior of updateXFormsInstance is to automatically update the XForms data model once a change has been made. However, for forms that are opened using the method with the UFL_XFORMS_INITIALIZE_ONLY flag, the UFL_SERVER_SPEED_FLAGS flag, or the UFL_SERVER_SPEED_FLAGS_WITH_XFORMS flag, the default behavior of updateXFormsInstance is to mark the model for a deferred update. You can override these default settings using the updateType parameter.

Method

void updateXFormsInstance(
   String modelID,
   String nodeRef,
   FormNodeP NSNode,
   String data,
   Number updateType
);

Parameters

Returns

Nothing. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Notes

The updateXFormsInstance and the extractXFormsInstance methods are the only methods that are intended to modify the XForms data model.

Example

The sample code inserts the city Moscow into an existing instance, and replaces Paris with Montreal. It then displays the new instance data in a JavaScript alert box.

Instance data:

<xformsmodels>
   <xforms:model>
      <xforms:instance id="instance1" xmlns="">
         <document>
            <cities>
               <city>Paris</city>
               <city>Beijing</city>
            </cities>
         </document>
      </xforms:instance>
   </xforms:model>
</xformsmodels>   

Sample code:

function testUpdateXFormsInstance(theForm) {
  var s, sData;
  
  s = "--- Results of updateXFormsInstance test ---\n\n";

  sData = "<city>Moscow</city>"
  theForm.updateXFormsInstance(null,
          "instance('instance1')/cities",
          null, sData, XFDL.UFL_XFORMS_UPDATE_APPEND);
  sData = "<city>Montreal</city>"
  theForm.updateXFormsInstance(null,
          "instance('instance1')/cities/city[1]",
          null, sData, XFDL.UFL_XFORMS_UPDATE_REPLACE);
  
  s += "The updated XForms instance:\n";
  s += theForm.extractXFormsInstance(null, "", true, true, null);

  alert(s);
  
}

--- Results of updateXFormsInstance test ---

The updated XForms instance:
<document>
   <cities>
      <city>Montreal</city>
      <city>Beijing</city>
      <city>Moscow</city>
   </cities>
</document>

Description

This method verifies the correctness of all digital signatures in a given form whose root node is provided. It finds all items of type signature and calls verifySignature for each signature. Errors are logged for all non valid signatures.

This method checks the following conditions for each signature:

• The signature item contains mimedata.
• The mimedata contains a hash value and signer certificate.
• The signer certificate contains the same ID as that recorded in the signature item's signer option.
• The signer certificate has not expired.

Method

Number verifyAllSignatures(
   boolean reportAsErrorsFlag
);

Parameters

Returns

One of the following values:

If one or more of the signatures is not valid and the reportAsErrorsFlag is true, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

The sample code verifies all of the signatures on the form then displays the results in a JavaScript alert box.

 function testVerifyAllSignatures(theForm) {
    var s;
    
    s = "--- Results of verifyAllSignatures test ---\n";
    switch(theForm.verifyAllSignatures(false)) {
    case FormNodeP.UFL_SIGS_OK:
      s += " All signatures on the form are valid.\n";
      break;
    case FormNodeP.UFL_SIGS_NOTOK:
      s += " One or more signatures are broken.\n";
      break;
    case FormNodeP.UFL_SIGS_UNVERIFIED:
      s += " One or more signatures cannot be verified.\n";
      break;
    default:
    
    }
    alert(s);
}   

--- Results of verifyAllSignatures test ---
 All signatures on the form are valid.

Description

This method verifies the correctness of the given digital signature. You supply the root of the form that contains the signature you want to verify. This method checks the following conditions:

• The signature item contains mimedata.
• The mimedata contains a hash value and signer certificate.
• The signer certificate contains the same ID as that recorded in the signature item's signer option.
• The signer certificate has not expired.

A plain text representation of the form (filtered by the signature item's filter) is constructed and the result is hashed. This hash value must match the hash value stored in the signature.

Method

short verifySignature(
   FormNodeP signatureItem,
   StringHolder theCertChain,
   boolean reportAsErrorsFlag
);

Parameters

Returns

A Number having one of the following values, depending on the status of the signature:

If the signature is not valid and the reportAsErrorsFlag is true, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

The sample code attempts to verify the signature item PAGE1.BUTTON1_SIGNATURE_405824760, and checks for a subset of the possible return values. The results are displayed in an alert box.

function testVerifySignature(theForm) {
  var sigNode;
  var s;
  
  s = "--- Results of verifySignature test ---\n";
  sigNode = theForm.dereferenceEx(null, "PAGE1.BUTTON1_SIGNATURE_405824760", 0,
            FormNodeP.UFL_ITEM_REFERENCE, null);
  if(sigNode == null) {
    s +=" Could not find the signature item.";
  } else {
    switch(theForm.verifySignature(sigNode, false)) {
    case FormNodeP.UFL_DS_OK:
      s += " The signature is verified.\n";
      break;
    case FormNodeP.UFL_DS_ALGORITHMUNAVAILABLE:
      s += " Appropriate verification engine is not available.\n";
      break;
    case FormNodeP.UFL_DS_CERTEXPIRED:
      s += " The certificate has expired.\n";
      break;
    case FormNodeP.UFL_DS_UNEXPECTED:
      s += " An unexpected error occured.\n";
      break;
    case FormNodeP.UFL_DS_UNVERIFIABLE:
      s += " The signature cannot be verified.\n";
      break;
    default:
      s += " Signature not valid for unknown reason.\n";
    }
  }
  alert(s);
}

--- Results of verifySignature test ---
 The signature is verified.

Description

This method updates the XML data model in the form. This is necessary if computes have changed the structure of the data model in some way, such as changing or adding bindings. These sorts of changes do not take effect until the xmlModelUpdate method is called.

Method

   void xmlModelUpdate( );   

Parameters

There are no parameters for this method.

Returns

Nothing. On error, the custom error handler registered by the XFDL.registerAPIExceptionHandler method is called with the details of the error. If no handler is registered, the details of the error are displayed in a JavaScript alert() message.

Example

The sample code uses setLiteralByRefEx to change the binding in the form, then calls xmlModelUpdate so that the XML data model reflects the change.

function testXMLModelUpdate(theForm) {
  var s;

  s = "--- Results of verifySignature test ---\n";
  theForm.setLiteralByRefEx(null,
          "global.global.xmlmodel[bindings][0][boundoption]",
          0, null, "PAGE1.FIELD3.value");
  theForm.xmlModelUpdate();
  s += " Bound option changed.";

  alert(s);
}

--- Results of verifySignature test ---
 Bound option changed.