An extention of Backbone Collection that allows for predefined filter(s) to be added/removed/applied/unapplied on the collection

Table of Contents

1. Installation
2. Usage
3. Tests
4. Filter Templates

• Date Range Filter Template
• Or Filter Template
• Range Filter Template
• Text Search Filter Template

5. Contributing
6. Release History
7. Travis CI Build History

Installation

| Installation Type | Command | |:-----------------:|-----------------------------------------------------------| | npm | npm install Backbone-Collection-Predefined-Filters --save | | bower | bower install Backbone-Collection-Predefined-Filters |

Usage

Initialialize a new Instance of PredefinedFilterCollection with new Backbone.PredefinedFilterCollection(models, options)

Configuarable Option Parameters

| Option Name | Expected Input Type | Default Value | Notes | |-------------|----------|----------|:---------| |options.predefinedFilters|Object| []|An object list of user defined functions with unique filter names as keys | |options.appliedPredefinedFilters|Object| []|An object list of user defined booleans with unique filter names as keys which set the state of the currently applied filters | |options.pagingOptions.modelsPerPage|Number| The number of models in the collection (i.e. Show entire collection on 1 page)|The maximum number of models each page has | |options.pagingOptions.enableLooping|Boolean| true|If set to true calling nextPage or previousPage will cycle through the pages continiously. If set to false the start and last page are the lower and upper limits. | |options.pagingOptions.startPage|Number| 1|The page number of models to render first |

Available Collection Functions

| Function Name | Expected Parameters | Notes | |----------|----------|:---------| |nextPage||Sets Models to the next available Page. If options.pagingOptions.enableLooping is set to false then if the previous page number is < 1 the first page is returned.| |previousPage||Sets Models to the next available Page. If options.pagingOptions.enableLooping is set to false then if the next available page number is > the total number of pages the last page is returned.| |goToPage|pageNumber (Number - Number of Page to navigate to.)|Sets the current models to the specified page. If the input page number is > the total number of pages the last page is returned. If the input page number < 1 the first page is returned.| |addPredefinedFilterFromTemplate|name (String - unique key value for collection filter list)templateName (String - Type of Filter to add from filter template list. See Filter Templates for more information about individual filter template types)options (Object - A configuation object passed to the filter template builder. See Filter Templates for more information about individual filter template options)applyImmediately (Boolean - Immediatelly applies the filter to the collection. Defaults to false if not specified)|| |addPredefinedFilter|name (String - unique key value for collection filter list)filterFunction (Function - A function that takes in a model as a parameter and returns a boolean)applyImmediately (Boolean/String - Immediatelly applies the filter to the collection. Defaults to false if not specified. Pass in a string value of '!' to immediately apply the NOT filter. See Using NOT filters for more information)|| |applyPredefinedFilter|name (String/Object - unique key value or Object list of values with filter name/boolean as the key/value pair)value (Boolean - If true enables filter. If false disables the filters. Defaults to toggling the current state of the filter if undefined)|Note if name is passed in as an object value is ignored and is substituted by the value in each entry in name)| |addPredefinedFilter|name (String - unique key value for collection filter list)||

Code Examples

var predefinedFilterCollection = require('backbone-collection-predefined-filters');
var models = [/*SomeArrayOfBackboneModels*/];
var options = {
    predefinedFilters: {
        'test-filter-1': /*Some Filter function 1*/,
        'test-filter-2': /*Some Filter function 2*/,
        'test-filter-3': /*Some Filter function 3*/,
        'test-filter-4': /*Some Filter function 4*/
    },
    appliedPredefinedFilters: {
        'test-filter-1': true,
        'test-filter-2': false,
        'test-filter-4': false
    },
    pagingOptions: {
        modelsPerPage: 10,
        enableLooping: true,
        startPage: 1
    }
};

/*Declare Basic Collection No options passed in*/
var exampleOneCollection = new predefinedFilterCollection(models);
/*Add filter to Collection*/
exampleOneCollection.addPredefinedFilter('test-filter-1', someTestFilterFunction1);
/*Apply filter to Collection*/
exampleOneCollection.applyPredefinedFilter('test-filter-1', true);
/*Unapply filter from Collection*/
exampleOneCollection.applyPredefinedFilter('test-filter-1', false);
/*Remove filter from Collection*/
exampleOneCollection.removePredefinedFilter('test-filter-1');

