Giter VIP home page Giter VIP logo

evoluteur / structured-filter Goto Github PK

View Code? Open in Web Editor NEW
258.0 18.0 62.0 461 KB

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)"...

Home Page: http://evoluteur.github.io/structured-filter/

License: MIT License

JavaScript 80.50% CSS 7.08% HTML 9.93% Less 2.49%
filter structured-data query-builder searchbar jquery-plugin jquery-ui faceted-search ui widget ui-component

structured-filter's Introduction

Structured-Filter · GitHub license npm version

Structured-Filter is a generic Web UI for building structured search or filter queries.

With it you can build structured search conditions like Firstname 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.

Structured-Filter screenshot

Check the demo for live examples.

Table of Contents

  1. Installation
  2. Usage
  3. Model
  4. Options
  5. Methods
  6. Events
  7. Theming
  8. License

Installation

You can download or fork structured-filter on GitHub.

# To get the latest stable version, use git from the command line.
git clone https://github.com/evoluteur/structured-filter

or install the npm package:

# To get the latest stable version, use npm from the command line.
npm install structured-filter

or install with Bower:

# To get the latest stable version, use Bower from the command line.
bower install structured-filter

# To get the most recent, latest committed-to-master version use:
bower install structured-filter#master

Notes:

  • If you use a version of jQuery-UI smaller than 1.12.1, you must use Structured-Filter version 1.1.0.
  • For React, use Structured-Filter-React.

Usage

First, load jQuery, jQuery UI, and the plugin:

<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js" type="text/javascript" charset="utf-8"></script>
<script src="https://ajax.googleapis.com/ajax/libs/jqueryui/1.13.2/jquery-ui.min.js" type="text/javascript" charset="utf-8"></script>
<script src="js/structured-filter.js" type="text/javascript" charset="utf-8"></script>

The widget requires a jQuery UI theme to be present, as well as its own included base CSS file (structured-filter.css). Here we use the "base" theme as an example:

<link rel="stylesheet" type="text/css" href="https://ajax.googleapis.com/ajax/libs/jqueryui/1.12.1/themes/base/jquery-ui.css">
<link href="css/structured-filter.css" rel="stylesheet" type="text/css">

Now, let's attach it to an existing <div> tag:

<script type="text/javascript">
    $(document).ready(function() {
        $("#myFilter").structFilter({
            fields: [
                {id:"lastname", type:"text", label:"Lastname"},
                {id:"firstname", type:"text", label:"Firstname"},
                {id:"active", type:"boolean", label:"Is active"},
                {id:"age", type:"number", label:"Age"},
                {id:"bday", type:"date", label:"Birthday"},
                {id:"category", type:"list", label:"Category",
                    list:[
                        {id:"1", label:"Family"},
                        {id:"2", label:"Friends"},
                        {id:"3", label:"Business"},
                        {id:"4", label:"Acquaintances"},
                        {id:"5", label:"Other"}
                    ]
                }
            ]
        });
    });
</script>

<div id="myFilter"></div>

This will change the <div> into the widget.

Model

The widget is configured with a list of fields to use in the search conditions.

Fields

Each field must have an ID, a type, and a label.

  • id - unique identifier for the field.
  • label - displayed field name.
  • type - data type. Possible types of field: text, number, boolean, date, time, list.

Fields of type "list" must also have a "list" property for the values (array of objects with id and label).

Example:

fields = [
    {id:"lastname", type:"text", label:"Lastname"},
    {id:"firstname", type:"text", label:"Firstname"},
    {id:"active", type:"boolean", label:"Is active"},
    {id:"age", type:"number", label:"Age"},
    {id:"bday", type:"date", label:"Birthday"},
    {id:"category", type:"list", label:"Category",
        list:[
            {id:"1", label:"Family"},
            {id:"2", label:"Friends"},
            ...
        ]
    }
];

Note: To change the behavior of a "list" field, use the type "list-options" and "list-dropdown" instead of "list".

Conditions

Queries are expressed as a set of conditions.

Each condition is defined by:

  • a field
  • an operator
  • one or several values

For each field the possible operators are determined by it's type.

boolean boolean

  • Yes (1)
  • No (0)

Boolean field screenshot

date date

  • on (eq)
  • not on (ne)
  • after (gt)
  • before (lt)
  • between (bw)
  • not between (nbw)
  • is empty (null)
  • is not empty (nn)

