@momsfriendlydevco/angular-ui-query-builder

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

1. 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"/>

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

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

1. 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

• Basic field filtering
• CSS tidyup
• Compound queries - $or / $and
• 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
• Number filtering - above, below, between
• Date support - date selector, before, after
• Nicer syntax support for $regexp
• Support for $length
• Nicer multi level path support

qb-tables

• Pagination
• Sticky headers on scroll
• Query-Builder integration
• Sorting per-column
• Export to excel functionality
• Row selection
• 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')