/*Declare Basic Collection with options passed in*/
var exampleTwoCollection = new predefinedFilterCollection(options);
/* Set Applied filter status to multiple filters at once*/
exampleTwoCollection.applyPredefinedFilter({
    'test-filter-1': false,
    'test-filter-2': true,
    'test-filter-4': true
});

/*Declare Basic Collection with paging options passed in*/
var exampleThreeCollection = new predefinedFilterCollection(options);
/*Get Next Page of Models*/
exampleThreeCollection.nextPage();
/*Get Previous Page of Models*/
exampleThreeCollection.previousPage();
/*Get Page 5 of Models*/
exampleThreeCollection.goToPage(5);

Tests

| Coverage Test Results | Unit Test Run | |-------------------------------------------------------------------|----------------------------------------------------------| | | | | | | | | | | | |

Filter Templates

Date Range Filter Template

Add new Date Range Filter by calling examplePredefinedFilterCollection.addPredefinedFilterFromTemplate('example-date-range-filter-name', 'DateRangeFilter', data-range-filter-options ); Below are the following options parameters.

Configuarable Option Parameters

| Option Name | Expected Input Type | Default Value | Notes | |-------------|----------|----------|:---------| |options.start.value|String| '1970/01/01 00:00:00'|A date string in moment format | |options.start.format|String| 'YYYY/MM/DD HH:mm:ss'|A String defining the format of options.start.value . | |options.start.isInUTC|Boolean| true|Flag to set whether or not the formated date string is in UTC time | |options.start.includeInRange|Boolean| true|if set to true comparedValue must be >= start date. If set to false comparedValue must be > start date. | |options.start.ignore|Boolean| false|Completely ignores the start date boundry. Use this option if you are trying to find values < or <= the end date. | |options.end.value|String| 'now'|A date string in moment format | |options.end.format|String| 'YYYY/MM/DD HH:mm:ss'|A String defining the format of options.end.value . | |options.end.isInUTC|Boolean| true|Flag to set whether or not the formated date string is in UTC time | |options.end.includeInRange|Boolean| true|if set to true comparedValue must be <= end date. If set to false comparedValue must be < end date. | |options.end.ignore|Boolean| false|Completely ignores the end date boundry. Use this option if you are trying to find values > or >= the start date. | |options.filterableModelAttributes|Array||Array of Objects containing the list of model attribute to include in the filter and the configuration for those modle attributes| |options.filterableModelAttributes[n].attribute|String| []|String containing model attribute name. Example 'someDate' is equivalent to returning model.get('someDate'). Nested values are supported. If you need to retrieve a nested value pass the string as follows 'someData.date'. Equivalent to returning model.get('someData').date. You can keep adding to the nested value layers as such: 'someData.moreData.evenMoreDate. ... .finallyMyDateAttribute' equivalently calls model.get('someData').moreData.evenMoreDate. ... .finallyMyDateAttribute .| |options.filterableModelAttributes[n].format|String| 'YYYY/MM/DD HH:mm:ss'|A String defining the format of the model attribute value. | |options.filterableModelAttributes[n].isInUTC|Boolean| true|Flag to set whether or not the formated date string is in UTC time |

Code Examples

var examplePredefinedFilterCollection = new Backbone.PredefinedFiltersCollection([/* some list of models */]);
// Base Default Options
var options = {
	start: {},
	end: {},
	filterableModelAttributes: []
};

// add basic model attribute to filter against
options.filterableModelAttributes.push({
	attribute: 'dateOfBirth'
});

// add nested model attribute to filter against
options.filterableModelAttributes.push({
	attribute: 'history.independanceDay.dateOfDeclarationOfIndependance'
});

// add model attribute to filter against that is in another foramt and is not in UTC
options.filterableModelAttributes.push({
	attribute: 'serverconfig.servertime',
	format: 'YYYYMMDDHHmmss',
	isInUTC: false
});

// set filter to only look for dates on or after a given date
options.end.ignore = true;

// set filter to only look for dates only after a given date
options.end.ignore = true;
options.start.includeInRange = false;

// set filter to only look for dates on or before a given date
options.start.ignore = true;

// set filter to only look for dates only before a given date
options.start.ignore = true;
options.end.includeInRange = false;

