Merge Transform Options Function

mergeTransformOptions function signature:

A page author can use the mergeTransformOptions function callback on the ServiceDataProvider fetch to fix up the transforms options that will be passed to the transform functions, if and when needed. The function will be passed two parameters: 'configuration' and 'transformOptions'. 

The configuration object will contain one set of { capability, context, externalContext, fetchParameters } set as a request is servicing one fetch capability.

For the configuration object, this table describes configuration parameters for the fetchByKeys capability.

Sub-property	Sub-property	Value	Description
capability	-	fetchByKeys	A hint that supplies the author the fetch capability.
context	idAttribute itemsPath uriParameters filterCriterion sortCriteria pagingCriteria responseType capabilities fetchByKeys keys ...	-	Provides a snapshot of the ServiceDataProvider variable at the time the fetchByKeys() call is made. For external chains, the state may not include all properties listed here.
externalContext			If the fetch was externalized then the context setup on the RestAction
fetchParameters	keys	-	The original parameters passed in via the fetchByKeys call.

This table describes configuration parameters for the fetchByOffset capability.

Property	Sub-property	Value	Description
capability	-	fetchByOffset	A hint telling the author the fetch capability for the current request.
context	idAttribute itemsPath uriParameters filterCriterion sortCriteria pagingCriteria responseType capabilities fetchByKeys keys ...		A snapshot of the value of the ServiceDataProvider variable at the time the fetchByOffset() call was made.
externalContext			If the fetch was externalized then the context setup on the RestAction
fetchParameters	filterCriterion size offset sortCriteria	-	The original parameters passed in via the fetchByOffset call.

This table describes configuration parameters for the fetchFirst capability.

Property	Sub-property	Value	Description
capability	-	fetchFirst	A hint telling that the request is a fetchFirst capability.
value	idAttribute itemsPath uriParameters filterCriterion sortCriteria pagingCriteria responseType capabilities fetchByKeys keys ...	-	A snapshot of the value of the ServiceDataProvider variable at the time the fetchFirst() call was made.
externalContext			If the fetch was externalized then the context setup on the RestAction
fetchParameters	filterCriterion size sortCriteria	-	-

This table describes the properties for the transformOptions parameter.

Property	Description
query filter paginate sort select	These are the properties when the ServiceDataProvider is configured for implicit fetch. When the ServiceDataProvider is configured to use an external fetch chain, the options configured on the RestAction 'requestTransformOptions' property will be made available here.

A sample endpoint, GET /customers, supports an 'ids' query parameter that can used to query customers by specific keys. For example: customers?ids=cus-101,cus-103. 

For this to work, there is currently no easy way at design time to map the keys provided by the component programmatically to the 'ids' query parameter on the URL. It might be necessary for page authors to use this property to wire up a function that will merge the transforms option.

This should be configured as follows:

1. Configuring 'mergeTransformOptions' property

   • The ServiceDataProvider variable below defines a fetchByKeys capability.

   • The 'mergeTransformOptions' property is configured to point to a page function.

   "customerSingleSDP_External": {
     "type": "vb/ServiceDataProvider",
     "defaultValue": {
       "endpoint": "demo-data-service/getCustomers",
       "keyAttributes": "id",
       "itemsPath": "result",
       "capabilities": {
         "fetchByKeys": {
           "implementation": "lookup"
         }
       }
    
       "mergeTransformOptions":
         "{{ $page.functions.processOptionsForGetCustomers }}"
     }
   }

2. Implementing the function

   • The page author uses the function to fix up the 'query' transform options that will be passed to the query transform function.

   • The page function "{{ $page.functions.processOptionsForGetCustomers}}" will look like the following:

   /**
    * fix up the query transform options.
    * When the fetchByKeys capability is set, the 'keys' provided via the fetch call
    * can be be looked up via the configuration.fetchParameters. This can be 
    * set/merged onto the 'query' transform options (1). This allows the transform 
    * function to then use the keys to build the final 'ids=' query param on the url.
    * See queryCustomersByIds method.
    *
    * Note: (1) this is needed because there is no way through DT configuration 
    * to define a mapping of 'keys' that are provided via a fetch call, to the 'ids' 
    * query parameter.
    *
    * @param configuration a map of 3 key values. The keys are
    * - fetchParameters: parameters passed to a fetch call
    * - capability: 'fetchByKeys' | 'fetchFirst' | 'fetchByOffset'
    * - context: the context of the SDP when the fetch was initiated.
    *
    * @param transformOptions a map of key values, where the keys are the names of
    *  the transform functions.
    * @returns {*}
    */
   PageModule.prototype.processOptionsForGetCustomers =
       function (configuration, transformOptions) {
     var c = configuration;
     var to = transformOptions;
     var fbkCap = !!(c && c.capability === 'fetchByKeys');
     var keysToFetch = fbkCap ? (c && c.fetchParameters && c.fetchParameters.keys) : null;
    
     if (fbkCap && keysToFetch && keysToFetch.length > 0) {
       // join keys
       var keysToFetchStr = keysToFetch.join(',');
       to = to || {};
       to.query = to.query || {};
       // ignore ids set on the query options and instead use ones passed in by
       //   fetchByKeys call
       to.query.ids = keysToFetchStr;
     }
    
     return to;
   };

3. • A query transform function is not needed in the above example because the query parameters are automatically appended to the final request URL if no additional transformation of the query options to the query parameter is needed.

   • A query transform function might be needed in more complex use cases.