Plugin API » Forms » Replaceable forms

Replaceable forms

Forms defined using replaceableForm() may be replaced by other plugins when they’re used. You can use the form ID and the contents to determine which form to replace it by.

You can use replaceable forms for:

• implementing generic plugins, and customising their forms in customer specific plugins.

• implementing backwards compatibility by inspecting the document contents and returning legacy versions of the form for older data.

When instance() is called on a FormDescription object, the "std:form:replace" service is called with two arguments, the form and the document.

To determine which form is being replaced, you must check both form.formId and form.plugin.pluginName as multiple plugins can define forms with the same name.

Returning a new form from that service uses that form instead. If the service isn’t implemented or no service implementation returns a form, the original form is used.

Example

var alternativeForm = P.form("alt0","form/alt0.json");

P.implementService("std:form:replace", function(form, document) {
    if(
        (form.formId === "form0") &&
        (form.plugin.pluginName === "example_plugin")
    ) {
        // NOTE: Could use document contents to choose form
        return alternativeForm;
    }
});