{"id":13596409,"url":"https://github.com/evoluteur/structured-filter","last_synced_at":"2025-04-04T09:08:42.122Z","repository":{"id":4507157,"uuid":"5646721","full_name":"evoluteur/structured-filter","owner":"evoluteur","description":"jQuery UI widget for structured queries like \"Contacts where Firstname starts with A and Birthday before 1/1/2000 and State in (CA, NY, FL)\"...","archived":false,"fork":false,"pushed_at":"2024-03-17T08:49:49.000Z","size":461,"stargazers_count":263,"open_issues_count":7,"forks_count":60,"subscribers_count":17,"default_branch":"main","last_synced_at":"2025-03-28T08:07:21.957Z","etag":null,"topics":["evolutility","faceted-search","filter","filter-plugin","filtering","filterlist","jquery-plugin","jquery-ui","metadata","metadata-driven","query-builder","querybuilder","search-interface","searchbar","searchview","structured-data","ui","ui-component","whereclause","widget"],"latest_commit_sha":null,"homepage":"http://evoluteur.github.io/structured-filter/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/evoluteur.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"evoluteur"}},"created_at":"2012-09-02T08:02:32.000Z","updated_at":"2025-02-23T00:47:51.000Z","dependencies_parsed_at":"2024-06-19T19:04:46.094Z","dependency_job_id":"fa4a5dae-d74f-46b0-acd9-71aa6280d32c","html_url":"https://github.com/evoluteur/structured-filter","commit_stats":{"total_commits":239,"total_committers":14,"mean_commits":"17.071428571428573","dds":0.5941422594142259,"last_synced_commit":"db7c271fef9b30729de438c8db22682ba1b5f016"},"previous_names":[],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evoluteur%2Fstructured-filter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evoluteur%2Fstructured-filter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evoluteur%2Fstructured-filter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/evoluteur%2Fstructured-filter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/evoluteur","download_url":"https://codeload.github.com/evoluteur/structured-filter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247149501,"owners_count":20891954,"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":["evolutility","faceted-search","filter","filter-plugin","filtering","filterlist","jquery-plugin","jquery-ui","metadata","metadata-driven","query-builder","querybuilder","search-interface","searchbar","searchview","structured-data","ui","ui-component","whereclause","widget"],"created_at":"2024-08-01T16:02:24.912Z","updated_at":"2025-04-04T09:08:42.100Z","avatar_url":"https://github.com/evoluteur.png","language":"JavaScript","readme":"# Structured-Filter \u0026middot; [![GitHub license](https://img.shields.io/github/license/evoluteur/structured-filter)](https://github.com/evoluteur/structured-filter/blob/master/LICENSE.md) [![npm version](https://img.shields.io/npm/v/structured-filter)](https://www.npmjs.com/package/structured-filter)\n\nStructured-Filter is a generic Web UI for building structured search or filter queries.\n\nWith it you can build structured search conditions like\nFirstname starts with 'A' and Birthday after 1/1/1980 and State in (CA, NY, FL)... It is a full jQuery UI widget, supporting various configurations and themes.\n\n![Structured-Filter screenshot](https://raw.github.com/evoluteur/structured-filter/master/screenshots/structured-filter.gif)\n\n\nCheck the **[demo](http://evoluteur.github.io/structured-filter/index.html)** for live examples.\n\n\n### Table of Contents\n1. [Installation](#Installation)\n2. [Usage](#Usage)\n3. [Model](#Model)\n4. [Options](#Options)\n5. [Methods](#Methods)\n6. [Events](#Events)\n7. [Theming](#Theming)\n8. [License](#License)\n\n\n\u003ca name=\"Installation\"\u003e\u003c/a\u003e\n## Installation\n\nYou can [download](https://github.com/evoluteur/structured-filter/archive/master.zip) or fork structured-filter on [GitHub](https://github.com/evoluteur/structured-filter).\n\n```bash\n# To get the latest stable version, use git from the command line.\ngit clone https://github.com/evoluteur/structured-filter\n```\n\nor install the [npm package](https://www.npmjs.com/package/structured-filter):\n\n```bash\n# To get the latest stable version, use npm from the command line.\nnpm install structured-filter\n```\n\nor install with **Bower**:\n\n```bash\n# To get the latest stable version, use Bower from the command line.\nbower install structured-filter\n\n# To get the most recent, latest committed-to-master version use:\nbower install structured-filter#master\n```\n\nNotes:\n\n- If you use a version of jQuery-UI smaller than 1.12.1, you must use Structured-Filter version 1.1.0.\n- For React, use [Structured-Filter-React](https://github.com/evoluteur/structured-filter-react).\n\n\n\u003ca name=\"Usage\"\u003e\u003c/a\u003e\n## Usage\n\nFirst, load [jQuery](https://jquery.com/), [jQuery UI](https://jqueryui.com/), and the plugin:\n\n```html\n\u003cscript src=\"https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js\" type=\"text/javascript\" charset=\"utf-8\"\u003e\u003c/script\u003e\n\u003cscript src=\"https://ajax.googleapis.com/ajax/libs/jqueryui/1.13.2/jquery-ui.min.js\" type=\"text/javascript\" charset=\"utf-8\"\u003e\u003c/script\u003e\n\u003cscript src=\"js/structured-filter.js\" type=\"text/javascript\" charset=\"utf-8\"\u003e\u003c/script\u003e\n```\n\nThe widget requires a jQuery UI theme to be present, as well as its own included base CSS file ([structured-filter.css](http://github.com/evoluteur/structured-filter/raw/master/css/structured-filter.css)). Here we use the \"base\" theme as an example:\n\n```html\n\u003clink rel=\"stylesheet\" type=\"text/css\" href=\"https://ajax.googleapis.com/ajax/libs/jqueryui/1.12.1/themes/base/jquery-ui.css\"\u003e\n\u003clink href=\"css/structured-filter.css\" rel=\"stylesheet\" type=\"text/css\"\u003e\n```\n\nNow, let's attach it to an existing `\u003cdiv\u003e` tag:\n\n```html\n\u003cscript type=\"text/javascript\"\u003e\n    $(document).ready(function() {\n        $(\"#myFilter\").structFilter({\n            fields: [\n                {id:\"lastname\", type:\"text\", label:\"Lastname\"},\n                {id:\"firstname\", type:\"text\", label:\"Firstname\"},\n                {id:\"active\", type:\"boolean\", label:\"Is active\"},\n                {id:\"age\", type:\"number\", label:\"Age\"},\n                {id:\"bday\", type:\"date\", label:\"Birthday\"},\n                {id:\"category\", type:\"list\", label:\"Category\",\n                    list:[\n                        {id:\"1\", label:\"Family\"},\n                        {id:\"2\", label:\"Friends\"},\n                        {id:\"3\", label:\"Business\"},\n                        {id:\"4\", label:\"Acquaintances\"},\n                        {id:\"5\", label:\"Other\"}\n                    ]\n                }\n            ]\n        });\n    });\n\u003c/script\u003e\n\n\u003cdiv id=\"myFilter\"\u003e\u003c/div\u003e\n```\n\nThis will change the `\u003cdiv\u003e` into the widget.\n\n\n\u003ca name=\"Model\"\u003e\u003c/a\u003e\n## Model\n\nThe widget is configured with a list of fields to use in the search conditions.\n\n### Fields\n\nEach field must have an ID, a type, and a label.\n\n- id - unique identifier for the field.\n- label - displayed field name.\n- type - data type. Possible types of field: text, number, boolean, date, time, list.\n\nFields of type \"list\" must also have a \"list\" property for the values (array of objects with id and label).\n\nExample:\n\n```javascript\nfields = [\n    {id:\"lastname\", type:\"text\", label:\"Lastname\"},\n    {id:\"firstname\", type:\"text\", label:\"Firstname\"},\n    {id:\"active\", type:\"boolean\", label:\"Is active\"},\n    {id:\"age\", type:\"number\", label:\"Age\"},\n    {id:\"bday\", type:\"date\", label:\"Birthday\"},\n    {id:\"category\", type:\"list\", label:\"Category\",\n        list:[\n            {id:\"1\", label:\"Family\"},\n            {id:\"2\", label:\"Friends\"},\n            ...\n        ]\n    }\n];\n```\n\nNote: To change the behavior of a \"list\" field, use the type \"list-options\" and \"list-dropdown\" instead of \"list\".\n\n\n### Conditions\n\nQueries are expressed as a set of conditions.\n\nEach condition is defined by:\n\n- a field\n- an operator\n- one or several values\n\nFor each field the possible operators are determined by it's type.\n\n\n### ![boolean](https://raw.github.com/evoluteur/structured-filter/master/screenshots/ft-bool.gif) boolean\n\n- Yes (1)\n- No (0)\n\n![Boolean field screenshot](https://raw.github.com/evoluteur/structured-filter/master/screenshots/sf-cond-bool.gif)\n\n\n### ![date](https://raw.github.com/evoluteur/structured-filter/master/screenshots/ft-date.gif) date\n\n- on (eq)\n- not on (ne)\n- after (gt)\n- before (lt)\n- between (bw)\n- not between (nbw)\n- is empty (null)\n- is not empty (nn)\n\n![Date field screenshot](https://raw.github.com/evoluteur/structured-filter/master/screenshots/sf-cond-date.gif)\n\n\n### ![list](https://raw.github.com/evoluteur/structured-filter/master/screenshots/ft-list.gif) list\n\n- any of (in)\n- equal (eq)\n\n![List field screenshot](https://raw.github.com/evoluteur/structured-filter/master/screenshots/sf-cond-list.gif)\n\n\n### ![number](https://raw.github.com/evoluteur/structured-filter/master/screenshots/ft-int.gif) number\n\n- = (eq)\n- != (ne)\n- \u0026gt; (gt)\n- \u0026lt; (lt)\n- is empty (null)\n- is not empty (nn)\n\n![Number field screenshot](https://raw.github.com/evoluteur/structured-filter/master/screenshots/sf-cond-number.gif)\n\n\n### ![text](https://raw.github.com/evoluteur/structured-filter/master/screenshots/ft-txt.gif) text\n\n- equals (eq)\n- not equal (ne)\n- starts with (sw)\n- contains (ct)\n- doesn't contain (nct)\n- finishes with (fw)\n- is empty (null)\n- is not empty (nn)\n\n![Text field screenshot](https://raw.github.com/evoluteur/structured-filter/master/screenshots/sf-cond-text.gif)\n\n### ![time](https://raw.github.com/evoluteur/structured-filter/master/screenshots/ft-time.gif) time\n\n- at (eq)\n- not at (ne)\n- after (gt)\n- before (lt)\n- between (bw)\n- not between (nbw)\n- is empty (null)\n- is not empty (nn)\n\n\n\u003ca name=\"Options\"\u003e\u003c/a\u003e\n## Options\n\nstructured-filter provides several options to customize its behaviour:\n\n### buttonLabels (Boolean)\n\nThe labels of buttons used to manipulate filters. This options applies to the 3 buttons, \"New filter\", \"Add filter\"/\"Update filter\" and \"Cancel\" which use icons if the option is set to false.\n\n```javascript\n$(\"#myFilter\").structFilter({\n    buttonLabels: true\n});\n```\n\nDefaults to *false*.\n\n### dateFormat (String)\n\nThe format for parsed and displayed dates. This attribute is one of the regionalisation attributes.\nCommon formats are: Default - \"mm/dd/yy\", ISO 8601 - \"yy-mm-dd\", Short - \"d M, y\", Medium - \"d MM, y\", Full - \"DD, d MM, yy\". For a full list of the possible formats see the [jQuery formatDate function](http://docs.jquery.com/UI/Datepicker/formatDate).\n\n```javascript\n$(\"#myFilter\").structFilter({\n    dateFormat: \"d M, y\"\n});\n```\n\nDefaults to *\"mm/dd/yy\"*.\n\n### disableOperators (Boolean)\n\nThis option disables operators from conditions. This changes the structure of conditions from \"field-operator-value\" to \"field-value\" which simplifies the backend implementation of filtering.\n\n```javascript\n$(\"#myFilter\").structFilter({\n    disableOperators: true\n});\n```\n\nDefaults to *\"false\"*.\n\n### fields (Array of Fields)\n\nThe list of fields (as an array of objects with id, label and type) to participate in the query definition.\nPossible types are: text, boolean, number, date, time, and list.\n\n```javascript\n$(\"#myFilter\").structFilter({\n    fields: [\n        {id:\"lastname\", type:\"text\", label:\"Lastname\"},\n        {id:\"firstname\", type:\"text\", label:\"Firstname\"},\n        {id:\"active\", type:\"boolean\", label:\"Is active\"},\n        {id:\"age\", type:\"number\", label:\"Age\"},\n        {id:\"bday\", type:\"date\", label:\"Birthday\"},\n        {id:\"category\", type:\"list\", label:\"Category\",\n            list:[\n                {id:\"1\", label:\"Family\"},\n                {id:\"2\", label:\"Friends\"},\n                {id:\"3\", label:\"Business\"},\n                {id:\"4\", label:\"Acquaintances\"},\n                {id:\"5\", label:\"Other\"}\n            ]\n        }\n    ]\n});\n```\n\nDefaults to *[ ]*.\n\n### highlight (Boolean)\n\nA highlight animation performed on the last added or modified filter.\n\n```javascript\n$(\"#myFilter\").structFilter({\n    highlight: false\n});\n```\n\nDefaults to *true*.\n\n### submitButton (Boolean)\n\nShows or hides the \"Submit\" button.\n\n```javascript\n$(\"#myFilter\").structFilter({\n    submitButton: true\n});\n```\n\nDefaults to *false*.\n\n### submitReady (Boolean)\n\nProvides hidden fields with the conditions' values to be submitted with the form (as an alternative to an AJAX call).\n\n```javascript\n$(\"#myFilter\").structFilter({\n    submitReady: true\n});\n```\n\nDefaults to *false*.\n\n\n\u003ca name=\"Methods\"\u003e\u003c/a\u003e\n## Methods\n\n### addCondition(data)\nAdds a new filter condition.\n\n```javascript\n$(\"#myFilter\").structFilter(\"addCondition\", {\n    field:{\n        label: \"Lastname\",\n        value: \"lastname\"\n    },\n    operator:{\n        label: \"starts with\",\n        value: \"sw\"\n    },\n    value:{\n        label: \"\\\"a\\\"\",\n        value: \"a\"\n    }\n});\n```\n\n### clear()\nRemoves all search filters.\n\n```javascript\n$(\"#myFilter\").structFilter(\"clear\");\n```\n\n### length()\nGets the number of filters.\n\n```javascript\n$(\"#myFilter\").structFilter(\"length\");\n```\n\n### removeCondition(index)\nRemoves the condition of the specified index.\n\n```javascript\n$(\"#myFilter\").structFilter(\"removeCondition\", 0);\n```\n\n### val([data])\nGets or sets the filter definition (as an array of filters).\n\n```javascript\n$(\"#myFilter\").structFilter(\"val\");\n\n$(\"#myFilter\").structFilter(\"val\", data);\n```\n\nSample value:\n\n```javascript\n[\n    {\n        field:{\n            label: \"Lastname\",\n            value: \"Lastname\"\n        },\n        operator:{\n            label: \"starts with\",\n            value: \"sw\"\n        },\n        value:{\n            label: \"\\\"jo\\\"\",\n            value: \"jo\"\n        }\n    }\n]\n```\n\n### valText()\nGets the filter definition (as a readable text string).\n\n```javascript\n$(\"#myFilter\").structFilter(\"valText\");\n```\n\nSample value:\n\n    Lastname starts with \"jo\"\n\n### valUrl()\nGets the filter definition (as a URL string).\n\n```javascript\n$(\"#myFilter\").structFilter(\"valUrl\");\n```\n\nSample value:\n\n    filters=1\u0026field-0=Lastname\u0026operator-0=sw\u0026value-0=jo\u0026label=Lastname%20starts%20with%20%22jo%22%0A\n\n\n\u003ca name=\"Events\"\u003e\u003c/a\u003e\n## Events\n\n### change.search\n\nThis event is triggered when the list of search conditions is modified.\n\n```javascript\n$(\"#myFilter\").on(\"change.search\", function(event){\n    // do something\n});\n```\n\n### submit.search\n\nThis event is triggered when the submit button is clicked.\n\n```javascript\n$(\"#myFilter\").on(\"submit.search\", function(event){\n    // do something\n});\n```\n\n\u003ca name=\"Theming\"\u003e\u003c/a\u003e\n## Theming\n\nstructured-filter is as easily themeable as any jQuery UI widget, using one of the [jQuery UI themes](http://jqueryui.com/themeroller/#themeGallery) or your own custom theme made with [Themeroller](http://jqueryui.com/themeroller/).\n\n\n![screenshot themes](https://raw.github.com/evoluteur/structured-filter/master/screenshots/themes.gif)\n\nCSS for themes can be accessed from Google Hosted Libraries.\n\nDark theme (\"ui-darkness\"):\n\n```html\n\u003clink href=\"https://ajax.googleapis.com/ajax/libs/jqueryui/1.13.2/themes/ui-darkness/jquery-ui.css\" rel=\"stylesheet\" type=\"text/css\"\u003e\n```\n\n\nA version of structured-filter for [Bootstrap](http://getbootstrap.com/) and [Backbone.js](http://backbonejs.org/) is available as part of [Evolutility-UI-jQuery](http://evoluteur.github.io/evolutility-ui-jquery/index.html)\nset of [generic views](http://evoluteur.github.io/evolutility-ui-jquery/doc/views.html) for CRUD (Create, Read, Update, Delete) and more.\n\n\nA re-write for React in under construction at [Structured-Filter-React](https://github.com/evoluteur/structured-filter-react).\n\n\nCheck out my other jQuery UI wdget [ColorPicker](https://evoluteur.github.io/colorpicker/).\n\n\u003ca name=\"License\"\u003e\u003c/a\u003e\n## License\n\n\nStructured-Filter is released under the [MIT license](https://github.com/evoluteur/structured-filter/blob/master/LICENSE.md#structured-filter).\n\nCopyright (c) 2024 [Olivier Giulieri](https://evoluteur.github.io/).\n","funding_links":["https://github.com/sponsors/evoluteur"],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevoluteur%2Fstructured-filter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fevoluteur%2Fstructured-filter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fevoluteur%2Fstructured-filter/lists"}