Date field screenshot

list list

  • any of (in)
  • equal (eq)

List field screenshot

number number

  • = (eq)
  • != (ne)
  • > (gt)
  • < (lt)
  • is empty (null)
  • is not empty (nn)

Number field screenshot

text text

  • equals (eq)
  • not equal (ne)
  • starts with (sw)
  • contains (ct)
  • doesn't contain (nct)
  • finishes with (fw)
  • is empty (null)
  • is not empty (nn)

Text field screenshot

time time

  • at (eq)
  • not at (ne)
  • after (gt)
  • before (lt)
  • between (bw)
  • not between (nbw)
  • is empty (null)
  • is not empty (nn)

Options

structured-filter provides several options to customize its behaviour:

buttonLabels (Boolean)

The 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.

$("#myFilter").structFilter({
    buttonLabels: true
});

Defaults to false.

dateFormat (String)

The format for parsed and displayed dates. This attribute is one of the regionalisation attributes. Common 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.

$("#myFilter").structFilter({
    dateFormat: "d M, y"
});

Defaults to "mm/dd/yy".

disableOperators (Boolean)

This 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.

$("#myFilter").structFilter({
    disableOperators: true
});

Defaults to "false".

fields (Array of Fields)

The list of fields (as an array of objects with id, label and type) to participate in the query definition. Possible types are: text, boolean, number, date, time, and list.

$("#myFilter").structFilter({
    fields: [
        {id:"lastname", type:"text", label:"Lastname"},
        {id:"firstname", type:"text", label:"Firstname"},
        {id:"active", type:"boolean", label:"Is active"},
        {id:"age", type:"number", label:"Age"},
        {id:"bday", type:"date", label:"Birthday"},
        {id:"category", type:"list", label:"Category",
            list:[
                {id:"1", label:"Family"},
                {id:"2", label:"Friends"},
                {id:"3", label:"Business"},
                {id:"4", label:"Acquaintances"},
                {id:"5", label:"Other"}
            ]
        }
    ]
});

Defaults to [ ].

highlight (Boolean)

A highlight animation performed on the last added or modified filter.

$("#myFilter").structFilter({
    highlight: false
});

Defaults to true.

submitButton (Boolean)

Shows or hides the "Submit" button.

$("#myFilter").structFilter({
    submitButton: true
});

Defaults to false.

submitReady (Boolean)

Provides hidden fields with the conditions' values to be submitted with the form (as an alternative to an AJAX call).

$("#myFilter").structFilter({
    submitReady: true
});

Defaults to false.

Methods

addCondition(data)

Adds a new filter condition.

$("#myFilter").structFilter("addCondition", {
    field:{
        label: "Lastname",
        value: "lastname"
    },
    operator:{
        label: "starts with",
        value: "sw"
    },
    value:{
        label: "\"a\"",
        value: "a"
    }
});

clear()

Removes all search filters.

$("#myFilter").structFilter("clear");

length()

Gets the number of filters.

$("#myFilter").structFilter("length");

removeCondition(index)

Removes the condition of the specified index.

$("#myFilter").structFilter("removeCondition", 0);

val([data])

Gets or sets the filter definition (as an array of filters).

$("#myFilter").structFilter("val");

$("#myFilter").structFilter("val", data);

Sample value:

[
    {
        field:{
            label: "Lastname",
            value: "Lastname"
        },
        operator:{
            label: "starts with",
            value: "sw"
        },
        value:{
            label: "\"jo\"",
            value: "jo"
        }
    }
]

valText()

Gets the filter definition (as a readable text string).

$("#myFilter").structFilter("valText");

Sample value:

Lastname starts with "jo"

valUrl()

Gets the filter definition (as a URL string).

$("#myFilter").structFilter("valUrl");

Sample value:

filters=1&field-0=Lastname&operator-0=sw&value-0=jo&label=Lastname%20starts%20with%20%22jo%22%0A

Events

change.search

This event is triggered when the list of search conditions is modified.

$("#myFilter").on("change.search", function(event){
    // do something
});

submit.search

This event is triggered when the submit button is clicked.

$("#myFilter").on("submit.search", function(event){
    // do something
});

Theming

