Create a button to add and remove a section

Create add and delete buttons

In interactive form designs, it is common practice to have one or more sections in the form that are not displayed until the user selects the option to include it. With Designer, you can add a button along with a script that dynamically adds or removes a particular section (subform) from the form when the user clicks a button.

For example, in the sample interactive Purchase Order, the user can click the Add Comments button to display the Comments section (comments subform). The button has one of two alternating captions, Add Comments or Clear Comments, depending on the current state of the subform. Each time the user clicks the button, the script checks whether the comments subform is displayed and then updates the button caption accordingly.

The button triggers a script that uses instanceManager, the XML Form Object Model object that manages the instance creation, removal, and movement of form objects. When the end user deletes the Comment subform, the instanceManager object removes the subform from both the Form data document object model (DOM) and the Data DOM.

Note that instanceManager uses four methods: addInstance, removeInstance, moveInstance, and setInstances. The naming convention of an instanceManager is the subform name prefixed with an underscore (_subformname). The syntax for instanceManager is_subformname.methodname().

In the sample interactive Purchase Order form, the form author typed the following JavaScript script in the Script Editor by using the setInstances method to add and remove the comments subform and change the button’s caption. Notice that the comments.count == 0 property returns the number of subform instances instantiated.

// Invoke the Instance Manager to add and remove the comments subform. 
 
if (_comments.count == 0) {// The count property specifies the current number      
                                            // of instances instantiated. 
    _comments.setInstances(1);                                                // Add the comments subform. 
    this.resolveNode("caption.value.#text").value = "Clear Comments";                                                                                                            // Change the button's caption. 
} 
 
else { 
    _comments.setInstances(0);                                                // Remove the comments subform. 
    this.resolveNode("caption.value.#text").value = "Add Comments";                                                                                                            // Change the button's caption. 
}

You can also use the ActionBuilder dialog box on the Tools menu to build common interactive capabilities in forms that have a flowable layout, without writing scripts.

Create add and delete buttons

Adding buttons to an interactive form provides end users with a way to initiate an action, such as adding and deleting instances of subforms that define sections such as item lines in an order form.

You can also add a tool tip to the delete button to display the words “Delete Item” when the user positions the pointer over the button. Using separate delete buttons is a good way to allow users to remove specific rows from the form.

For example, the sample interactive Purchase Order has an Add Item button and a delete button labeled “X” for each detail subform. When the user clicks the Add Item button, a script adds an item line. Alternatively, when the user clicks one of the delete buttons, a script deletes the associated item line.

You can also use the Action Builder dialog box on the Tools menu to build common interactive capabilities in forms that have a flowable layout, without writing scripts. See Building actions in forms.

Add Item button

The following JavaScript script in the click event of the Add Item button lets users add an item line to the sample interactive Purchase Order form. The script also recalculates the form so that the Total field includes the new line in the calculation.

Because users only add item lines by using the Add Item button, the script does not need to verify the minimum count (occurrence) value.

// Invoke the Instance Manager to add one instance of the detail subform. 
_detail.addInstance(1); 
 
//Invoke the recalculate method to include the field values from the added subform in calculations. 
xfa.form.recalculate(1);

Delete button

The following JavaScript script in the click event of the Delete button lets users use the Delete button to delete an instance of the detail subform from the sample interactive Purchase Order form. The script also recalculates the form so that the Total field no longer includes the deleted line in the calculation.

// Invoke the Instance Manager to remove the current instance of the detail subform. 
_detail.removeInstance(this.parent.index); 
 
// Invoke the recalculate method to update the form calculations. 
xfa.form.recalculate(1);

Because the initial minimum occurrence value for the detail subform is 2, the script needs to reduce the minimum occurrence value to allow the person filling the form to delete the two item lines that appear automatically when the form is rendered. This script is added to the initialize event of the detail subform.

// Reset the minimum occurrence value of the detail subform. 
this.occur.min = "0";

Because the form allows users to delete all instances of the detail subform, the script for the calculate event of the Total field (numTotal) must verify that at least one instance of the numAmount field in the detail subform exists. Otherwise, an error appears because the calculation cannot find any occurrences of the numAmount field. This script is added to the Calculate event of the numTotal field.

// Verify at least one instance of the numAmount field exists. 
if (exists(detail[0].numAmount) == 1) then 
    Sum(detail[*].numAmount) 
endif