{"id":20816062,"url":"https://github.com/arillo/backbone.facetr","last_synced_at":"2025-05-07T12:40:57.331Z","repository":{"id":6929712,"uuid":"8180898","full_name":"arillo/Backbone.Facetr","owner":"arillo","description":"A library to perform faceted search on Backbone collections","archived":false,"fork":false,"pushed_at":"2016-01-14T16:48:12.000Z","size":725,"stargazers_count":47,"open_issues_count":0,"forks_count":3,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-04-14T19:07:57.422Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://arillo.github.io/Backbone.Facetr/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arillo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-02-13T14:45:24.000Z","updated_at":"2021-02-04T15:13:06.000Z","dependencies_parsed_at":"2022-08-26T17:21:13.367Z","dependency_job_id":null,"html_url":"https://github.com/arillo/Backbone.Facetr","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arillo%2FBackbone.Facetr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arillo%2FBackbone.Facetr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arillo%2FBackbone.Facetr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arillo%2FBackbone.Facetr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arillo","download_url":"https://codeload.github.com/arillo/Backbone.Facetr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252879190,"owners_count":21818744,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-17T21:27:50.464Z","updated_at":"2025-05-07T12:40:57.308Z","avatar_url":"https://github.com/arillo.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# Backbone.Facetr\n\n[![npm](https://img.shields.io/npm/l/backbone.facetr.svg)](https://www.npmjs.com/package/backbone.facetr)\n[![npm](https://img.shields.io/npm/v/backbone.facetr.svg)](https://www.npmjs.com/package/backbone.facetr)\n[![Bower](https://img.shields.io/bower/v/Backbone.Facetr.svg)](https://github.com/arillo/Backbone.Facetr)\n[![Build Status](https://travis-ci.org/arillo/Backbone.Facetr.svg?branch=master)](https://travis-ci.org/arillo/Backbone.Facetr)\n[![Coverage Status](https://coveralls.io/repos/arillo/Backbone.Facetr/badge.svg?branch=master\u0026service=github)](https://coveralls.io/github/arillo/Backbone.Facetr?branch=master)\n\n### \u003ca name=\"contents\"\u003e\u003c/a\u003e CONTENTS\n\n* [INTRODUCTION](#introduction)\n* [INSTALLATION](#installation)\n* [BASIC USAGE](#basic-usage)\n* [DOT NOTATION](#dot-notation)\n* [OPERATORS](#operators)\n* [API REFERENCE](#api-reference)\n* [EXAMPLES](#examples)\n* [LICENSE](#license)\n\n### \u003ca name=\"introduction\"\u003e\u003c/a\u003e INTRODUCTION\n\nBackbone.Facetr is an utility which enables filtering of Backbone collections through facets. It can be used to implement faceted search, which follows the\n[faceted classification system](http://en.wikipedia.org/wiki/Faceted_classification).\n\nIt works flawlessly up to 2500 items; computation starts getting slower with 5000 - 10000 items. This is however an \nearly version; optimizations may improve performance in future realeases.\n\n\n### \u003ca name=\"installation\"\u003e\u003c/a\u003e INSTALLATION\n\nProduction bundles can be found in the dist folder. Facetr is distributed via bower and npm.\nBoth AMD and CommonJS are supported.\n\n#### npm\n\n```bash\nnpm install backbone.facetr --save\n```\n\n#### bower\n\n```bash\nbower install Backbone.Facetr --save\n```\n\n#### build from source\n\n```bash\ngit clone git@github.com:arillo/Backbone.Facetr.git # clone repo\ncd Backbone.Facetr # navigate to local repo\nnpm install -g grunt-cli # install grunt globally\nnpm install # install dependencies\ngrunt # build to dist folder\n```\n\nInclude in your code using any of the following methods\n\n#### AMD\n\n```js\ndefine('yourmodule', ['backbone.facetr'], function(Facetr){\n    // ... \n});\n```\n\n#### CommonJS\n\n```js\nvar Facetr = require('backbone.facetr');\n```\n\n#### script tag\n\n```html\n\u003c!-- deps --\u003e\n\u003cscript src=\"path/to/libs/backbone.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"path/to/libs/underscore.js\"\u003e\u003c/script\u003e\n\u003c!-- facetr --\u003e\n\u003cscript src=\"path/to/libs/backbone.facetr.js\"\u003e\u003c/script\u003e\n```\n\n### \u003ca name=\"basic-usage\"\u003e\u003c/a\u003e BASIC USAGE\n\n```js\n// create a collection with few test items\nvar collection = new Backbone.Collection([\n    {\n        'Name'      : {\n            'FirstName' : 'Bob',\n            'LastName' : 'Smith'\n        },\n        'Age'       : 20,\n        'Country'   : 'Australia',\n        'Hobbies'   : ['fishing','painting','playing the ukulele'],\n        'Profession': 'manager'\n    },\n    {\n        'Name'      : {\n            'FirstName' : 'Otto',\n            'LastName'  : 'Von Braun'\n        },\n        'Age'       : 35,\n        'Country'   : 'New Zealand',\n        'Hobbies'   : ['drawing', 'painting', 'shopping'],\n        'Profession': 'team manager'\n    },\n    {\n        'Name'      : {\n            'FirstName' : 'Sarah',\n            'LastName'  : 'Smith'\n        },\n        'Age'       : 28,\n        'Country'   : 'Ireland',\n        'Hobbies'   : ['shopping','painting'],\n        'Profession': 'project manager'\n    }\n]);\n\nFacetr(collection).facet('Name.LastName').value('Smith'); // collection contains 'Sarah Smith' and 'Bob Smith'\nFacetr(collection).facet('Hobbies').value('shopping'); // contains only 'Sarah Smith' \nFacetr(collection).facet('Name.LastName').removeValue('Smith'); // contains 'Sarah Smith' and 'Otto Von Braun'\n\n// removes all facet values and restores original collection content\nFacetr(collection).clearValues();\n\n// if chaining is not your cup of tea, the following is equivalent to the above code\nvar facetCollection = Facetr(collection); // returns a FacetCollection object\nvar lastNameFacet = facetCollection.facet('Name.LastName'); // returns a Facet object\nvar hobbiesFacet = facetCollection.facet('Hobbies');\n\nlastNameFacet.value('Smith'); // returns a FacetExp object\nhobbiesFacet.value('shopping');\nlastNameFacet.removeValue('Smith');\n\n// read the API Reference section for more\n// most examples will use the above collection reference to illustrate functionalities\n```\n\n### \u003ca name=\"dot-notation\"\u003e\u003c/a\u003e DOT NOTATION\n\n    Syntax: PropertyName{1}(.PropertyName)*\n\n\nIn the context of Facetr, Dot Notation refers to the syntax used to define facets on a collection. Using the \nFacetr Dot Notation it is possible to define facets on properties of a Model, as well as on properties of its properties.\n\nFor example, consider the following model:\n\n```js\nvar model = new Backbone.Model({\n    'Name' : {\n        'FirstName' : 'John',\n        'LastName' : ['Smith','White']\n    },\n    'City' : 'London',\n    'Age' : 45,\n    'FamilyMembers' : [\n        { 'Name' : 'Robert' },\n        { 'Name' : 'Margaret' }\n    ]\n});\n```\n\nTo add a facet on property 'FirstName' the following expression in Dot Notation syntax can be used: 'Name.FirstName'.\n\n```js\nFacetr(collection).facet('Name.FirstName');\n```\n\nTheoretically there is no depth limit for a Dot Notation expression (e.g. PropertyName1.PropertyName2...PropertyNameN), the only \nlimitation being the common sense.\n\nA facet can only be added on a Backbone Model or object property having any of the following value types:\n \n* string | number | boolean\n* Array of strings\n* Array of numbers\n* Array of booleans\n* Array of objects\n* Array of Backbone models\n\nIt cannot be added on properties having the following value / composite types:\n\n* object\n* Backbone Collection\n* Array of arrays\n* Array of Backbone collections\n\n.. and in any other case not mentioned in the list of allowed value types\n\n\n#### EXAMPLE\n\n```js\nFacetr(collection).facet('City');               // valid, City is a string\nFacetr(collection).facet('Age');                // valid, Age is a Number\nFacetr(collection).facet('Name.LastName');      // valid, LastName is an Array of strings\nFacetr(collection).facet('FamilyMembers.Name'); // valid, takes value of Name of each object in array FamilyMembers\nFacetr(collection).facet('Name');               // error, Name is an object\n\n// etc..\n```\n\n\n### \u003ca name=\"operators\"\u003e\u003c/a\u003e OPERATORS\n\nFacets filtering can be combined using logical operators 'or' and 'and', both between different facets (external operator, see [FacetCollection.facet method](#facetcollection-facet)) and between values of one facet (internal operator, see [Facet.value method](#facet-value) and [FacetExp](#facetexp)).\n\n#### External Operator\n\n```js\n// create a facet with default external operator 'and'\nvar facetCountry = Facetr(collection).facet('Country');\n\n// or set the external operator explicitly\nvar facetLastName = Facetr(collection).facet('Name.LastName', 'and');\n\n// when filtering, such operator will be used to combine filters of the two facets\nfacetCountry.value('Australia');\nfacetLastName.value('Smith');\n\n// collection contains all models with Country equal 'Australia' and LastName equal 'Smith'\n```\n\n#### Internal Operator\n\n```js\n// add a value with default internal operator 'or'\nfacetCountry.value('Australia');\n\n// or set the internal operator explicitly\nfacetCountry.value('Ireland', 'or');\n\n// it is possible to use chaining syntax to combine values\nfacetCountry.value('Australia').or('Ireland');\n\n// collection contains all models with Country equal either 'Australia' or 'Ireland'\n```\n\n### \u003ca name=\"api-reference\"\u003e\u003c/a\u003e API Reference\n\n* [Facetr](#facetr)\n\n* [FacetCollection](#facetcollection)\n    * [facet](#facetcollection-facet)\n    * [toJSON](#facetcollection-tojson)\n    * [clear](#facetcollection-clear)\n    * [remove](#facetcollection-remove)\n    * [sortBy](#facetcollection-sortby)\n    * [asc](#facetcollection-asc)\n    * [desc](#facetcollection-desc)\n    * [addFilter](#facetcollection-addfilter)\n    * [removeFilter](#facetcollection-removefilter)\n    * [clearFilters](#facetcollection-clearfilters)\n    * [clearValues](#facetcollection-clearvalues)\n    * [facetsOrder](#facetcollection-facetsorder)\n    * [collection](#facetcollection-collection)\n    * [origLength](#facetcollection-origlength)\n    * [facets](#facetcollection-facets)\n    * [settingsJSON](#facetcollection-settingsjson)\n    * [initFromSettingsJSON](#facetcollection-initfromsettingsjson)\n\n* [Facet](#facet)\n    * [value](#facet-value)\n    * [removeValue](#facet-removevalue)\n    * [toJSON](#facet-tojson)\n    * [label](#facet-label)\n    * [sortByCount](#facet-sortbycount)\n    * [sortByActiveCount](#facet-sortbyactivecount)\n    * [sortByValue](#facet-sortbyvalue)\n    * [asc](#facet-asc)\n    * [desc](#facet-desc)\n    * [remove](#facet-remove)\n    * [clear](#facet-clear)\n    * [customData](#facet-customdata)\n    * [isSelected](#facet-isselected)\n    * [hierarchy](#facet-hierarchy)\n\n* [FacetExp](#facetexp)\n    * [and](#facetexp-and)\n    * [or](#facetexp-or)\n\n\n### \u003ca name=\"facetr\"\u003e\u003c/a\u003e Facetr\n    \n##### Facetr(collection:Backbone.Collection, [id:string]) : FacetCollection                     \n    \nInitialize a Collection to be used with Facetr. The first building block of\nany Facetr expression. Returns the created FacetCollection instance for\nmethod chaining. An id can be associated with the collection.\n    \n**Example**\n\n```js\nFacetr(collection);\n\n// or also\nFacetr(collection, 'myCollection');\n\n// which enables the following syntax\nFacetr('myCollection') === Facetr(collection); // true\n```\n\n### \u003ca name=\"facetcollection\"\u003e\u003c/a\u003e FacetCollection\n\n\n##### \u003ca name=\"facetcollection-facet\"\u003e\u003c/a\u003e facet(dotNotationExpr:string, [externalOperator:string], [silent:boolean]) : Facet\n\nAdds a Facet on the given collection using the property refered to by the\nDot Notation expression (see [Dot Notation section](#dot-notation) for more details).\nValid [external operator](#operators) values are: 'or' and 'and' (default is 'and').\nReturns the created Facet instance to allow method chaining.\nTriggers a facet event with the facetName passed to the callback, unless true is passed as last parameter.\n\n**Example**\n\n```js\nFacetr(collection).on('facet', function(facetName) {\n    console.log('added facet', facetName);\n});\n\n// add facet on property 'Age' using default operator ('and')\nFacetr(collection).facet('Age');\n\n// add facet on property 'LastName' of object 'Name' using 'or' operator\nFacetr(collection).facet('Name.LastName', 'or');\n\n// console output would be\n// added facet Age\n// added facet Name.LastName\n```\n\n\n##### \u003ca name=\"facetcollection-tojson\"\u003e\u003c/a\u003e toJSON() : Array\n\nReturns an array containing objects representing the status of the facets\nadded to the collection. Useful for rendering out facets lists.\nEach object in the array is the result of invoking toJSON on each Facet\n(see Facet documentation below for the Facet.toJSON method).\n\n**Example**\n\n```js\n// create a collection with two models\nvar collection = new Backbone.Collection([\n    {\n        'Name'      : {\n            'FirstName' : 'Bob',\n            'LastName' : 'Smith'\n        },\n        'Age'       : 20\n    },\n    {\n        'Name'      : {\n            'FirstName' : 'Otto',\n            'LastName'  : 'Von Braun'\n        },\n        'Age'       : 35\n    }\n]);\n\nFacetr(collection).facet('Name.FirstName').label('First Name');\nFacetr(collection).facet('Name.FirstName').value('Bob');\n\nvar json = Facetr(collection).toJSON();\n\n// value of json will be an array of Facet data object with the following format:\n//\n// [\n//      {\n//          data : {\n//              extOperator : 'and',\n//              intOperator : 'or',\n//              label       : 'First Name',\n//              name        : 'Name.FirstName',\n//              selected    : true,\n//              sort        : {\n//                  by        : 'value',\n//                  direction : 'asc'\n//              }\n//              customData : {}\n//          },\n//          values : [\n//              {\n//                  active      : true,\n//                  activeCount : 1,\n//                  count       : 1,\n//                  value       : 'Bob'\n//              },\n//              {\n//                  active      : false,\n//                  activeCount : 0,\n//                  count       : 1,\n//                  value       : 'Otto'\n//              }\n//          ]\n//      }\n// ]\n```\n\n\n##### \u003ca name=\"facetcollection-clear\"\u003e\u003c/a\u003e clear([silent:boolean]) : FacetCollection\n\nRemoves all the facets added to the collection and unfilters it accordingly.\nUse this method to reset the original models in the collection.\nTriggers a clear event, unless true is passed as parameter.\n\n**Example**\n\n```js\nFacet(collection).on('clear', function() {\n    console.log('All facets were removed');\n});\n\nFacet(collection).clear();\n\n// console output:\n// All facets were removed\n```\n\n\n##### \u003ca name=\"facetcollection-remove\"\u003e\u003c/a\u003e remove() : undefined\n\nRemoves all the facets and the facetrid added on the collection id upon\nFacetr(collection) initialization. Resets the original items in the\ncollection.\n\n**Example**\n\n```js\nFacetr(collection).remove()\n```\n\n##### \u003ca name=\"facetcollection-sortby\"\u003e\u003c/a\u003e sortBy(attribute:string, [silent]) : FacetCollection\n\nSorts the collection according to the given attribute name. By default\nascendent sort is used. See asc() and desc() methods below to define sort\ndirection. Triggers sort event unless true is passed as last parameter.\nThis method automatically recognizes string, numeric or date values.\n\n**Example**\n\n```js\nFacetr(collection).on('sort', function(attr, dir) {\n    console.log('Sorting by ' + attr + ' ' + dir);\n});\n\nFacetr(collection).sortBy('Age');\n\n// console output:\n// Sorting by Age asc\n```\n\n##### \u003ca name=\"facetcollection-asc\"\u003e\u003c/a\u003e asc([silent:boolean]) : FacetCollection\n\nSorts the collection in ascendent order by the attribute selected using\nsortBy method.\nIf sortBy was not invoked before, this method has no effect. Triggers sort\nevent unless true is passed as parameter.\n\n**Example**\n\n```js\nFacetr(collection).sortBy('Age').asc();\n```\n\n##### \u003ca name=\"facetcollection-desc\"\u003e\u003c/a\u003e desc([silent:boolean]) : FacetCollection\n\nSorts the collection in descendent order by the attribute selected using\nsortBy method.\nIf sortBy was not invoked before, this method has no effect. Triggers sort\nevent unless true is passed as parameter.\n\n**Example**\n\n```js\nFacetr(collection).sortBy('Age').desc();\n```\n\n##### \u003ca name=\"facetcollection-addfilter\"\u003e\u003c/a\u003e addFilter(filterName:string, filter:function, [silent:boolean]) : FacetCollection\n\nAdds a filter which is used to filter the collection by testing each model against it. \nTriggers Backbone.Collection reset unless true is passed as last parameter. Multiple filters can be added as long as they have\ndifferent names. Adding two filters with the same name will result in the first being overwritten by the second.\n\n**Example**\n\n```js\nFacetr(collection).addFilter('AgeFilter', function(model) {\n    return model.get('Age') \u003e= 20 \u0026\u0026 model.get('Age') \u003c 60; \n});\n```\n\n\n##### \u003ca name=\"facetcollection-removefilter\"\u003e\u003c/a\u003e removeFilter(filterName:string, [silent:boolean]) : FacetCollection\n\nRemoves the filter with the given name from the collection and unfilters it accordingly. \nTriggers reset unless true is passed as last parameter.\n\n**Example**\n\n```js\nFacetr(collection).removeFilter('AgeFilter');\n```\n\n##### \u003ca name=\"facetcollection-clearfilters\"\u003e\u003c/a\u003e clearFilters([silent:boolean]) : FacetCollection\n\nRemoves all the filters previously added to the collection and unfilters it accordingly. \nTriggers reset unless true is passed as parameter.\n\n**Example**\n\n```js\nFacetr(collection).clearFilters();\n```\n\n##### \u003ca name=\"facetcollection-clearvalues\"\u003e\u003c/a\u003e clearValues([silent:boolean]) : FacetCollection\n\nRemoves all the currently selected values from all the facets, bringing\nthe collection to its initial state.\nTriggers a clearValues event unless true is passed as parameter.\n\n**Example**\n\n```js\nFacetr(collection).clearValues();\n```\n\n##### \u003ca name=\"facetcollection-facetsorder\"\u003e\u003c/a\u003e facetsOrder(facetNames:Array, [silent:boolean]) : FacetCollection\n\nSometimes it is convinient to give the facets list a predefined order. This method\ncan be used to achieve this by passing an array of facet names which corresponds to\nthe order to be given to the facets in the list. Triggers a 'facetsOrder' event with the facetNames array passed\nto the event handler, unless true is given as last parameter.\n\n**Example**\n\n```js\nFacetr(collection).facet('Age');\nFacetr(collection).facet('Name.FirstName');\n\n// Facetr(collection).toJSON() has facet 'Age' at index 0 and 'Name.FirstName' at index 1\n\nFacetr(collection).facetsOrder(['Name.FirstName', 'Age']);\n\n// Facetr(collection).toJSON() has facet 'Name.FirstName' at index 0 and 'Age' at index 1\n```\n\n\n##### \u003ca name=\"facetcollection-collection\"\u003e\u003c/a\u003e collection() : Backbone.Collection\n\nReturns the reference to the Backbone.Collection. Useful for cases where the reference\nis needed but it was declared in another scope and is no more accessible.\n\n**Example**\n\n```js\nFacetr(collection).collection() === collection; // true\n```\n\n##### \u003ca name=\"facetcollection-origlength\"\u003e\u003c/a\u003e origLength() : Number\n\nReturns the length of the collection before any faceted filtering was applied.\n\n**Example**\n\n```js\nvar collection = new Backbone.Collection([\n    {\n        Name : 'John'\n        Age  : 19\n    },\n    {\n        Name : 'Sarah',\n        Age  : 35\n    }\n]);\n\ncollection.length() // 2\n\nFacetr(collection).facet('Age').value(35);\n\ncollection.length(); // 1\nFacetr(collection).origLength(); // 2\n```\n\n##### \u003ca name=\"facetcollection-facets\"\u003e\u003c/a\u003e facets() : Array\n\nReturns an array containing all the Facet instances created on this FacetCollection.\n\n##### \u003ca name=\"facetcollection-settingsjson\"\u003e\u003c/a\u003e settingsJSON() : object\n\nReturns an object representation of the current state of the Facetr collection which\ncan be used to reload the same state in future using the initFromSettingsJSON method.\n\n**Example**\n    \n```js\nFacetr(collection).facet('Name.FirstName').label('First Name');\nFacetr(collection).sortBy('Name.FirstName').asc();\nFacetr(collection).facet('Name.FirstName').value('Bob');\n\nvar json = Facetr(collection).settingsJSON();\n\n// value of json will be the following:\n//  \n// {\n//      sort : {\n//          by  :   \"Name.FirstName\",\n//          dir :   \"asc\"\n//      },\n//      facets : [\n//          {\n//              attr    :   \"Name.FirstName\",\n//              eop     :   \"and\",\n//              iop     :   \"or\",\n//              vals    :   [ \"Bob\" ]\n//          }\n//      ]\n//  }\n```\n\n##### \u003ca name=\"facetcollection-initfromsettingsjson\"\u003e\u003c/a\u003e initFromSettingsJSON(json:object) : FacetCollection\n\nInitializes the Facetr collection using a settings object generated\nusing the settingsJSON method. Triggers an \"initFromSettingsJSON\" event.\n\n\n### \u003ca name=\"facet\"\u003e\u003c/a\u003e Facet\n\n##### \u003ca name=\"facet-value\"\u003e\u003c/a\u003e value(value:string, [internalOperator:string], [silent:boolean]) : FacetExp\n\nAdds a value to the facet. This will result in the collection being filtered\nby { FacetName : 'Value' }. Valid [internal operator](#operators) values are: 'or' and 'and' (default is 'or').\nTriggers a 'filter' event on the FacetCollection passing facetName and facetValue to the handler and \na 'value' event on the Facet passing the facetValue to the handler, unless true is passed\nas last parameter.\n\n**Example**\n    \n```js\nFacetr(collection).on('filter', function(facetName, facetValue) {\n    console.log('filtered by '+ facetName + ' with value equal ' + facetValue);\n});\n\nvar facet = Facetr(collection).facet('Name.FirstName');\n\nfacet.on('value', function(facetValue){\n    console.log('the following value was added to the facet: ' + facetValue);\n});\n\nfacet.value('Bob');\n\n// console output: \"filtered by Name.FirstName with value Bob\"\n// collection contains only models with FirstName = 'Bob'\n```\n\n##### \u003ca name=\"facet-removevalue\"\u003e\u003c/a\u003e removeValue(value:string, [silent:boolean]) : FacetExp\n\nRemoves the given value from the facet and resets the collection to\nthe state previous of the filtering caused by the removed value.\nTriggers a 'unfilter' event on the FacetCollection passing facetName and facetValue to the handler and \na 'removeValue' event on the Facet passing the facetValue to the handler, unless true is passed\nas last parameter.\n\n**Example**\n    \n```js\nFacetr(collection).on('unfilter', function(facetName, facetValue) {\n    console.log('unfiltered by '+ facetName + ' with value equal ' + facetValue);\n});\n\nvar facet = Facetr(collection).facet('Name.FirstName');\n\nfacet.on('removeValue', function(value){\n    console.log('the following value was removed from the facet: ' + value);\n});\n\nfacet.removeValue('Bob');\n\n// console output: \"unfiltered by Name.FirstName with value Bob\"\n// collection contains again also models with FirstName = 'Bob'\n```\n\n##### \u003ca name=\"facet-tojson\"\u003e\u003c/a\u003e toJSON() : object\n\nReturns an object representation of the current facet data and values.\nUseful for rendering the facet to the page.\n\n**Example**\n\n```js\n// create a collection with two models\nvar collection = new Backbone.Collection([\n    {\n        'Name'      : {\n            'FirstName' : 'Bob',\n            'LastName' : 'Smith'\n        },\n        'Age'       : 20\n    },\n    {\n        'Name'      : {\n            'FirstName' : 'Otto',\n            'LastName'  : 'Von Braun'\n        },\n        'Age'       : 35\n    }\n]);\n\nFacetr(collection).facet('Name.FirstName').label('First Name');\nFacetr(collection).facet('Name.FirstName').value('Bob');\n\nvar json = Facetr(collection).facet('Name.FirstName').toJSON();\n\n// json is equal to:\n//\n//  {\n//      data : {\n//          extOperator : 'and',\n//          intOperator : 'or',\n//          label       : 'First Name',\n//          name        : 'Name.FirstName',\n//          selected    : true,\n//          sort        : {\n//              by        : 'value',\n//              direction : 'asc'\n//          }\n//          customData : {}\n//      },\n//      values : [\n//          {\n//              active      : true,\n//              activeCount : 1,\n//              count       : 1,\n//              value       : 'Bob'\n//          },\n//          {\n//              active      : false,\n//              activeCount : 0,\n//              count       : 1,\n//              value       : 'Otto'\n//          }\n//      ]\n//  }\n```\n\n##### \u003ca name=\"facet-label\"\u003e\u003c/a\u003e label(label:string) : Facet\n\nUse this method to set a human readable label for the facet.\nThis can be used when rendering the facet on the page.\n\n**Example**\n\n```js\nFacetr(collection).facet('Name.FirstName').label('First Name');\n\nFacetr(collection).facet('Name.FirstName').toJSON();\n\n// the property data.label has value 'First Name'\n// while the property data.name stays 'Name.FirstName'\n```\n\n##### \u003ca name=\"facet-sortbycount\"\u003e\u003c/a\u003e sortByCount() : Facet\n\nSorts the facet values by their count. The count is the number \nof models in the original collection with an attribute having as name \nthe facet name and value the given value.\n\n**Example**\n\n```js\n// we use the colleciton defined in Basic Usage section\nvar facet = Facetr(collection).facet('Hobbies');\n\nfacet.value('painting'); // painting count = 3  \nfacet.value('drawing');  // drawing count = 1\n\n// facet.toJSON().data.values[0] = 'drawing'\n// facet.toJSON().data.values[1] = 'painting'\n\nfacet.sortByCount();\n\n// facet.toJSON().data.values[0] = 'painting'\n// facet.toJSON().data.values[1] = 'drawing'\n```\n\n##### \u003ca name=\"facet-sortbyactivecount\"\u003e\u003c/a\u003e sortByActiveCount() : Facet\n\nSorts the facet values by their active count. The active count is the number\nof models in the current filtered collection with an attribute having as name\nthe facet name and value the given value.\n\n**Example**\n\n```js\nvar facet = Facetr(collection).facet('Hobbies');\n\nfacet.value('fishing');\nfacet.value('shopping');\n\n// fishing active count = 1\n// shopping active count = 2\n\n// facet.toJSON().data.values[0] = 'fishing'\n// facet.toJSON().data.values[1] = 'shopping'\n\nfacet.sortByActiveCount();\n\n// facet.toJSON().data.values[0] = 'shopping'\n// facet.toJSON().data.values[1] = 'fishing'\n```\n\n##### \u003ca name=\"facet-sortbyvalue\"\u003e\u003c/a\u003e sortByValue() : Facet\n\nSorts the facet values by their value. This is the default sort.\n\n##### \u003ca name=\"facet-asc\"\u003e\u003c/a\u003e asc() : Facet\n\nSets the direction of the values sort to ascendent.\n\n**Example**\n\n```js\nFacetr(collection).facet('Name.FirstName').asc();\n```\n\n##### \u003ca name=\"facet-desc\"\u003e\u003c/a\u003e desc() : Facet\n\nSets the direction of the values sort to descendant.\n\n**Example**\n\n```js\nFacetr(collection).facet('Name.FirstName').sortByCount().desc();\n```\n\n##### \u003ca name=\"facet-remove\"\u003e\u003c/a\u003e remove([silent:boolean]) : undefined\n\nRemoves the facet and all its values and unfilters the collection accordingly.\nIt triggers a \"removeFacet\" event on the facet collection, unless true is passed as parameter.\n\n```js\nvar facetCollection = Facetr(collection);\nvar facet = facetCollection.facet('Age');\n\nfacetCollection.on('removeFacet', function(facetName){\n    console.log('removed facet', facetName);\n});\n\nfacet.remove();\n\n// console output would be\n// removed facet Age\n```\n\n##### \u003ca name=\"facet-clear\"\u003e\u003c/a\u003e clear([silent:boolean]) : Facet\n\nUnselects all the values from the facet. It triggers a 'clear' event unless true is passed as parameter.\n\n##### \u003ca name=\"facet-customdata\"\u003e\u003c/a\u003e customData(key:string, [value:object]) : Facet\n\nThis method can be used to add arbitrary data to pass to the templates.\nData added using this method is included in the object returned by the toJSON() method\nin the data.customData property.\nTo retrieve previously set data, just pass the key parameter without any value.\n\n**Example**\n\n```js\nvar facet = Facetr('myCollection').facet('Hobbies').customData('sublabel', 'Available hobbies');\n\n// facet.customData('sublabel') returns 'Available hobbies'\n// facet.toJSON().data.customData = { sublabel : 'Available hobbies' }\n```\n\n##### \u003ca name=\"facet-isselected\"\u003e\u003c/a\u003e isSelected : Boolean\n\nReturns true if any value is selected from this facet, false otherwise.\n\n**Example**\n\n```js\nvar facet = Facetr('myCollection').facet('Hobbies');\n\nfacet.value('fishing');\n\n// facet.isSelected() returns true\n\nfacet.clear(); // remove all selected values\n\n// facet.isSelected() returns false\n```\n\n##### \u003ca name=\"facet-hierarchy\"\u003e\u003c/a\u003e hierarchy(hierarchySettings:Array) : Facet\n\nThis method creates a hierarchical representation of facet values, based on the settings\nobject given as parameter. Once this method is used, the facet becomes a \"hierarchical\" facet.\nYou can then use the facet as you usually would, with the following differences:\n\n* the data section of the object resulting from invoking the toJSON method will also\n  contain a \"hierarchical\" property with value true and a \"groupedValues\" array, with the following format:\n\ngroupedValues\n\n```js\n[\n    {\n        value: \"manager\",\n        label: \"Manager\",\n        active: false,\n        activeCount: 7,\n        count: 7,\n        groups: [\n            {\n                value: \"team manager\",\n                label: \"Team Manager\",\n                active: false,\n                activeCount: 5,\n                count: 5,\n                groups: [\n                    { ... other groups values ... }\n                ]\n            },\n             {\n                value: \"manager\",\n                label: \"Manager\",\n                active: false,\n                activeCount: 5,\n                count: 5 // no groups property means that this value has no children groups\n            },\n        ]\n    }\n]\n```\n\n* when a value from the facet is selected, also the models resulting from selecting its descendents values are\n  included in the result set\n\n* the count includes both the count of the value itself and that of its descendants values\n\nThe hierarchySettings argument is an array with different \"hierarchical value\" objects, where it is possible\nto specify the hierarchy of values along with a label. See the **Example** below to understand the hierarchySettings format.\n\n**Example**\n\n```js\n    var hierarchySettings = [\n        {               \n            value: \"manager\",\n            label: \"Manager\",\n            groups: [\n                {\n                    value: \"project manager\",\n                    label: \"Project Manager\",\n                    groups: [\n                        {\n                            value: \"team manager\",\n                            label: \"Team Manager\"\n                        }\n                    ]\n                }\n            ]\n        }\n    ];\n\n    var profession = Facetr(collection).facet('Profession').hierarchy(hierarchySettings);\n\n    var json = profession.toJSON();\n\n    // value of json variable would be:\n    //\n    // {\n    //  \"data\": {\n    //      \"name\":\"Profession\",\n    //      \"hierarchical\":true,\n    //      \"label\":\"Profession\",\n    //      \"extOperator\":\"and\",\n    //      \"intOperator\":\"or\",\n    //      \"sort\":{\n    //          \"by\":\"activeCount\",\n    //          \"direction\":\"desc\"\n    //      },\n    //      \"selected\":false,\n    //      \"customData\":{}\n    //  },\n    //  \"values\": [ ... stays as the normal facets ... ],\n    //  \"groupedValues\":[\n    //      {\n    //          \"value\":\"manager\",\n    //          \"label\":\"Manager\",\n    //          \"active\":false,\n    //          \"activeCount\":3,\n    //          \"count\":3,\n    //          \"groups\":[\n    //              {\n    //                  \"value\":\"project manager\",\n    //                  \"label\":\"Project Manager\",\n    //                  \"active\":false,\n    //                  \"activeCount\":2,\n    //                  \"count\":2,\n    //                  \"groups\":[\n    //                      {\n    //                          \"value\":\"team manager\",\n    //                          \"label\":\"Team Manager\",\n    //                          \"active\":false,\n    //                          \"activeCount\":1,\n    //                          \"count\":1\n    //                      }\n    //                  ]\n    //              }\n    //          ]\n    //      }\n    //  ]\n    // }\n```\n\n### \u003ca name=\"facetexp\"\u003e\u003c/a\u003e FacetExp\n\nFacetExp objects are returned from Facet value and removeValue methods.\nThey can be used to coincisely define multiple values on a facet, using\ndifferent operators.\n\n**Example**\n\n```js\nFacetr(collection).facet('Age').value(12, 'and');\nFacetr(collection).facet('Age').value(15, 'or');\nFacetr(collection).facet('Age').value(39, 'and');\n\n// can also be expressed with the following syntax\n\nFacetr(collection).facet('Age').value(12, 'and').or(15).and(39);\n```\n\n##### \u003ca name=\"facetexp-and\"\u003e\u003c/a\u003e and(value:string, [silent:boolean]) : Facet\n\nEquivalent to facet.value('Value', 'and'), but can be used for FacetExp chains.\n\n##### \u003ca name=\"facetexp-or\"\u003e\u003c/a\u003e or(value:string, [silent:boolean]) : Facet\n\nEquivalent to facet.value('Value', 'or'), but can be used for FacetExp chains.\n\n\n### \u003ca name=\"examples\"\u003e\u003c/a\u003e EXAMPLES\n\nThis section contains a list of websites / projects using Facetr.\n\n* [ruefer-ing.ch](http://ruefer-ing.ch/referenzen)\n* [terra-vecchia.ch](http://terra-vecchia.ch/sozialtherapie/angebote-und-betriebe)\n* [grimselhydro.ch](http://grimselhydro.ch/referenzen)\n\n### \u003ca name=\"license\"\u003e\u003c/a\u003e LICENSE\n\nBackbone.Facetr may be freely distributed under the MIT license.\n\nCopyright (C) 2012 Arillo GmbH http://arillo.net\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies \nof the Software, and to permit persons to whom the Software is furnished to do so, \nsubject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies\nor substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, \nINCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR \nPURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE\nFOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR \nOTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER \nDEALINGS IN THE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farillo%2Fbackbone.facetr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farillo%2Fbackbone.facetr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farillo%2Fbackbone.facetr/lists"}