Crud Lookup Client

<bk-crud-lookup-client></bk-crud-lookup-client>

resolves lookups from a given data schema onto a given source.

info

Beginning with version 6.9.0 of the CRUD Service, writable views are available.

Views are virtual collections that encapsulate the results derived from aggregation pipelines. Their primary function revolves around presenting data obtained from one collection within the contextual framework of a main collection, which is referred to as the "source". Normally, views are read-only, but since version 6.9.0 of the CRUD Service, editing a view will automatically reflect changes to the original collection.

This new feature offers a the possibility to handle lookup fields in CRUD Service collection directly in the backend. Most Back-Kit components are compatible with writable views feature and thus need not the CRUD Lookup Client for correct handling of lookup fields.

How to configure

To correctly configure the CRUD Lookup Client, properties dataSchema and basePath should be specified.

{
  "tag": "bk-crud-lookup-client",
  "properties": {
    "basePath": "/v2",
    "dataSchema": {
      "type": "object",
      "properties": {
        "riderId": {
          "type": "string",
          "format": "lookup",
          "lookupOptions": {
            "lookupDataSource": "riders",
            "lookupFields": ["name", "surname"],
            "lookupValue": "_id"
          }
        },
        "_id": {"type": "string"},
        "__STATE__": {"type": "string"}
      }
    }
  },
}

basePath is targeted path for HTTP requests, while dataSchema provides information on the structure of the data in the CRUD collection, including information on how to handle lookup fields.

Context

The CRUD Lookup Client is able to handle dynamic configurations for the lookupOptions field of data-schema entries through handlebars.

In particular, the following information are available for specifying dynamic values:

• the information of the currently logged user, via currentUser
• information about the pathname of the current URL, via pathnameParams.
  pathnameParams.params includes the result of the match between the urlMask property and the pathname of the URL, while pathnameParams.path holds the full pathname. This requires property urlMask to be defined.
• information about the query parameters of the current URL, via searchParams.
  searchParams.params includes the result of the match between the urlMask property and the query of the URL, while searchParams.path holds the full query as a string. This requires property urlMask to be defined.

This is shown in an example below.

Examples

Example: basic usage

The CRUD Lookup Client provides support to resolve lookup fields. The provided behavior is quite alike to SQL join resolution, but on a frontend client.

Let's say the data-schema looks like:

{
  "$defs": {
    "city": {
      "type": "string",
      "lookupOptions": {
        "lookupDataSource": "cities",
        "lookupValue": "_id",
        "lookupFields": ["name"]
      }
    }
  },
  "dataSchema": {
    "type": "object",
    "properties": {
      "_id": "#/$defs/_id",
      "city": "#/$defs/city",
      "addresses": {
        "type": "array",
        "items": {
          "address1": "#/$defs/address1",
          "city": "#/$defs/city"
        }
      }
    }
  }
}

hence city is a lookup from another collection called by both first and second level of an item described by the previous data schema.

The CRUD Lookup Client will perform a recursive analysis on the data schema. Starting from a given data sample

[
  {
    "_id": "1",
    "city": "city_1",
    "addresses": [
      {
        "address1": "12 Byron St.",
        "city": "city_124"
      },
      {
        "address1": "1 Batman Rd.",
        "city": "city_124"
      }
    ]
  }
]

it will fetch a projection lookupFields of lookupDataSource

city_1 -> Sydney
city_124 -> Melbourne

and emit a lookup-data event with a resolved partial data structure as payload

[
  {
    "city": "Sydney",
    "addresses": [
      {
        "city": "Melbourne"
      },
      {
        "city": "Melbourne"
      }
    ]
  }
]

such structure can be compared with the original datum, which is not modified.

Example: lookup queries with info from url

A CRUD Lookup Client configured like the following:

{
  "tag": "bk-crud-lookup-client",
  "properties": {
    "urlMask:": "/restaurants/:id",
    "dataSchema": {
      "type": "object",
      "properties": {
        "cityId": {
          "type": "string",
          "format": "lookup",
          "lookupOptions": {
            "lookupDataSource": "cities",
            "lookupValue": "_id",
            "lookupFields": ["name"],
            "lookupQueries": [
             {
                "property": "_id",
                "operator": "equal",
                "value": "{{pathnameParams.params.id}}"
              }
            ]
          }
        }
      }
    }
  }
}

assuming the current URL to be:

'/restaurants/restaurant-id-123'

then the options for field "cityId" are fetched with extra query:

{
  "_id": {"$eq": "restaurant-id-123"}
}

API

Properties & Attributes

property	attribute	type	default	description
allowLiveSearchCache	allow-live-search-cache	boolean	false	allows to cache results of live-search queries. Cache lasts as long as the component lives
dataSchema	-	ExtendedJSONSchema7Definition	-	data schema describing which field to retrieve from CRUD collection
extraLookupKeys	-	ExtendedJSONSchema7Definition	-	data schema describing extra field (not included in dataSchema) to retrieve from CRUD collection
lookupDataLimit	lookup-data-limit	number	25	limit data to require in a single lookup chunk
lookupDefaultState	-	string | string[]	["PUBLIC","DRAFT","TRASH"]	default states to append on lookup queries. Lookup queries will overwrite this setting when required by the data schema. Can be set to one or multiple of: ["PUBLIC","DRAFT","TRASH"]
maxQueryURLLength	max-query-urllength	number	1500	external lookups might require a long query parameter. According with your base path trim it to a maximum using this prop
urlMask	url-mask	UrlMask	-	url mask to apply to the current path to extract dynamic parameters

Listens to

event	description	emits	on error
display-data	validates and resolves the lookup data	success,lookup-data	-
nested-navigation-state/display	validates and resolves the lookup data upon navigating into a nested object	success,lookup-data	-
lookup-live-searching	fetches lookup options, matching their lookupFields against a string	lookup-live-found	error
search-lookups	fetches values from multiple lookups, matching their lookupFields against a string if excludeFromSearch is false in their schema	search-lookups-found	error

Emits

event	description
lookup-data	contains lookup data
lookup-live-found	notifies successful fetching of lookup options
search-lookups-found	notifies successful fetching of lookups values
success	notifies a successful lookup request
error	contains HTTP error messages when something goes wrong