structured-filter is as easily themeable as any jQuery UI widget, using one of the jQuery UI themes or your own custom theme made with Themeroller.

screenshot themes

CSS for themes can be accessed from Google Hosted Libraries.

Dark theme ("ui-darkness"):

<link href="https://ajax.googleapis.com/ajax/libs/jqueryui/1.13.2/themes/ui-darkness/jquery-ui.css" rel="stylesheet" type="text/css">

A version of structured-filter for Bootstrap and Backbone.js is available as part of Evolutility-UI-jQuery set of generic views for CRUD (Create, Read, Update, Delete) and more.

A re-write for React in under construction at Structured-Filter-React.

Check out my other jQuery UI wdget ColorPicker.

License

Structured-Filter is released under the MIT license.

Copyright (c) 2024 Olivier Giulieri.

structured-filter's People

Contributors

evoluteur avatar larskoeie avatar roomthirteen avatar struiling avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

structured-filter's Issues

Exclusive list

It would be nice to have a list but with radio buttons so only one option is ever selected.

Perhaps:

{ type: "exclusiveList", id: "myID", label: "Fancy Exclusive List", list: [
  {id: "opt1", label: "First Option"},
  {id: "opt2", label: "Second Option"},
  {id: "opt3", label: "Third Option"}
]}

And then

case fTypes.exculsiveList:
  var arrayLength = this._field.list.length;
  h+='<span id="value">';
  for (var i = 0; i < arrayLength; i++) {
    h+= EvoUI.inputRadio(this._field.list[i].label, this._field.list[i].id, this._field.list[i].label, v==this._field.list[i].id, 'value' + this._field.list[i].id);
  }
  h +='</span>';
  break;

Haven't looked too deeply into this, I know there would need to be a few more changes to bring this in.

issue while retrieving value from structured-filter

I am integrating this component, and after filter changed or submit i am posting those values to some link...
while retrieving value from component i am getting some issue..
Please help me where i doing worng

