Frontend Background Update

The client side background update requires the server side hook implementation and a client side handler registration.

Server side implementation

The hook slot is provided by system (system.multiplex) and the all provided hooks must implement the following interface:

XELOS\Framework\XF\System\Hook\FrontendBackgroundUpdateInterface

Hook implementations must provide the method "response" which is called to return a json compatible data array. This array will be returned as json string to the client, which will pass it to the registered handler callback. The "response" method have an optional array parameter which contains client side created data. This data array can be considered to process only targeted information.

Hook implementation example:

<?php
public function response(array $userIds = []) {
    # Contains all data for response
    $response = [];

    # process only requested user ids given by data parameter to avoid overhead
    foreach ($userIds as $userId){
            $response[$userId] = ['status' => 'online'];
    }

    # This array will be pass as json to the client side registered response handler
    return $response;
}

Client side implementation

The XELOS js library provides an global object to register the response handler and data provider.

XF_JS.BackgroundUpdater

The handler registration requires a global unique identifier which is the same as the hook id on server side but uses a ":" instead of "." as separator. The handler is a callback with json parameter that contains the server response. Optionally you can pass a third registration as callback. This callback is used as data provider which created the client side data that sends to the server side processor.

Handler registration:

XF_JS.BackgroundUpdater.register(identifier, responseHandlerCallback, dataProviderCallback);

Implementation example:

XF_JS.BackgroundUpdater.registerHook('mymodule:myhook_multiplex', function(response){
    MyComponent.doSomethinWithNewData(response.something);
}, function(){ // optional
    return MyComponent.someDataAsObject;
});

The registration can be done by an alternate way:

~~~javascript XF_JS.BackgroundUpdater.registerHook({ identifier: 'mymodule:myhook_multiplex', responseHandler:function(response){ MyComponent.doSomethinWithNewData(response.something); }, dataProvider:function(){ return MyComponent.someDataAsObject; }, suspend:function(){ return true || false; // based on custom logic } }); ~~~

The last optional parameter "suspended" can be used to decide whether the request for this hook should be skipped or not. If true, this hook will be ignored for the next request.

In case the the client side hook handler want to display the last state after a page reload without to wait until the refresh call is fired, it can use the "onLoad" entry in the registration. This will persist the last valid response data into browsers local storage automatically and call the "onLoad" callback recently after page reload with the latest data saved from last response.

 XF_JS.BackgroundUpdater.registerHook({
    identifier: 'mymodule:myhook_multiplex',
    responseHandler:function(response){ },
    dataProvider:function(){ },
    suspend:function(){ },
    onLoad:function(data){
      // do some special with the data or just call the responseHandler
      // for default behavior
      this.responseHandler(data);
    }
 });

If the onLoad function is defined, the BackgroundUpdater will save all responses for this hook into "lastResponse" object variable that can be accessed from each callback.

XF_JS.BackgroundUpdater.registerHook({
   // ...
   onLoad:function(data){
      // do something with this info
     this.responseHandler(data);
   }
});