Adds (registers) a JSDO plugin object with a specified name in the current document context that can be used with a supported Data Object operation invoked on a JSDO instance.

Return type: null

Applies to: progress.data.PluginManager class

Syntax

progress.data.PluginManager.addPlugin( name , plugin )
name
A string expression that evaluates to the name of the plugin. If a plugin by this name already exists, the method throws an exception.
Note: The PluginManager class provides access to a built-in plugin with the reserved name, "JFP", which you can customize as described further in this topic. You can also customize any other JSDO plugin that you have already registered.
plugin
A plugin Object that you can define with certain properties. Each property references the definition of a function that you provide. Each function executes according to the requirements of the supported Data Object operation invoked by any JSDO instance.

This method currently supports only MappingType plugins registered for the Read operation. A MappingType plugin object can contain any or all of the following properties:

  • requestMapping — Defines a function that must return an object with properties that define the parameters passed to the JSDO Read operation method (fill( ) or read( )). This function thus allows you to specify or modify any or all of the properties that you can include in a Read operation method's parameter-object argument before the method executes, thus affecting how the Read operation request is invoked across the network. The function must have the following signature:
    function ( jsdo , params , info )
    jsdo
    A reference to the progress.data.JSDO object that corresponds to the JSDO on which the Read operation method was invoked.
    params
    A reference to the Object passed to the Read operation method as its parameter-object argument.
    info
    A reference to an Object with a single operation property set to the value, "read".
  • responseMapping — Defines a function that must return an object with properties that provide the data returned from the corresponding Read operation executed on the server. This function allows you to process the network response from the Read operation in some way. The function must have the following signature:
    function ( jsdo , response , info )
    jsdo
    A reference to the progress.data.JSDO object that corresponds to the JSDO on which the Read operation method was invoked.
    response
    A reference to the Object that contains data properties returned from the Read operation across the network. For more information, see the description of the response property of JSDO request object for returning Read operation output.
    Note: If this responseMapping function customizes the built-in "JFP" plugin or defines a custom plugin based on this built-in plugin, in the body of the function, you can set the value of the JSDO user-defined "server.count" property to a corresponding response property that holds the total count of records returned in the Read operation result set. This has the equivalent effect of specifying a Count operation for the server Data Object to return the same value. For more information, see the Example in this topic.
    info
    A reference to an Object with a single operation property set to the value, "read".

The built-in "JFP" MappingType plugin is available to support JSDO access by a Kendo UI DataSource. For more information on this "JFP" plugin, see the description of the fill( ) method. Although you cannot create your own plugins with this name, you can reference the built-in "JFP" plugin, for example, to create a custom requestMapping or responseMapping function for it, or to create an entirely new plugin based on the existing built-in "JFP" plugin. For more information see the Example in this topic.

To allow an OpenEdge Data Object Read operation to use either the built-in "JFP" or your custom MappingType plugin, you must annotate the ABL method that implements the operation to identify the plugin to use. For more information, see the Notes in this topic.

Example

The following JSDO plugin example adds a new plugin, "MYJFP", which is based on the built-in "JFP" plugin. The example begins by returning a reference to the built-in "JFP" plugin object in the current document context as jfpPlugin and invokes addPlugin( ) to register the new "MYJFP" plugin, as follows:

jsdo = new progress.data.JSDO( . . . );

var jfpPlugin = progress.data.PluginManager.getPlugin("JFP");

progress.data.PluginManager.addPlugin("MYJFP", {

    requestMapping: function(jsdo, params, info) {

        var requestParams = {},
            object = {};
        params = jfpPlugin.requestMapping(jsdo, params, info);
        if (params && typeof params.filter === "string") {
            object = JSON.parse(params.filter);
        }
        object.mydata = jsdo.getProperty("mydata");
        requestParams.filter = JSON.stringify(object);

        // You must return the [updated] parameter object 
        return requestParams;

    }

    responseMapping: function(jsdo, response, info) {

        var record;
        var newData = response.dsEmployee.ttEmployee;
        if (info.operation === "read") {

            for (var i = 0; i < newData.length; i++) {
                record = newData[i];
                record.VacDays = record.VacDays + 10;
            }

            jsdo.setProperty("server.count", response.myTotal);
        }

        // You must return the [updated] response object 
        return response;

    }
});

For the new requestMapping function, the example builds and returns a custom params object (requestParams) from both the params object returned by the existing requestMapping function invoked on the built-in "JFP" plugin and an additional mydata property returned as a custom JSDO property that has already been set on the currently executing JSDO instance (jsdo).

For the new responseMapping function, the example first tests that the function is executing in the context of a Read operation and applies a common update to the returned dsEmployee.ttEmployee table, adding 10 days to the VacDays field of each record. It then sets the reserved custom JSDO property, "server.count", on the currently executing JSDO instance (jsdo) to the custom value returned from the server as response.myTotal before returning the updated response from the Read operation.

Notes

  • If you want to dynamically update the definition for an existing plugin, whether it is the built-in "JFP" plugin or a custom plugin you have previously registered, you can invoke the getPlugin( ) method to return a reference to the plugin object and assign the appropriate property to the updated function definition. For example, to assign an updated definition for the responseMapping function of an existing custom plugin named "myReadPlugin", you can invoke code similar this: 
    progress.data.PluginManager.getPlugin("myReadPlugin").responseMapping 
    = function(jsdo, response, info) { /* Your new definition */ };

    For an example, see the description of the getPlugin( ) method.

  • For an OpenEdge Data Object Read operation to use the specified MappingType plugin from the client document context, you must properly annotate the definition of the Read operation method in the ABL Business Entity that defines the server Data Object. This annotation defines a mappingType property in the Data Service Catalog with a string value that is identical to the name of a MappingType plugin you have registered for the JSDO instance on the client. You specify this annotation with the following syntax:
    @openapi.openedge.method.property (name="mappingType", value="plugin-name").

    Where "plugin-name" is the quoted name that you used to register the custom plugin with the addPlugin( ) method. For example, on the definition of an ABL Read operation method, ReadEmployee( ), you might add this annotation for a plugin registered with the name "MYJFP": 

    @openapi.openedge.export(type="REST", useReturnValue="false", writeDataSetBeforeImage="true").
@progress.service.resourceMapping(type="REST", operation="read", URI="?filter=~{filter~}", alias="", mediaType="application/json"). 
@openapi.openedge.method.property (name="mappingType", value="MYJFP").
METHOD PUBLIC VOID ReadEmployee(
    INPUT filter AS CHARACTER, 
    OUTPUT DATASET dsEmployee):
    SUPER:ReadData(filter).

END METHOD.

    When this ReadEmployee( ) method executes on the server, it uses the parameter values passed by the client JSDO and provided by any requestMapping function defined in the "MYJFP" JSDO plugin, and the JSDO then handles the response according to the processing provided by any responseMapping function defined in the same plugin.

    Note: When annotating for use of the built-in "JFP" plugin only, you must also add an annotation that defines an associated capabilities property for that plugin. For more information on annotations required for using the built-in "JFP" plugin, see the description of Business Entity updates for access by the Kendo UI DataSource in OpenEdge Development: Web Services. However note, if you are annotating a custom plugin that is based on the built-in "JFP" plugin (such as the sample "MYJFP" plugin annotated here), you do not also need to annotate an associated capabilities property for that custom plugin.

See also

fill( ) method, getPlugin( ) method, progress.data.JSDO class