// set specific start date value
options.start.value = '08-10-1982 10:53:41';
options.start.format = 'MM-DD-YYYY HH:mm:ss';
options.start.isInUTC = false;

// set specific end date value
options.end.value = '09/13/2010 11:04:23 AM';
options.end.format = 'MM/DD/YYYY hh:mm:ss A';
options.end.isInUTC = true;

// Add Date Range Filter to Collection
examplePredefinedFilterCollection.addPredefinedFilterFromTemplate('example-date-range-filter-name', 'DateRangeFilter', options);

// Add Date Range Filter to Collection and apply Immediately 
examplePredefinedFilterCollection.addPredefinedFilterFromTemplate('example-date-range-filter-name', 'DateRangeFilter', options, true);

documentation coming soon!

Return to Top

Or Filter Template

Add new Range Filter by calling examplePredefinedFilterCollection.addPredefinedFilterFromTemplate('example-range-filter-name', 'Or', or-filter-options ); Below are the following options parameters.

Configuarable Option Parameters

| Option Name | Expected Input Type | Default Value | Notes | |-------------|----------|----------|:---------| |options.filters|Array| []|Array of Strings listing out the filter names. Any model that is returned from the listed filters is included. |

Code Examples

documentation for Or Filter Template still under construction

Return to Top

Range Filter Template

Add new Range Filter by calling examplePredefinedFilterCollection.addPredefinedFilterFromTemplate('example-range-filter-name', 'RangeFilter', range-filter-options ); Below are the following options parameters.

Configuarable Option Parameters

| Option Name | Expected Input Type | Default Value | Notes | |-------------|----------|----------|:---------| |options.start.value|String| 0|A numeric value | |options.start.includeInRange|Boolean| true|if set to true comparedValue must be >= start value. If set to false comparedValue must be > start value. | |options.start.ignore|Boolean| false|Completely ignores the start value boundry. Use this option if you are trying to find values < or <= the end value. | |options.end.value|String| 100|A numeric value | |options.end.includeInRange|Boolean| true|if set to true comparedValue must be <= end value. If set to false comparedValue must be < end value. | |options.end.ignore|Boolean| false|Completely ignores the end value boundry. Use this option if you are trying to find values > or >= the start value. | |options.filterableModelAttributes|Array| []|Array of Strings containing the list of model attributes to include in the filter. Example 'someDate' is equivalent to returning model.get('someDate'). Nested values are supported. If you need to retrieve a nested value pass the string as follows 'someData.value'. Equivalent to returning model.get('someData').value. You can keep adding to the nested value layers as such: 'someData.moreData.evenMoreData. ... .finallyMyAttribute' equivalently calls model.get('someData').moreData.evenMoreData. ... .finallyMyAttribute .|

Code Examples

documentation for Range Filter Template still under construction

Return to Top

Text Search Filter Template

Add new Range Filter by calling examplePredefinedFilterCollection.addPredefinedFilterFromTemplate('example-text-search-filter-name', 'TextSearch', test-search-filter-options ); Below are the following options parameters.

Configuarable Option Parameters

| Option Name | Expected Input Type | Default Value | Notes | |-------------|----------|----------|:---------| |options.inputValue|String/Number/Boolean| ''|String, Number, or Boolean value to search for. | |options.caseSensitive|Boolean| false|Flag to indicate to match results with exact case of inputValue or not. | |options.minimumInputLength|Number| 1|Minimum of charactors in inputValue necessary to invoke the filter. If the minimun length is not met the filter returns all models effectively not running the filter. Helpful for use with typeahead functionality. | |options.filterableModelAttributes|Array| []|Array of Strings containing the list of model attributes to include in the filter. Example 'someData' is equivalent to returning model.get('someData'). Nested values are supported. If you need to retrieve a nested value pass the string as follows 'someData.value'. Equivalent to returning model.get('someData').value. You can keep adding to the nested value layers as such: 'someData.moreData.evenMoreData. ... .finallyMyAttribute' equivalently calls model.get('someData').moreData.evenMoreData. ... .finallyMyAttribute .|

Code Examples

documentation for Text Search Filter Template still under construction

Return to Top

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code.

Release History

• 1.0.0 Initial release

Travis CI Build History

Return to Top