DataTable

module:api/utils/common~ DataTable

DataTable is a helper class for data tables in the UI which have bServerSide: true. It provides abstraction for server side pagination, searching and column based sorting. The class relies on MongoDB's aggregation for all operations. This doesn't include making db calls though. Since there can be many different execution scenarios, db left to the users of the class.

There are two main methods of the class:

  1. getAggregationPipeline: Creates a pipeline which can be executed by MongoDB. The pipeline can be customized, please see its description.

  2. getProcessedResult: Processes the aggregation result. Returns an object, which is ready to be served as a response directly.

Constructor

new DataTable(queryString, options)

Description:

  • Constructor

Source:
Parameters:
Name Type Description
queryString object

This object should contain the datatable arguments like iDisplayStart, iDisplayEnd, etc. These are added to request by DataTables automatically. If you have a different use-case, please make sure that the object has necessary fields.

Properties
Name Type Description
outputFormat 'full' | 'rows'

The default output of getProcessedResult is a DataTable compatible object ("full"). However, some consumers of the API may require simple, array-like results too ("rows"). In order to allow consumers to specify expected output, the field can be used.
options object

Wraps options

Properties
Name Type Description
columnOrder Array.<string>

If there are sortable columns in the table, then you need to specify a column list in order to make it work (e.g. ["name", "status"]).
defaultSorting object

When there is no sorting provided in query string, sorting falls back to this object, if you provide any (e.g. {"name": "asc"}).
searchableFields Array.<string>

Specify searchable fields of a record/item (e.g. ["name", "description"]).
searchStrategy 'regex' | 'hard'

Specify searching method. If "regex", then a regex search is performed on searchableFields. Other values will be considered as hard match.
outputProjection object

Adds a $project stage to the output rows using the object passed.
defaultOutputFormat 'full' | 'rows'

This is the default value for queryString.outputFormat.
uniqueKey string

A generic-purpose unique key for records. Default is _id, as it is the default identifier of MongoDB docs. Please make sure that this key is in the output of initial pipeline.
disableUniqueSorting boolean

When sorting is done, the uniqueKey is automatically injected to the sorting expression, in order to mitigate possible duplicate records in pages. This is a protection for cases when the sorting is done based on non-unique fields. Injection is enabled by default. If you want to disable this feature, pass true.

Methods

_getSearchField() → {object|string}

Description:

  • Returns the search field for. Only for internal use.

Source:
Returns:

Regex object or search term itself

Type
object | string

getAggregationPipeline(options) → {object}

Description:

  • Creates an aggregation pipeline based on the query string and additional stages/facets if provided any. Data flow between stages are not checked, so please do check manually.

Source:
Parameters:
Name Type Description
options object

Wraps options

Properties
Name Type Description
initialPipeline Array.<object>

If you need to select a subset, to add new fields or anything else involving aggregation stages, you can pass an array of stages using options.initialPipeline. Initial pipeline is basically used for counting the total number of documents without pagination and search.

of output rows = total number of docs.
filteredPipeline Array.<object>

Filtered pipeline will contain the remaining rows tested against a search query (if any). That is, this pipeline will get only the filtered docs as its input. If there is no query, then this will be another stage after initialPipeline. Paging and sorting are added after filteredPipeline.

of output rows = filtered number of docs.
customFacets object

You can add facets to your results using option.customFacets. Custom facets will use initial pipeline's output as its input. If the documents you're looking for are included by initial pipeline's output, you can use this to avoid extra db calls. You can obtain outputs of your custom facets via getProcessedResult. Please note that custom facets will only be available when the output format is "full".
Returns:

Pipeline object

Type
object

getProcessedResult(queryResult, processFn) → {object|Array.<string>}

Description:

  • Processes the aggregation result and returns a ready-to-use response.

Source:
Parameters:
Name Type Description
queryResult object

Aggregation result returned by the MongoDB.
processFn function

A callback function that has a single argument 'rows'. As the name implies, it is an array of returned rows. The function can be used as a final stage to do modifications to fetched items before completing the response.
Returns:

Returns the final response

Type
object | Array.<string>