Collections
A large element of the Data Hub application involves showing lists of items, be they related records or search results, and providing a mechanism to page through them list, alter the sort order or apply filters.
The behaviour of listing and navigating these lists is common throughout the application so the collections framework aims to provide a generic method of doing this.
There are 3 main variations of collections throughout the application. The primary example can be seen when navigating to an area from the top level navigation. The diagram above shows an example of the collection page for contacts.
The primary collection pages use all elements of collections: filters, collection header/summary, a list and pagination. Each of these sections is generated by a set of common Nunjucks macros which create their content based on data passed to them.
There are other uses of collection pages also. When using the global search from the homepage a list of results is shown, this uses the same collection code but does not include filters. When viewing a company or contact record collections are also used to display related data. In the case of a company record, selecting the contacts left tab will show a list of contacts within the company context, the same goes for interactions. These pages again use the common collection macros without filters. The contents of these sub lists normally differ slightly from the top level collection lists, this is done by providing different data to the same macros.
The 2 key elements to collection pages are transformers and nunjuck macros. The idea behind transformers is to simply turn one data structure into another. Within collections a transformer transforms the data that represents an entity, such as a contact, into a common format the Nunjucks macros can understand and render in the card format that represents list items.
The transformer reads the result from the api and uses it to build properties such as the total count, then calls upon a function to generate the parameters needed for pagination then finally is called with a list of 1 or more 'item' transformers that it calls, to which it calls in order for each result item.
The piece that is unique to each entity is the 'item' transformer, this describes how to turn the properties that make up an entity into the format that the nunjucks macros require.
Because you can use multiple transformers, and dictate the order they are called in, it is possible to create one transformer for an entity that transforms common elements to it and then have a follow up transformer add or modify the results of the first. In the case of contacts a single common transformer is created and then when used within the context of a company a 2nd transformer strips out the company meta item, as it is not required.
http://datahub.com/contacts?term=Fred&sort_order=name:asc
# Response
{
count: 100,
page: 1,
items: [{
id: '1234',
name: 'Fred Smith',
updated: 20170102TZ19:00:32:0000,
company: {
id: '123123',
name: 'Acme Corp'
},
telephone: '0123 321 12312',
email: 'fred@acme.org'
}...]
}
# Transformed item
{
id: '1234',
type: 'contact',
name: 'Fred Smith',
subTitle: {
value: 20170102TZ19:00:32:0000,
type: 'dateTime',
label: 'Last updated',
},
meta: [
{ label: 'Company', value: { id: '123123', name: 'Acme Corp' }}
{ label: 'Telephone', value: '0123 321 12312' },
{ label: 'Email', value: 'fred@acme.org', }
]
}
If you look at a result on the page you can see all results have a title area, an optional sub-title and then fields to describe that entity, which are called meta. A meta item needs a label and value, the type is optional but can be used to describe some items that require special formatting or handling. The current supported types are:
- date: Transforms a native date value into a human readable one, e.h. 20 Jan 1983
- dateMonthYear: Transforms a native date into a format that just shows month and year, e.g. January 2017
- dateTime: Transforms a native data time into a human readable format that includes the time, e.g. 20 Jan 1989 09:00am
- fromNow: Transforms a native date format into a human readable format relative to the current date and time, e.g. Tomorrow, Yesterday
- badge: Badges are displayed on the right side of a record with additional styling to make them stand out.
A further attribute url can be specified, and another called urlLabel. If url alone is passed then the value to be shown will be wrapped in a link. If both are passed then the original value is displayed followed by a link using the url and label.
A value can either be a string, a datetime value from the api or an object that in turn has at the very least a name property.
To fully understand what needs to go into a meta item take a look at 'meta-item.njk', this is the nunjucks macro used to render a meta item and you can see how decides how to render the item.
A note about transformApiResponseToSearchCollection and transformApiResponseToCollection. These two transformers are similar, in fact the search transformers uses the collection transformer and adds to it. It introduces a few features unique to search and filtering, such as highlighting a term and handling the idea of aggregations for filters, though this is not currently being used.
Use data has been transformed into a common format a combination of Nunjucks layouts and macros have been developed to
