JarCastingAngular Advanced Searchbox
A directive for AngularJS providing a advanced visual search box.
DEMO
Usage
Include with bower
bower install angular-advanced-searchbox
The bower package contains files in the dist/directory with the following names:
- angular-advanced-searchbox.js
- angular-advanced-searchbox.min.js
- angular-advanced-searchbox-tpls.js
- angular-advanced-searchbox-tpls.min.js
Files with the min suffix are minified versions to be used in production. The files with -tpls in their name have the directive template bundled. If you don't need the default template use the angular-paginate-anything.min.js file and provide your own template with the templateUrl attribute.
Load the javascript and css and declare your Angular dependency
<!-- dependency includes -->
<script src="bower_components/jquery/dist/jquery.min.js"></script>
<script src="bower_components/bootstrap/dist/js/bootstrap.min.js"></script>
<script src="bower_components/angular/angular.min.js"></script>
<script src="bower_components/angular-animate/angular-animate.min.js"></script>
<link rel="stylesheet" href="bower_components/bootstrap/dist/css/bootstrap.min.css">
<!-- optional for auto complete / suggested value feature -->
<script src="bower_components/angular-bootstrap/ui-bootstrap-tpls.min.js"></script>
<!-- angular advanced searchbox includes -->
<link rel="stylesheet" href="bower_components/angular-advanced-searchbox/dist/angular-advanced-searchbox.min.css">
<script src="bower_components/angular-advanced-searchbox/dist/angular-advanced-searchbox-tpls.min.js"></script>
angular.module('myModule', ['angular-advanced-searchbox']);
Define the available search parameters in your controller:
$scope.availableSearchParams = [
{ key: "name", name: "Name", placeholder: "Name..." },
{ key: "city", name: "City", placeholder: "City..." },
{ key: "country", name: "Country", placeholder: "Country..." },
{ key: "emailAddress", name: "E-Mail", placeholder: "E-Mail...", allowMultiple: true },
{ key: "job", name: "Job", placeholder: "Job..." }
];
Then in your view
<nit-advanced-searchbox
ng-model="searchParams"
parameters="availableSearchParams"
placeholder="Search...">
</nit-advanced-searchbox>
The angular-advanced-searchbox directive uses an external template stored in angular-advanced-searchbox.html. Host it in a place accessible to your page and set the template-url attribute. Note that the url param can be a scope variable as well as a hard-coded string.
Benefits
- Handles free text search and/or parameterized searches
- Provides suggestions on available search parameters
- Easy to use with mouse or keyboard
- Model could easily be used as
paramsfor Angular's$httpAPI - Twitter Bootstrap compatible markup
- Works perfectly together with angular-paginate-anything (use
ng-modelasurl-params)
Directive Attributes
| Name | Description |
|---|---|
| ng-model | Search parameters as object that could be used as params with Angular's $http API. |
| parameters | List of available parameters to search for. |
| parametersDisplayLimit | Maximum number of suggested parameters to display. Default is 8. |
| parametersLabel | Text for the suggested parameters label, e.g. "Parameter Suggestions". |
| placeholder | Specifies a short hint in the search box |
| searchThrottleTime | Specifies the time in milliseconds to wait for changes in the ui until the ng-model is updated. Default is 1000ms. |
Events
The directive emits events as search parameters added (advanced-searchbox:addedSearchParam), removed (advanced-searchbox:removedSearchParam and advanced-searchbox:removedAllSearchParam), enters the edit mode (advanced-searchbox:enteredEditMode), leaves the edit mode (advanced-searchbox:leavedEditMode) or the search model was updated (advanced-searchbox:modelUpdated). To catch these events do the following:
$scope.$on('advanced-searchbox:addedSearchParam', function (event, searchParameter) {
///
});
$scope.$on('advanced-searchbox:removedSearchParam', function (event, searchParameter) {
///
});
$scope.$on('advanced-searchbox:removedAllSearchParam', function (event) {
///
});
$scope.$on('advanced-searchbox:enteredEditMode', function (event, searchParameter) {
///
});
$scope.$on('advanced-searchbox:leavedEditMode', function (event, searchParameter) {
///
});
$scope.$on('advanced-searchbox:modelUpdated', function (event, model) {
///
});
Available Search Parameters Properties
| Name | Description | Type |
|---|---|---|
| key | Unique key of the search parameter that is used for the ng-model value. | string |
| name | User friendly display name of the search parameter. | string |
| placeholder | Specifies a short hint in the parameter search box | string |
| allowMultiple | Should multiple search parameters of the same key allowed? Output type changes to array of values. Default is false. | boolean |
| suggestedValues | An array of suggested search values, e.g. ['Berlin', 'London', 'Paris'] | string[] |
| restrictToSuggestedValues | Should it restrict possible search values to the ones from the suggestedValues array? Default is false. | boolean |
Full example:
$scope.availableSearchParams = [
{ key: "name", name: "Name", placeholder: "Name..." },
{ key: "city", name: "City", placeholder: "City...", restrictToSuggestedValues: true, suggestedValues: ['Berlin', 'London', 'Paris'] }
{ key: "email", name: "E-Mail", placeholder: "E-Mail...", allowMultiple: true },
];