adding error stack
(index):48 Uncaught TypeError: $(...).structFilter is not a function
at updateValue ((index):48)
at HTMLDivElement. ((index):95)
at HTMLDivElement.dispatch (jquery.min.js:3)
at HTMLDivElement.q.handle (jquery.min.js:3)
at Object.trigger (jquery.min.js:4)
at HTMLDivElement. (jquery.min.js:4)
at Function.each (jquery.min.js:2)
at r.fn.init.each (jquery.min.js:2)
at r.fn.init.trigger (jquery.min.js:4)
at t.(:8570/anonymous function).(anonymous function)._triggerChange (http://localhost:8570/Scripts/structured-filter.js:599:16)
updateValue @ (index):48
(anonymous) @ (index):95
dispatch @ jquery.min.js:3
q.handle @ jquery.min.js:3
trigger @ jquery.min.js:4
(anonymous) @ jquery.min.js:4
each @ jquery.min.js:2
each @ jquery.min.js:2
trigger @ jquery.min.js:4
_triggerChange @ structured-filter.js:599
(anonymous) @ jquery-ui.min.js:6
addCondition @ structured-filter.js:264
(anonymous) @ jquery-ui.min.js:6
(anonymous) @ structured-filter.js:144
dispatch @ jquery.min.js:3
q.handle @ jquery.min.js:3

image

Dropdown select filter

It would be nice to give a predefined list of values for a filter. For example, if the data that was being queried only had X options for a field, would be nice to show all of them and let the user select the one they wanted. Would use less screen space than a normal list of say 10 options, though would be limited to only one option?

Perhaps:

{ type: "selectList", id: "myID", label: "Birthmonth", list: [
  {id: "jan", label: "January"},
  {id: "feb", label: "February"},
  {id: "mar", label: "March"},
  {id: "apr", label: "April"},
  {id: "may", label: "May"},
  {id: "jun", label: "June"},
  {id: "jul", label: "July"},
  {id: "aug", label: "August"},
  {id: "sep", label: "September"},
  {id: "oct", label: "October"},
  {id: "nov", label: "November"},
  {id: "dec", label: "December"}
]}

and then:

case fTypes.selectList:
  var arrayLength = this._field.list.length;
  h+='<select id="value">'+EvoUI.optNull;
  for (var i = 0; i < arrayLength; i++) {
    h+=EvoUI.inputOption(this._field.list[i].id, this._field.list[i].label);
  }
  h+='</select>';
  break;

just a rough sketch of a possible way?

relative date option

It will be better if there is option relative date inside date field. I have shared sample screen link below please check it
filter-relative

Disable operators

In options array

 disableOperators: false

In _setEditorOperator method at the begin

if(this.options.disableOperators) {
        this._step=2;
        return this._setEditorValue();
}

Restore filter from valUrl

I get the filter url:
let filterUrlFormat = $('#sonarioFilter').structFilter('valUrl');

Then I try to set the filter, but it fails to do anything:
$('#sonarioFilter').structFilter('valUrl',"filters=1&field-0=Gender&operator-0=eq&value-0=male&label=Gender%20equals%20%22male%22%20");

Is there something I'm missing?

Remove issue

Remove from X button not trigger change.search.

can't get the remove icon to show

hello,
thanks for the nice code, but I'm having a problem showing the x icon to remove the a single filter
i'm using bootstrap 3.3.7 and a custom jquery-ui theme for bootstrap

Perfomance on firefox

Hello I am using this plugin but seems like it gets really slow when adding/removing filters even in the demo page. Do you have any idea why it becomes slow on firefox?

Auto Complete for all dropdowns

Feature Request:

It will be a very useful feature if we can provide autocomplete by typing in the dropdowns.

So that user doesn't have to find from dropdown.

Minor functionality broken with JQuery UI 1.12.1

Noticed the following behavior when JQuery UI 1.12.1 was used alongside this plugin:

  • Close button/icon inside a filtering box (which is intended to remove the filter object from the list) does not remove the item, and instead opens it for editing

  • Text description of filtering behaves oddly when being edited after initial creation. Would end up with odd strings like "Room does not contain 'a' does not contain 'b' does not contain 'c'"

Excellent plugin btw.

Run time add new fields in structFilter

It's possible to add new fields object { id: "FieldID", type: "text", label: "FieldLabel" } in existing
structFilter.

$("#myFilter").structFilter({
fields: [
{type:"text", id:"lastname", label:"Lastname"},
{type:"text", id:"firstname", label:"Firstname"},
]
});

Collision with Bootstrap Javascript

The css for structured-filter does not work if used with bootstrap.

The offender is not in the css, but in the javascript. To reproduce the problem, simply add the following,

    <link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/bootstrap/3.3.6/css/bootstrap.min.css">

    <script src="//maxcdn.bootstrapcdn.com/bootstrap/3.3.6/js/bootstrap.min.js"></script>

Then lower the jquery version to something under version 3, which bootstrap doesn't like. Then the styling will go away.

It only occurs when the .js is there, removing the bootstrap css and leaving the js causes the problem.

Can't get widget display to use the icons

I'm very interested in using this package,but I am having difficulty getting the widget display right.
I'm using jQuery 2.2.4, jQuery-ui 1.12.1.

I'm following the installation instructions per the documentation. I am attempting to use this in a Flask application that uses Jinja templating and bootstrap 3.Rather than getting the nice looking display in the demo, I am getting text rather than the icons, an unappealing looking filter list, and the filter list has no way to remove a filter. In short, the icons and attractive theming is not rendering. I've even tried explicitly setting the buttonLabels option to false.

... <script src="/static/js/jquery-2.2.4.js"></script> <script src="/static/jquery-ui-1.2.1/jquery-ui.js"></script> <script src="/static/bootstrap-3.3.7/dist/js/bootstrap.js" crossorigin="anonymous"></script> <script src="/static/structured-filter-master/js/structured-filter.js"></script>

Can you assist? Thank you

Custom OR logic?

It would be awesome if I could do filtering like this:
{
{Username contains 'asdf' AND Lastname contains 'foo'}
OR
{Username startswith 'A' and age < 13}
}

This way a lot more flexible queries could be built

Filrer as OData query

Hi there, first of all thank You for such great project. I'm wondering if it is possible to create OData query from filter build with Your builder.
I'd like to use Your builder to create filter that could be send to OData endpoint.

Not Between

Another small enhancement could be to add an option for "not between" (nbw). I think it is just about as simple as adding the label, API, and adding it to the validation of sBetween?

It could also be nice to enable between and not between for numbers (though this is already possible by doing both a greater than and a less than filter)

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.