angular-ui-query-builder

MongoDB format query-builder UI component for Angular.

This component comes in two parts:

1. An interactive UI element to edit a MongoDB query
2. Functionality to extend basic HTML tables with additional features (column sorting, filtering etc.) by changing the MongoDB query

Demo.

Installation

1. Grab the NPM

npm install --save @momsfriendlydevco/angular-ui-query-builder

2. Install the required script + CSS somewhere in your build chain or include it in a HTML header:

<script src="/libs/angular-ui-query-builder/dist/angular-ui-query-builder.min.js"/>
<link href="/libs/angular-ui-query-builder/dist/angular-ui-query-builder.min.css" rel="stylesheet" type="text/css"/>

3. Include the router in your main angular.module() call:

var app = angular.module('app', ['angular-ui-query-builder'])

4. Use somewhere in your template:

<ui-query-builder query="$ctrl.myQuery" spec="$ctrl.mySpec"></ui-query-builder>

A demo is also available. To use this follow the instructions in the demo directory.

API

ui-query-builder (directive)

Simply create a query object and link it up to the directive.

In a controller:

$scope.mySpec = {
	_id: {type: 'objectId'},
	name: {type: 'string'},
	email: {type: 'string'},
	status: {type: 'string', enum: ['pending', 'active', 'deleted']},
};

$scope.myQuery = {
	status: 'active', // Assumes you have a status field
	limit: 10,
	skip: 0,
};

In a HTML template:

<ui-query-builder query="$ctrl.myQuery" spec="$ctrl.mySpec"></ui-query-builder>

... or see the Demo.

The ui-query-builder directive takes the following parameters:

| Parameter | Type | Description | |-----------|--------|---------------------------------------------------------------------------------------| | query | Object | The current query, this object will be mutated into / from a MongoDB compatible query | | spec | Object | A base specification of field types to use when providing the UI |

qb-table & qb-* (directives)

If using either the full JS release (angular-ui-query-builder.js) or the table add-on (angular-ui-query-builder-tables.js) additional functionality is provided for Tables including column setup, pagination and other functionality.

To use:

1. Add the qb-table directive to the table header with a pointer to the query object to mutate
2. (Optional) Add the qb-col directive to any table column to extend, include attributes like sortable to add that functionality
3. (Optional) Add the qb-pagination directive into the table footer to add pagination functionality

For example:

<table class="table table-bordered table-striped table-hover" qb-table="query">
	<thead>
		<tr>
			<th qb-col="name" sortable>Name</th>
			<th qb-col="username" sortable>Username</th>
			<th qb-col="email" sortable>Email</th>
		</tr>
	</thead>
	<tbody>
		<tr ng-repeat="row in data track by row.id">
			<td>{{row.name}}</td>
			<td>{{row.username}}</td>
			<td>{{row.email}}</td>
		</tr>
	</tbody>
	<tfoot>
		<tr>
			<td colspan="3">
				<qb-pagination></qb-pagination>
			</td>
		</tr>
	</tfoot>
</table>

For a more complex example see the demo.

qb-table (directive)

Use on a <table/> element to designate that it should be managed by this module.

Valid attributes are:

| Attribute | Type | Description | |----------------|-----------|-------------------------------------------------------------------------------------------| | qb-table | Object | The main query object to mutate when the table is interacted with | | sticky-thead | boolean | Indicates that the <thead/> portion of the table should remain on screen when scrolling | | sticky-tfoot | boolean | Indicates that the <tfoot/> portion of the table should remain on screen when scrolling |

qb-col (directive)

Use on <td> / <th> element within a <thead> to provide column level interaction.

<table class="table table-bordered table-striped table-hover" qb-table="query">
	<thead>
		<tr>
			<th qb-col="name" sortable>Name</th>
			<th qb-col="username" sortable>Username</th>
			<th qb-col="email" sortable>Email</th>
		</tr>
	</thead>
	...
</table>

Valid attributes are:

| Attribute | Type | Description | |----------------|-----------------------|-------------------------------------------------------------------------------------------| | qb-col | string | The database field to link against in dotted notation | | sortable | boolean or string | Indicates that this column can be sorted, if blank or boolean true this simply uses the qb-col value as the field to sort by, if its a string it uses that field instead |

qb-cell (directive)

Use on <td> / <th> element within a <thead> / <thead> to provide column level interaction.

If this element is within <thead> it adds table level meta functionality (such as controlling which rows are selected if selector is truthy). If its within a <tbody> it adds per-row functionality.

<table class="table table-bordered table-striped table-hover" qb-table="query">
	<thead>
		...
	</thead>
	<tbody>
		<tr ng-repeat="row in data track by row.id">
			<td qb-cell selector="row.selected"></td>
			<td>{{row.name}}</td>
		</tr>
	</tbody>
</table>

Valid attributes are:

| Attribute | Type | Description | |----------------|------------|-------------------------------------------------------------------------------------------| | selector | Object | Indicates the field to bind against + mutate when selection is toggled. This usually resembles something like row.selected | | onSelect | function | Function called with ({value}) when the selection value changes |

qb-pagination

An element, usually found in the <tfoot> section of a table which provides general pagination functionality.

<table class="table table-bordered table-striped table-hover" qb-table="query">
	<thead>
		...
	</thead>
	<tbody>
		...
	</tbody>
	<tfoot>
		<tr>
			<td colspan="10">
				<qb-pagination></qb-pagination>
			</td>
		</tr>
	</tfoot>
</table>

This directive has no attributes.

NOTE: This is an optionally transcludable element. Any content within its tags will be inserted in the center of the pagination controls.

qbTableSettings (Provider)

Simple shared resource that can be used to set qbTable settings globally in an App.

// Add a custom question into the exporter
app.config(qbTableSettingsProvider => {
	qbTableSettingsProvider.export.questions.push({
		id: 'docTitle',
		type: 'text',
		title: 'Document title',
		default: 'Exported Data',
		help: 'What your document will be called when exported',
	});
});

Valid properties are:

| Attribute | Type | Description | |--------------------|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | icons | object | Generic icon choices in your application. See the individual contents of this object for more details | | export | object | Options relevent to the qbExport directive | | export.formats | array | Collection of suported output formats. Each entity should have an id + title property | | export.questions | array | Additional questions to ask when exporting. Each question will be apptended onto the query posted to the server. Questions should have id, type and title properties with optional default and help fields |

NOTE: Since this is an Angular Provider this service is exposed as qbTableSettingsProvider during the config stage and qbTableSettings if you require it in a controller / component.

TODO

ui-query-builder

• [x] Indicator for 'No query - show all records'
• [x] Basic field filtering
• [ ] CSS tidyup
• [ ] Compound queries - $or / $and
• [x] Automatically moving from a static string ($eq condition) to a multiple choice enum ($in) when a comma is used in a string
• [ ] Convert string ENUMs to a $in type automatically
• [x] Number filtering - above, below, between
• [x] Date support - date selector, before, after
• [x] Nicer syntax support for $regexp
• [ ] Support for $length
• [ ] Nicer multi level path support

qb-tables

• [x] Pagination
• [x] Sticky headers on scroll
• [x] Query-Builder integration
• [x] Sorting per-column
• [x] Export to excel functionality
• [x] Row selection
• [x] Simple searching
• [ ] Freezing columns (low priority)
• [ ] Responsive layout compatible for mobiles (low priority)
• [ ] Animated on load or transitions (low priority)
• [ ] Column reorder capability (low priority)
• [ ] Sort profiles (e.g. 'show recent', 'only my items')