Community articleCreate function
Added by IBM contributorIBM on May 2, 2012
Rate this article 1 starsRate this article 2 starsRate this article 3 starsRate this article 4 starsRate this article 5 stars

No abstract provided.



Description

This function creates a new IFormNodeP and attaches it to the form hierarchy at the indicated location. Once created, the type and identifier of a IFormNodeP cannot be changed.
Note that you can also use SetLiteralByRefEx to create an IFormNodeP at the option level and below. Using SetLiteralByRefEx is often easier and faster than using Create.

Function

   Function Create(
      aNode As IFormNodeP, 
      where As Long, 
      theType As String, 
      theLiteral As String, 
      theFormula As String, 
      theIdentifier As String
      ) As IFormNodeP


Parameters

Table 1. create parameters
ExpressionTypeDescription
aNodeIFormNodePThe new IFormNodeP is placed in the form hierarchy in relation to this node. If null, this creates a new IFormNodeP hierarchy (a new form)
whereLong
A constant that describes the location, in relation to the parameter aNode, in which the new node should be placed:
UFL_APPEND_CHILD — adds the new node as the last child of aNode.
UFL_AFTER_SIBLING — adds the new node as a sibling of aNode, placing it immediately after that node.
UFL_BEFORE_SIBLING — adds the new node as a sibling of aNode, placing it immediately before that node.
Note: If the parameter aNode is null, then this parameter should be set to 0.
theTypeStringThe type to assign to the IFormNodeP being created. This is only necessary for page and item nodes. Use null for all other nodes. The type cannot be changed after the node has been created.
If you are creating a non-XFDL node, you must also include the namespace that the node should belong to, as shown:
   <namespace prefix>:<type>

For example:
   custom:myItem

If you do not provide a namespace, the function will assign the default namespace for the form.
theLiteralStringThe literal to assign to this IFormNodeP. null is valid.
theFormulaStringThe formula to assign to this IFormNodeP. null is valid.
theIdentifierStringThe identifier to assign to this IFormNodeP. The identifier cannot be changed after the node has been created. null is valid.
If you are creating an option or argument level node, this must also include the namespace the node should belong to. Use the following format:
   <namespace prefix>:<type>

For example:
   custom:myOption

If you do not provide a namespace, the function will assign the default namespace for the form.


Returns

The new IFormNodeP or throws an exception if an error occurs.

Example

The following example adds a label to a form. A node is passed into the function, which then uses GetLiteralByRefEx to read the value of a field. The function then uses DereferenceEx to locate the field node, and creates a label node as a sibling using Create. Finally, the function creates a value for the new label node using SetLiteralByRef.
   Sub AddLabel(Form)
 
      Dim TempNode, XFDL ' objects
      Dim Name ' strings
 
      Set TempNode = Form
      
      ' Get the value of the NameField.value option node
 
      Name = TempNode.GetLiteralByRefEx(vbNullString, _
         "PAGE1.NameField.value", 0, vbNullString, Nothing)
 
      ' Locate the NameField item node in the first page of the form
      
      Set TempNode = TempNode.DereferenceEx(vbNullString, _
      "PAGE1.NameField", 0, UFL_ITEM_REFERENCE, Nothing)
      
      ' Get an XFDL object
      
      Set XFDL = CreateObject("PureEdge.xfdl_XFDL")
      
      ' Create a label.  This label is created as a sibling of the NameField,
      ' and is named NameLabel.
      
      Set TempNode = XFDL.Create(TempNode, UFL_AFTER_SIBLING, "label", _
         vbNullString, vbNullString, "NameLabel")
      
      ' Create a value option for the label.  This option is assigned the 
      ' value of Name (as read from the field)
      
      TempNode.SetLiteralByRefEx vbNullString, "value", 0, vbNullString, _
         Nothing, Name
   End Sub


Parent topic:
XFDL functions