Events

At design time, a page author may need to know what features and capabilities the endpoint supports, and they may need to configure the correct properties and transforms.

Events

The events raised by the data provider are defined by contract for oj.DataProvider. These events are fired at appropriate times to notify UI components. Page authors may need to force the variable to fire some of the DataProvider events, including 'add', 'remove', 'refresh', and 'update'.

vbDataProviderNotification Event Listener

Page authors can register an event listener of this type in order to be notified of catastrophic errors that may occur when something goes wrong during an implicit fetch. For an externalized fetch, where the fetch is externalized to a action chain, the current mechanism of handling failure outcomes can continue to be used.

For example, on the page, the listeners property can have this definition:

"vbDataProviderNotification": {
  "chains": [
    {
      "chainId": "someChainX"
    }
  ]
}

The event payload available to the listener is an object that has the following properties:

• severity: a string
• detail: any details of the error, such as REST failure details
• capability: an object with the capabilities configured on the ServiceDataProvider
• fetchParameters: an object with the parameters passed to the fetch
• context: an object representing the state of the ServiceDataProvider at the time the fetch was initiated
• id: uniqueId, a string, the id of the ServiceDataProvider instance
• key: since the event can be fired multiple times, this identifies the event instance

Page authors can use this to display an error message.

Example 1-6 Firing a DataProvider event by using a fireDataProviderEvent action

A page is configured to have a master list and detail form showing the details of the current selected row on the list. Suppose that the form is wired to PATCH to a different endpoint than the one configured on the list. When the user updates the form data, it's desirable for the same actionChain to also raise the 'update' event on the ServiceDataProvider so it can show the changes to the current row. To configure the page:

<!-- list view bound to page variable incidentListTableSource --> 
<oj-list-view id="listview" 
              data="{{$variables.incidentListTableSource}}" 
... 
</oj-list-view> 

<!-- form UI fields bound to page variable currentIncident --> 
<div class="oj-form-layout" 
  <div class="oj-form" 
    <div class="oj-flex" 
      <div class="oj-flex-item" 
        <oj-label for="problem"Problem</oj-label> 
      </div> 
      <div class="oj-flex-item" 
        <oj-input-text id="problem" 
                       value="{{$variables.currentIncident.problem}}" 
                       required=true</oj-input-text> 
      </div>
    </div> 
...

<!-- Save button bound to componentEvent handler 'saveIncident' -->
<oj-button href="#" id='saveButton'
           label='Save' 
           on-dom-click='[[$componentEvents.saveIncident]]'</oj-button>

// saveIncident calls the actionChain 'saveIncidentChain', which
// (1) defines 2 variables - incidentId and incidentPayload
// (2) then calls a REST action to put/patch payload
// (3) then it takes the result from (2) and assigns to incidentsResponse chain 
//     variable,
// (4) calls an actionChain to fire a data provider event to refresh the SDP page
//     variable
// (5) an update event payload passed to the action chain
"saveIncidentChain": {
  "variables": {                                                // (1)
    "incidentId": {
      "type": "string",
      "description": "the ID of the incident to update",
      "input": "fromCaller",
      "required": true
    },
    "incidentPayload": {
      "type": "object",
      "description": "the payload of the incident data",
      "input": "fromCaller",
      "required": true
    },
    "incidentsResponse": {
      "type": "application:incidentsResponse"
    }
  },
  "root": {
    "id": "saveIncidentToRest",                                 // (2)
    "module": "vb/action/builtin/restAction",
    "parameters": {
      "endpoint": "ifixitfast-service/putIncident",
      "uriParams": {
        "id": "{{ $variables.incidentId }}"
      },
      "body": "{{ $variables.incidentPayload }}"
    },
    "outcomes": {
      "success": "assignVariables_incidentsResponse"
    }
  },
  "assignVariables_incidentsResponse": {
    "module": "vb/action/builtin/assignVariablesAction",
    "parameters": {
      "$variables.incidentsResponse.result": {
        "source": "{{ $chain.results.saveIncidentToRest.body }}" // (3)
      }
    },
    "outcomes": {
      "success": "updateIncidentList"
    }
  },
  "updateIncidentList": {
    "module": "vb/action/builtin/callChainAction",
    "parameters": {
      "id": "fireDataProviderMutationEventActionChain",         // (4)
      "params": {
        "payload": {
          "update": {                                           // (5)
            "data": "{{ $variables.incidentsResponse }}"
          }
        }
      }
    }
  }
}

"fireDataProviderMutationEventActionChain": {
  "variables": {
    "payload": {
      "type": "application:dataProviderMutationEventDetail",
      "input": "fromCaller"
    }
  },
  "root": "fireEventOnDataProvider",
  "actions": {
    "fireEventOnDataProvider": {
      "module": "vb/action/builtin/fireDataProviderEventAction",
      "parameters": {
        "target": "{{ $page.variables.incidentListDataProvider }}", // SDP variable 
                                                     // on which the event is fired
        "add": "{{ $variables.payload.add }}",
        "remove": "{{ $variables.payload.remove }}",
        "update": "{{ $variables.payload.update }}" // has the updated record details
      }
    }
  }
},