filtersbuilder v0.2.1
Filters Controller & Builder
Info
Filters is both a controller for filters and a builder for filters. Depending on the template you send in along with the filters data you set. To use filters you will need to initialize the component with your options and filters you want constructed and then listen for its event trigger, the component handles dates, and other inputs and sends you the value for the triggered filter for you to do with as you please.
Constructor
Assign instance variables to the constructor.
Arguments
els- the page element that the filters should be rendered onoptions- an object with options such as the filters setup you want.
##Options
template- path to the desired template you want to use (REQUIRED)filters- filter information to populate your filters according to your template Default:[]waitTimer- how long should event delayallowHighlighting-Booleanpass in true if you want to have filters highlight items that are searched for. Default:falsetrackFilterHistory-Booleanpass true if you want filters history to be saved. Default:falsepreventEmptyFilters-Booleanpass true if you do not want the filters to trigger if the box is empty. Default:falsedateFormat- String passed to format the date to whatever you want (uses moment) Default:MM/DD/YYYY$tableEls- the element that the filters will be "Filtering" Default:''
##Events
comp_ui_filtering.dropDown - fired whenever a dropdown is changed it will send the event and an object with the data value of the dropdown
comp_ui_filtering.input - Fired when a radio button is chanded, and when a user hits enter or clicks off a regular input box
comp_ui_filtering.savedHistory - Fired whenever a save happens if trackFilterHistory is true
comp_ui_filtering.datePicker - fired when the datepicker is successfully entered
comp_ui_filtering.resetFilters - fired when the reset filters link/button is clicked
comp_ui_filtering.checkbox - triggers with checkbox manipulation
apply.daterangepicker - a default event fired by daterangepicker whenever someone applies a new date
Classes
Classes with js- in the front are not style based classes and are used by the javascript exclusively.
All bootstrap elements are also supported such as form-control etc. (if bootstrap is present)
###js-filterdropdown Should be attached to the drop down so it can properly assign data and trigger the proper events
<select data-type="reason" class="js-filterDropdown">
<option value="reason1">No Sale</option>
<option value="reason2">Return</option>
</select>Usage
Triggers the comp_ui_filtering.dropDown event when the element is changed this can also be used with regular inputs not just dropdowns
$el.on('comp_ui_filtering.input', $.proxy(this.handleInputs, this)).on('comp_ui_filtering.dropDown', $.proxy(this.handleInputs, this));
function handleInputs(e, a) {
var filtersData = {};
if (a.value !== '' && a.value !== 'all') {
filtersData[a.type] = a.value;
} else {
delete filtersData[a.type];
}
return filtersData;
};###js-filterinput
Attach to inputs such as text, checkboxes, number, radio inputs.
<input class="js-filterInput" type="text" value="" data-type="searchterm" placeholder="All">Usage
Triggers the comp_ui_filtering.input event when a user clicks off the input, or hits the enter key.
See above for usage notes...
###js-datepicker Should be attached to a input you would like to use as a date picker element this will attach the bootstrap date picker to this element and allow the proper events to trigger on it.
<input type="text" class="form-control js-datepicker">Usage
Triggers the comp_ui_filtering.datePicker event when the user hits the enter key, or clicks on a certain date through the Calendar.
Dates return as an object:
{
startdate: 'XX/XX/XXXX',
enddate: 'XX/XX/XXXX'
}$el.on('comp_ui_filtering.datePicker', $.proxy(this.handleDates, this));
function handleDates(e, dates) {
var filtersData = {};
for (var o in dates) {
if (dates.hasOwnProperty(o) && dates[o]) {
filtersData[o] = dates[o];
} else {
delete filtersData[o];
}
}
return filtersData;
};###js-daterange
Attach this class to the wrapper div of your inputs if you plan to use the date range picker in order to correctly plan out date range requires the use of datepickerFrom and datepickerTo in order to properly place the correct values.
<div class="input-group input-daterange js-daterange">
<input type="text" class="form-control js-datepicker" id="datepickerFrom">
<span class="input-group-addon">to</span>
<input type="text" class="form-control js-datepicker" id="datepickerTo">
</div>Usage
Used to keep track of date ranges so that users cannot mis match ranges
still triggers comp_ui_filtering.datePicker once these calculations finish
###js-datepicker-icon Attach this if you have icons on your datepicker inputs and would like the icon to also trigger a date picker calendar to appear on your input.
<span class="input-group-addon js-datepicker-icon"><span class="glyphicon glyphicon-calendar"></span></span>Use it properly with the date picker element would look like:
<div class="input-group">
<input type="text" class="form-control js-datepicker">
<span class="input-group-addon js-datepicker-icon"><span class="glyphicon glyphicon-calendar"></span></span>
</div>###js-resetfilters Attach this on the button or link you would like to use to trigger a filter reset
<a class="js-resetFilters">Reset Filters</a>Usage
Triggers the comp_ui_filtering.resetFilters event but does not pass along any data with the event
$el.on('comp_ui_filtering.resetFilters', $.proxy(this.resetFilters, this));
function resetFilters() {
this.filtersData = {};
return this.filtersData;
};###js-watchhighlight
Attach this class on to elements you would like to be highlighted when the user uses a search input, if allowHighlighting is set to true then items with this class will trigger a highlight within your table or whatever you are using for highlights.
######Important
This adds a class called comp--mark to items that are found by the highlighting function so make sure you setup in your css for this class or you will not see your highlights.
<span class="js-watchhighlight"></span>Usage
In order to actually trigger highlight you will need to call the function after your table, or whatever else you are filtering re-renders. Sending the function the term you want highlighted.
function render(opts) {
Filters.highlightItems(opts.searchterm);
}###js-savehistory Attach this class to elements you would like Filtering to save in history (the value not the element).
<input type="text" class="form-control js-datepicker js-savehistory">Usage
In order to access the filters history simply make a request to the history object inside filters
yourview.filters.historyData Types
Data types play a pretty important role in getting you the right information for your use.
###type type is the basic data type of the bunch it tells you what the type of input your data is coming from, useful if you want a filter to call a sql service when a user hits enter. (the return will give you back the type and the value of the input in an object with the trigger)
####Usage
<input class="form-control js-filterinput js-savehistory" type="text" value="Example" data-type="searchterm" placeholder="All">This would return the following object to your listener:
{value: 'Example', type: 'searchterm'}###historytype This data type is associated with history and required if you want nicely organized history data (it IS optional however if not used you will just get a clump of history data back in an object)
####Usage
<input class="form-control js-filterinput js-savehistory" type="text" value="Example" data-type="searchterm" data-historytype="search" placeholder="All">historyType is NOT returned to your listener on event triggering, it is simply used by Filters in order to better organize your history data. (If enabled of couse)
How-To
To use Filters simply call the constructor and tell it what you want to do.
var Filters = require('filtersbuilder');
var tableFilters = new Filters($el, {
template: 'path/to/your/filtering/template',
trackFilterHistory: true,
autoSearchWait: 500,
$tableEls: $yourTable // This should be whatever the elments the filters will be watching/editing
filters: [] //You can use this field as a location to keep data you want to place on your filters. (Or not its up to you) it is NOT manipulated by the js simply template only.
});
tableFilters.render();Example Template & Options
The following example allows for automatic filters building and control by the component. Use the following option setup to use the template at its best:
filters: [{
type: 'text', //What type is the input going to be? (accepts any type if you want to use a dropdown just put dropdown)
labelFor: 'input-example', //Do you want the label to have a for attribute?
labelText: 'I am an Example!', //You can place icon html here as well?
useToolTip: true, // Should we assign tool tip icons and boxes to labels?
toolTipText: '',
placeholder: 'All', //Do you want a placeholder, leave blank if not
columnSize: 4, //Change to the appropriate column size for how many inputs you'll have
datatype: 'example-input' //what do you want the data-type attribute to be?
},
{
type: 'dropdown',
labelFor: 'dropdown-example',
labelText: 'I am a dropdown Example!',
dropDownData: [
{value: 'all', option: 'All'}, //data object for an <option> tag value will fill the value attribute
{value: 'test', option: 'Test'}, //option will be whats actually placed between the <option> tags
{value: 'test2', option: 'Test2'}
],
useToolTip: false, // Should we assign tool tip icons and boxes to labels?
toolTipText: '',
columnSize: 4,
datatype: 'example-dropdown',
allowHighlighting: true,
trackFilterHistory: true
}]You can use the following template as an example of the possibilities
<form class="row">
{{#each filters}}
<div class="col-md-{{this.columnSize}} form-group">
<label for="{{this.labelFor}}">{{this.labelText}}</label> {{#if this.useToolTip}}<i class="glyphicon glyphicon-exclamation-sign" title="{{this.toolTipText}}"></i>{{/if}}
{{#equal this.type "text"}}
<input class="form-control js-filterInput" type="{{this.type}}" value="" data-type="{{this.datatype}}" placeholder="{{this.placeholder}}">
{{else}}
<select data-type="{{this.datatype}}" class="form-control js-filterDropdown">
{{#each this.dropDownData}}
<option value="{{this.value}}">{{this.option}}</option>
{{/each}}
</select>
{{/equal}}
</div>
{{/each}}
{{#if useDatePicker}}
{{#if useDateRange}}
<div class="col-md-{{datePickerColumn}} form-group">
<label class="control-label" for="datepicker-to">{{datePickerLabel}}</label>
<div class="input-group input-daterange" id="inputDateRange">
<input type="text" class="form-control js-datepicker" id="datepickerFrom">
<span class="input-group-addon">to</span>
<input type="text" class="form-control js-datepicker" id="datepickerTo">
</div>
</div>
{{else}}
<div class="col-md-{{datePickerColumn}} form-group">
<label class="control-label" for="datepicker-single">{{datePickerLabel}}</label>
<div class="input-date input-group" id="inputDateSingle">
<input type="text" class="form-control js-datepicker" id="datepickerSingle">
<span class="input-group-addon js-datepicker-icon"><span class="glyphicon glyphicon-calendar"></span></span>
</div>
</div>
{{/if}}
{{/if}}
{{#if attachResetBtn}}
<div class="col-md-1 filters--reset">
<a class="js-resetFilters font-xs">{{resetBtnTxt}}</a>
</div>
{{/if}}
</form>