Fire Data Provider Event Action

The action module for this action is "vb/action/builtin/fireDataProviderEventAction".

This causes the DataProvider specified via the 'target' parameter to dispatch an oj.DataProvider event as a way to notify all listeners registered on that DataProvider to react to changes to the underlying data. For example, a component using a particular ServiceDataProvider may need to render new data because new data has been added to the endpoint used by the ServiceDataProvider.

The action can be called either with a mutation event or a refresh but not both. Generally a mutation event is raised when items have been added, updated, or removed from the data that the ServiceDataProvider represents.

Note:

This action can be used with a vb/ArrayDataProvider2. It does not need to be used with a legacy vb/ArrayDataProvider because the 'data' is already exposed as a property on the variable. This allows page authors to directly mutate the data array using the assignVariables action. This assignment is automatically detected by Visual Builder, and all listeners of this change are notified, removing the need to use a fireDataProviderEventAction. Users will be warned when the fireDataProviderEventAction is used with a legacy ArrayDataProvider, prior to mutating the 'data' property directly.

A mutation event can include multiple mutation operations (add, update, remove) as long as the id values between operations do not intersect. This behavior is enforced by JET components. For example, you cannot add a record and remove it in the same event, because the order of operations cannot be guaranteed.

The action can return either success or failure. Success returns null, while failure returns the error string.

Table 1-1 Parameters

Name	Type	Description	Example
target	string	Target of the event, usually a variable of type vb/SDP or vb/ADP.	target: "{{ $page.variables.incidentList }}"
refresh	null	Indicates a data provider refresh event needs to be dispatched to the data provider identified by the target. A null value is specified because the refresh event does not require a payload.	refresh: null
add	object	The following properties may be present in the payload: data: Array<Object>; the results of the 'add' operation. Note there can be more than one rows added. If data alone is present in the payload, and the target has a keyAttributes property specified, then the 'keys' are built for you. The structure of the data returned must be similar to the responseType specified on the target variable of type vb/ServiceDataProvider (respecting the "itemsPath", if any), or the itemType specified on the vb/ArrayDataProvider keys: optional Set<>. the keys for the rows that were added. If a ServiceDataProvider variable is configured with a keyAttributes property, this can be determined by the ServiceDataProvider itself from the data, if data is present. metadata: optional Array<ItemMetadata<Object>>. Since the ServiceDataProvider variable is configured with 'keyAttributes', this can be determined by the ServiceDataProvider itself. addBeforeKeys: Optional Array of keys for items located after the items involved in the operation. They are relative to the data array, after the operation was completed and not the original array. If null and index are not specified, then insert at the end. afterKeys: Deprecated: use addBeforeKeys instead. Optional Set<>; a Set that is the keys of items located after the items involved in the operation. If null and index not specified then insert at the end. indexes: optional Array<number>, identifying insertion point.	"add": { "data": "{{ $chain.results.saveProduct.body }}", "indexes": [0] } An example with ServiceDataProvider, where "itemsPath": "items": "updateList": { "module": "vb/action/builtin/fireDataProviderEventAction", "parameters": { "target": "{{ $page.variables.personList }}", "add": { "data": { "items": "{{ [$chain.results.createPersonPost.body] }}" } } } }
remove		The payload for the remove event is similar to add above except 'afterKeys'/'addBeforeKeys' are not present.	"remove": { "keys": "{{ [ $page.variables.productId ] }}" }
update		Same as remove.	"update": { "data": "{{ $page.variables.currentIncidentResponse }}" }

The action can return two outcomes:

The name of the outcome can be 'success' or 'failure'.
The result of a failure outcome is the error string, and the result of a success outcome is null.

Example 1-19 Example 1

Configuring a refresh event to be dispatched to a ServiceDataProvider:

(1) activityListDataProvider is the name of the
page variable that is of type vb/ServiceDataProvider
(2) refresh has a null value
  
"fireDataProviderRefreshEventActionChain": {
  "variables": {
    "payload": {
      "type": {
        "target": "activityListDataProvider"                           // (1)
      }
    }
  },
  "root": "fireEventOnDataProvider",
  "actions": {
    "fireEventOnDataProvider": {
      "module": "vb/action/builtin/fireDataProviderEventAction",
      "parameters": {
        "target": "{{ $page.variables[$variables.payload.target] }}",
        "refresh": null                                               // (2)
      }
    }
  }
},

Example 1-20 Example 2

Configuring a remove event to be dispatched to a ServiceDataProvider:

(1) deleteProductChain deletes a product and ends up calling
another chain that fires a remove event on the ServiceDataProvider
(2) deletes the product from the backend service via a RestAction
(3) calls fireDataProviderEventAction
(4) on a variable of type vb/ServiceDataProvider
(5) with a remove payload
  
"variables": {
  "productListSDP": {
    "type": "vb/ServiceDataProvider",
    "defaultValue": {
      "keyAttributes": "id",
      "responseType": "application:productSummary[]"
    }
  },
}
"chains": {
  "deleteProductChain": { // (1)
    "variables": {
      "productId": {
        "type": "string",
        "description": "delete a single product",
        "input": "fromCaller",
        "required": true
      }
    },
    "root": "deleteProduct",
    "actions": {
      "deleteProduct": { // (2)
        "module": "vb/action/builtin/restAction",
        "parameters": {
          "endpoint": "ifixitfast-service/deleteProduct",
          "uriParams": {
            "productId": "{{ $page.variables.productId }}"
          }
        },
        "outcomes": {
          "success": "refreshProductList"
        }
      },
      "refreshProductList": {
        "module": "vb/action/builtin/callChainAction",
        "parameters": {
          "id": "fireDataProviderMutationEventActionChain",
          "params": {
            "payload": {
              "remove": {
                "keys": "{{ [ $page.variables.productId ] }}"
              }
            }
          }
        }
      }
    }
  },
  "fireDataProviderMutationEventActionChain": {
    "variables": {
      "payload": {
        "type": "application:dataProviderMutationEventDetail",
        "input": "fromCaller"
      }
    },
    "root": "fireEventOnDataProvider",
    "actions": {
      "fireEventOnDataProvider": {
        "module": "vb/action/builtin/fireDataProviderEventAction", // (3)                  // (2)
        "parameters": {
          "target": "{{ $page.variables.productListSDP }}",    // (4)
          "remove": "{{ $variables.payload.remove }}" // (5)
        }
      }
    }
  }
},