Using the instance manager to control subforms at run time

This example demonstrates how to use properties and methods of the instance manager to retrieve information about subforms and perform operations on subform objects at run time.

In this example, the form filler uses the buttons to perform various actions using instances of Subform3. For example, when the form filler clicks the Add Row Below button a new Subform3 instance is added below the current instance.

Note: You may need to add or remove subforms, or make changes to the data in the text field, to see the changes applied to the instances of Subform3.

View full size graphic

Note: If no instances of a particular subform exist on your form, you must use the underscore (_) notation provided with each example below. For more information about using the underscore (_) notation, see Designer Help.

Scripting the Add a New Subform button

The following script determines whether the supported maximum number of Subform3 instances exist on the form. If the maximum number exist, the script displays a message. Otherwise, a new Subform3 instance is added to the form.

    if (advanced.Subform3.instanceManager.count == 
        advanced.Subform3.instanceManager.max) { 
        xfa.host.messageBox("You have reached the maximum number of items 
        allowed.","Combining Instance Manager Concepts", 1); 
    } 
    else { 
        advanced.Subform3.instanceManager.addInstance(1); 
        xfa.form.recalculate(1); 
    }

You can also write this script by using the underscore (_) notation to reference the properties and methods of the instance manager, as shown here:

    if (advanced._Subform3.count == advanced._Subform3.max) { 
        xfa.host.messageBox("You have reached the maximum number of items 
        allowed.", "Combining Instance Manager Concepts", 1); 
    } 
    else { 
        advanced._Subform3.addInstance(1); 
        xfa.form.recalculate(1); 
    }

Scripting the Remove a Subform button

The following script determines whether any Subform3 instances exist on the form. If none exist, the script displays a message indicating that no instances exist. If instances exist, the script removes the first instance from the form.

    if (advanced.Subform3.instanceManager.count == 0) { 
        xfa.host.messageBox("There are no subform instances to remove.",  
        "Combining Instance Manager Concepts", 1);     
    } 
    else { 
        advanced.Subform3.instanceManager.removeInstance(0); 
    }

You can also write this script by using the underscore (_) notation to reference the properties and methods of the instance manager, as shown here:

    if (advanced._Subform3.count == 0) { 
        xfa.host.messageBox("There are no subform instances to remove.", 
        "Combining Instance Manager Concepts", 1);     
    } 
    else { 
        advanced._Subform3.removeInstance(0); 
    }

Scripting the Add Instance Below button

The following if-else statement prevents the script from proceeding if the form currently contains the maximum number of Subform3 instances:

    if (Subform3.instanceManager.count < Subform3.instanceManager.occur.max) { 
//oNewInstance stores an instance of Subform3 created by the addInstance() method. 
    var oNewInstance = Subform3.instanceManager.addInstance(1); 
//nIndexFrom and nIndexTo store the before and after index values to use with the moveInstance() method.  
    var nIndexFrom = oNewInstance.index; 
    var nIndexTo = Subform3.index + 1;

In this case, when the script references the value for nIndexFrom, the new instance of Subform3 is added to the form in the position specified in the moveInstance method:

        Subform3.instanceManager.moveInstance(nIndexFrom, nIndexTo); 
    } 
    else { 
        xfa.host.messageBox("You have reached the maximum number of items 
        allowed.", "Combining Instance Manager Concepts", 1); 
    }

You can also write this script by using the underscore (_) notation to reference the properties and methods of the instance manager, as shown here:

    if (_Subform3.count < _Subform3.occur.max) { 
    var oNewInstance = _Subform3.addInstance(1); 
    var nIndexFrom = oNewInstance.index; 
    var nIndexTo = Subform3.index + 1; 
    _Subform3.moveInstance(nIndexFrom, nIndexTo); 
    } 
    else { 
    xfa.host.messageBox("You have reached the maximum number of items allowed.",         "Combining Instance Manager Concepts", 1); 
    }

Scripting the Delete This Instance button

The following if-else statement prevents the script from proceeding if the form currently contains the minimum number of Subform3 instances.

if (Subform3.instanceManager.count > Subform3.instanceManager.occur.min) {

This script uses the removeInstance method to remove an instance of Subform3.

Note: This script uses the value parent.parent.index to indicate the Subform3 instance to remove. The parent reference indicates the container of the object using the reference. In this case, using the reference parent.index would indicate the untitled subform that contains the Add Instance Below, Delete This Instance, Move Row Up, and Move Row Down buttons.

        Subform3.instanceManager.removeInstance(parent.parent.index); 
    } 
    else { 
        xfa.host.messageBox("You have reached the minimum number of items 
        allowed.", "Combining Instance Manager Concepts", 1); 
    }

You can also write this script by using the underscore (_) notation to reference the properties and methods of the instance manager, as shown here:

    if (_Subform3.count > _Subform3.occur.min) { 
    Subform3.removeInstance(Subform3.index); 
    } 
    else { 
    xfa.host.messageBox("You have reached the minimum number of items allowed.",  
    "Combining Instance Manager Concepts", 1); 
    }

Scripting the Move Row Up button

The following if-else statement prevents the script from proceeding if the instance of Subform3 appears as the first instance in the list:

    if (Subform3.index != 0) { 
//nIndexFrom and nIndexTo store the before and after index values to use with the moveInstance method.  
        var nIndexFrom = Subform3.index; 
        var nIndexTo = Subform3.index - 1; 
        Subform3.instanceManager.moveInstance(nIndexFrom, nIndexTo); 
    } 
    else { 
        xfa.host.messageBox("The current item cannot be moved because it is the  
        first instance in the list.", "Combining Instance Manager Concepts", 1); 
    }

You can also write this script by using the underscore (_) notation to reference the properties and methods of the instance manager, as shown here:

    if (Subform3.index != 0) { 
        var nIndexFrom = Subform3.index; 
    var nIndexTo = Subform3.index - 1; 
    Subform3.moveInstance(nIndexFrom, nIndexTo); 
    } 
    else { 
    xfa.host.messageBox("The current item can't be moved since it already is the     first instance in the list.", "Combining Instance Manager Concepts", 1); 
    }

Scripting the Move Row Down button

This variable stores the index value of the instance of Subform3:

var nIndex = Subform3.index;

The following if-else statement prevents the script from proceeding if the instance of Subform3 appears as the last instance in the list:

    if ((nIndex + 1) < Subform3.instanceManager.count) { 
    // nIndexFrom and nIndexTo store the before and after index values to use with the moveInstance() method.  
        var nIndexFrom = nIndex; 
        var nIndexTo = nIndex + 1; 
     
        Subform3.instanceManager.moveInstance(nIndexFrom, nIndexTo); 
        } 
        else { 
        xfa.host.messageBox("The current item cannot be moved because it is the last 
        instance in the list.", "Combining Instance Manager Concepts", 1); 
        }

You can also write this script by using the underscore (_) notation to reference the properties and methods of the instance manager, as shown here:

    var nIndex = Subform3.index; 
    if ((nIndex + 1) < Subform3.instanceManager.count) { 
    var nIndexFrom = nIndex; 
    var nIndexTo = nIndex + 1; 
    _Subform3.moveInstance(nIndexFrom, nIndexTo); 
    } 
    else { 
    xfa.host.messageBox("The current item can't be moved since it already is the 
    last instance in the list.", "Combining Instance Manager Concepts", 1); 
    }