Sort Transform

The sort request transform allows authors to transform a sort criteria into a sort query param that is then appended to the configuration.url.

The sort criteria provided via the options parameter is an array that has one or more criteria with properties { attribute, direction }. See JET SortCriterion for details.

Examples of Sort criteria

This example shows a single sort criterion that transforms to "orderBy=firstName:asc"

[
  {
    "attribute": "firstName",
    "direction": "ascending"
  }
]

This example shows a compound sort criteria that transforms to "orderBy=firstName:asc,age:desc"

[
  {
    "attribute": "firstName",
    "direction": "ascending"
  },
  {
    "attribute": "age",
    "direction": "descending"
  }
]

For 3rd party services the author can provide a custom sort transforms implementation.

Signature

The sort transform function can be declared like this:

const sort = function(configuration, options, transformsContext) {

  var c = configuration;
  // use the sort criteria provided on 'options' parameter to generate the query param
  // update c.url as needed

  return c;
}

This function has the following parameters:

configuration an object with the following properties:
- Refer to the signature in Request Transformation Functions for details on the various properties.
options the sort criteria to transform.
transformsContext is an object that is set by the author (ServiceDataProvider, RestHelper, Call Rest action) to then be passed as is to all transforms for the current fetch cycle.

The function returns the updated configuration object.

Usage

The examples below illustrate the arguments passed to the sort transform, as well as the effect its code has on the fetch performed by the RestHelper.

The example below uses a service fixitfast that has a GET endpoint to retrieve the list of customers.

Example 1-14 ServiceDataProvider variable

Assume that the following variable of type vb/ServiceDataProvider is defined in a page that refers to the above GET /customers endpoint. The SDP variable includes a default sort criteria set via the property sortCriteria.

{
  "variables": {
    "customersSDP": {
      "type": "vb/ServiceDataProvider",
      "defaultValue": {
        "endpoint": "fixitfast-service/getCustomers",
        "keyAttributes": "id",
        "itemsPath": "result",
        "responseType": {
          "result": "customerResponse[]"
        },
        "sortCriteria": [
          {
            "attribute": "lastName",
            "direction": "ascending"
          }
        ]
      }
    }
  }
}

When a caller such as a component bound to the above SDP initiates a fetch call, it can also provide additional sort criteria. These are combined with the configured cort criteria above and the merged sort criteria is provided to the sort transforms function.

The

sort

request transforms function uses the criteria passed in via the

options

parameter to build a query param on the configuration url. The

sort

transform is implemented in the service transforms as follows:

define([], function () {
  class Request {

    static sort(configuration, options, transformsContext) {
      const c = configuration;
      const sortCriteria = options;

      // process options to build the query param for the sort
      if (sortCriteria && Array.isArray(sortCriteria) && sortCriteria.length > 0) {
        sortCriteria.forEach((sc) => {
          const dir = sc.direction === 'descending' ? 'desc' : 'asc';
          const attr = sc.attribute || "";
          if (attr) {

            // build sort criteria and append to url
          }
        })
      }

      // update the c.url
      return c;
    }
  }

  class Response {};
  class Metadata {};

  // Note: as an example, the Request object is expanded to include just the sort property
  return {
    metadata: Metadata,
    request: { sort: Request.sort },
    response: Response
  };
});

Example 1-15 REST Action

Assume that the following variable of type vb/ServiceDataProvider is defined in a page that delegates the fetch to an action chain (set via 'fetchChainId' property).

The chain "fetchCustomersChain" in its fetchCustomers RestAction configuration sets a default sort criteria via the property requestTransformOptions.sort.

When a fetch is initiated by a component bound to the SDP, the sort criteria is automatically passed in to the sort transform function associated to the service, via the options parameter. Refer to the Call Rest action docs for details.

{
  "variables": {
    "customersSDP": {
      "type": "vb/ServiceDataProvider",
      "defaultValue": {
        "fetchChainId": "fetchCustomersChain",
        "keyAttributes": "id",
        "itemsPath": "result"
      }
    }
  },
  "chains": {
    "fetchCustomersChain": {
      "variables": {
        "configuration": {
          "type": {
            "hookHandler": "vb/RestHookHandler"
          },
          "description": "the configuration for the rest action",
          "input": "fromCaller",
          "required": true
        }
      },
      "root": "fetchCustomers",
      "actions": {
        "fetchCustomers": {
          "module": "vb/action/builtin/restAction",
          "parameters": {
            "endpoint": "fixitfast-service/getCustomers",
            "hookHandler": "{{ $variables.configuration.hookHandler }}",
            "responseType": "customersComputedResponse",
            "requestTransformOptions": {
              "sort": [
                {
                  "attribute": "lastName",
                  "direction": "desc"
                }
              ]
            }
          },
          "outcomes": {
            "success": "returnCustomersResponse",
            "failure": "returnFailureResponse"
          }
        }
      }
    }
  }
}