ngCrossfilter uses Crossfilter for a significant improvement in performance.
Firstly you need to initialise Crossfilter with your collection of items.
ngCrossfilter's constructor accepts four parameters – with only the first being mandatory. With the second parameter you can change the primary key – which will otherwise default to the first property in the first model; the third parameter allows you to change the filtering strategy – either
transient, whereas the fourth parameter allows you to specify which properties to create dimensions with.
For timing information and other useful information for development, you can enable debug mode.
Once you've configured your Crossfilter collection, you can begin filtering and sorting. From within your view you should reference your collection – in our case,
After you've applied all of your filters, you need to add the
ngCrossfilter filter to your
You should place the
crossfilter filter before any other filters so that a standard array is piped to the subsequent filters.
Filter by word:
Third argument allows the specifying of a custom filtering function – see custom functions.
Unfilter by word:
By default the filtering strategy is
persistent which means that all filters are persistent until they are re-applied, or removed. If you'd like to change to the
transient behaviour where the previous filter is cleared, you can pass
ngCrossfilter's constructor as the third argument.
By specifying a custom function on the third argument of the
filterBy method you can implement your own sorting logic.
Which can then be utilised by passing it as the third argument in your view.
Sort by word:
Second argument allows you to choose whether the sorting is by ascending – by not applying a value, the ascending will be inverted each time the same property is sorted on.
Unsort by word:
Second argument prevents the reverting of the sort order to ascending.
With filters it's useful to compute the
length of any given property and value pair – with
ngCrossfilter we can do this with the
However, there is one proviso and that is the
countBy method may not behave as you expect it to as it disregards the dimension you're counting on – see Crossfilter's Map-Reduce documentation.
In a nutshell, if you're filtering on the
name property, and you're also counting by the
name property, the
name filter will be disregarded – instead you need to count on a dimension that you're not using in the filtering process – unless the default behaviour is useful – and in most cases it actually makes sense – see the Word Count filter in the example. You can implement this by adding a custom dimension with
addDimension, or by counting on the primary key – assuming it's not being used in the filtering process.
Sometimes it is preferable to subscribe to the update of the Crossfilter, and to apply any modifications of your data at that point rather than relying on Angular's dirty-checking.
In these cases you can listen to the
As there are common filtering techniques that Crossfilter doesn't implement,
ngCrossfilter comes with a fine selection of bundled filters for common tasks.
With the fuzzy filter you can filter with incomplete expressions.
You will notice that the
fuzzy method is invoking the method immediately – this allows you to pass valid regular expression flags for insensitivity, et cetera...
By default no flags will be defined for the regular expression matching.
Regular Expression Filter
With the regular expression filtering you can specify an expression to filter on.
You can pass either an expression or an actual
RegExp object to the filter.
inArray filter you can check an array against an array – using the
every array methods – please check the browser support before using it.
By default the
inArray filter uses the
every method, which means in the above example only entries where
twinCities has both Beijing and Tokyo will be returned – you can use
some instead by passing it into
inArray filter method.
Simple filter using the bitwise
& operator against the collection.
You can invert the filtering by passing an exclamation mark as the first argument to the
For the entire list of features for
ngCrossfilter it is advised to refer to the unit tests – as these have full coverage of all
ngCrossfilter methods and their usages.
addDimension: Add a custom dimension;
deleteDimension: Delete a dimension;
getCollection: Collection as a standard array;
getModels: Alias for
getFirst: First model in the collection;
getLast: Last model in the collection;
getModel: nth model in the collection;
countBy: Count values – see counting;
groupBy: Group by any given dimension;
addModel: Add a model to the collection;
addModels: Add models to the collection;
deleteModel: Delete a model from the collection;
deleteModels: Delete models from the collection;
getCount: Get a count of the collection;
debugMode: Enable/disable debugging mode;
As with all of my projects, you're more than welcome to contribute. Please include a unit test for your additions, and if the Travis build passes then it will be merged into master.