jui_filter_rules Documentation

jui_filter_rules is a jQuery plugin, useful to create or set filter rules as JSON object and get the relevant WHERE SQL.

As a javascript control, it can be integrated with any server-side technology (e.g. PHP, Perl, ASP, JSP and more) and any Database.

A helper PHP jui_filter_rules class is available. It can parse rules to SQL, supporting: "MYSQLi" and "POSTGRES".

Compatible with modern web browsers. Tested with: Google Chrome, Mozilla Firefox, Microsoft Internet Explorer >= 8, (default) Android browser.

PROJECT HOME: https://labs.pontikis.net/jui_filter_rules

DEMO: https://labs.pontikis.net/jui_filter_rules/demo

DOCUMENTATION: https://labs.pontikis.net/jui_filter_rules/docs

SUPPORT FORUM: https://www.pontikis.net/bbs

SOURCE REPOSITORY: https://github.com/pontikis/jui_filter_rules

JQUERY PLUGIN REGISTRY: https://plugins.jquery.com/jui_filter_rules/

NuGet GALLERY: https://nuget.org/packages/jui_filter_rules/

Copyright © Christos Pontikis https://www.pontikis.net

License MIT

Requires

• jquery
• jquery-ui (if jquery ui widgets are in use)
• moment.js library (for datetime validation)

NOTE: moment.js and jquery-ui are not required but highly recommended for full functionality (date validation and rich interface).

Tested with jquery >= 1.8.2 and >= jquery-ui 1.8.23 (recommended jquery-ui >= 1.9)

Current Release 1.0.5 (27 May 2014) Download here.

CHANGELOG here.

Features

• Create rules as JSON object
• Create 'WHERE SQL' parsing rules JSON object using Prepared Statements or not (available for php)
• Set rules from JSON object
• Fully configurable
• Support nested filter groups
• Restrict operators per filter
• Filter types
  • text
  • number
  • date
• Supported form elements
  • input (text, radio, checkbox). At least one checkbox or radio must be checked (single checkbox interface is not supported at this time).
  • select
• Supported widgets:
  • jquery ui datepicker and timepicker (by Trent Richardson)
  • jquery ui autocomplete
  • jquery ui slider
  • jquery ui spinner (jqueru ui >= 1.9)
• Filter default value supported
• Filter value validation ('numeric' using jquery $.isNumeric and 'date' using moment.js library)
• Filter value conversion using javascript (or server side) function
• Localization

How to use jui_filter_rules to create Rules

1. Include jui_filter_rules css, js and localization file in head section of your page. See code examples. There are two CSS. Use jquery.jui_filter_rules.bs.min.css for Bootstrap and jquery.jui_filter_rules.min.css anywhere else.

   If you use simple controls in filters (e.g. common input, select etc) you don't need something else. But if you use complex widgets (e.g. autocomplete, datepicker etc) you have to include their css or js files.

2. Create a div in your page, where you want jui_filter_rules to render and give it an ID (e.g. myfilters )
3. In your javascript code, add

   $("#myfilters").jui_filter_rules({
   	// your options here - see below or code examples
   })
   

4. After you create your query, get the rules in JSON format using getRules method

   $("#myfilters").jui_filter_rules('getRules', 0, []);
   

   In order to get the WHERE SQL from JSON you have to create a server-side script to parse JSON object. You may use any server-side technology to create this ajax script. If your web server runs PHP, you may use the PHP class jui_filter_rules.php. It uses Da Capo database wrapper, which you can get from Github.

How to use jui_filter_rules to set Rules

If you define filter_rules option, jui_filter_rules will display default filters on startup.

You can also apply a filter_rules set, using method setRules. See code examples.

$("#myfilters").jui_filter_rules('setRules', a_rules);

To set rules, use the JSON format, which is returned from getRules. Additional options:

• autocomplete_value to define jquery ui autocomplete text input value
• slider_value to define jquery ui slider value

See code examples for details.

Example of Rules returned (JSON)

    [
        {
            "element_rule_id": "rule_demo_rules1_1",
            "condition": {
                "filterType": "text",
                "field": "lastname",
                "operator": "equal",
                "filterValue": [
                    "Smith"
                ]
            },
            "logical_operator": "AND"
        },
        {
            "element_rule_id": "rule_demo_rules1_2",
            "condition": {
                "filterType": "number",
                "field": "age",
                "operator": "less",
                "filterValue": [
                    "60"
                ]
            },
            "logical_operator": "AND"
        },
        {
            "condition": [
                {
                    "element_rule_id": "rule_demo_rules1_3",
                    "condition": {
                        "filterType": "date",
                        "field": "date_updated",
                        "operator": "greater",
                        "filterValue": [
                            "20121212122920"
                        ]
                    },
                    "logical_operator": "OR"
                },
                {
                    "element_rule_id": "rule_demo_rules1_4",
                    "condition": {
                        "filterType": "date",
                        "field": "date_updated",
                        "operator": "less_or_equal",
                        "filterValue": [
                            "20100510082929"
                        ]
                    },
                    "logical_operator": "OR"
                }
            ],
            "logical_operator": "AND"
        }
    ]
    

Supported Filter types and Operators

var filter_types = [
    "text",
    "number",
    "date"
], operators = [
    {type: "equal", accept_values: "yes", apply_to: ["text", "number", "date"], group: "equality"},
    {type: "not_equal", accept_values: "yes", apply_to: ["text", "number", "date"], group: "equality"},
    {type: "in", accept_values: "yes", apply_to: ["text", "number", "date"], group: "multiple_choice"},
    {type: "not_in", accept_values: "yes", apply_to: ["text", "number", "date"], group: "multiple_choice"},
    {type: "less", accept_values: "yes", apply_to: ["number", "date"], group: "inequality"},
    {type: "less_or_equal", accept_values: "yes", apply_to: ["number", "date"], group: "inequality"},
    {type: "greater", accept_values: "yes", apply_to: ["number", "date"], group: "inequality"},
    {type: "greater_or_equal", accept_values: "yes", apply_to: ["number", "date"], group: "inequality"},
    {type: "begins_with", accept_values: "yes", apply_to: ["text"], group: "substring"},
    {type: "not_begins_with", accept_values: "yes", apply_to: ["text"], group: "substring"},
    {type: "contains", accept_values: "yes", apply_to: ["text"], group: "substring"},
    {type: "not_contains", accept_values: "yes", apply_to: ["text"], group: "substring"},
    {type: "ends_with", accept_values: "yes", apply_to: ["text"], group: "substring"},
    {type: "not_ends_with", accept_values: "yes", apply_to: ["text"], group: "substring"},
    {type: "is_empty", accept_values: "no", apply_to: ["text"], group: "empty_string"},
    {type: "is_not_empty", accept_values: "no", apply_to: ["text"], group: "empty_string"},
    {type: "is_null", accept_values: "no", apply_to: ["text", "number", "date"], group: "null"},
    {type: "is_not_null", accept_values: "no", apply_to: ["text", "number", "date"], group: "null"}
];

Filter options synopsis

    filter_template: [
        {
            filterName: "Lastname", "filterType": "text", field: "lastname", filterLabel: "Last name",
            excluded_operators: ["in", "not_in"],
            filter_interface: [
                {
                    filter_element: "input",
                    filter_element_attributes: { // id, name will be ignored. At no text type input, value, checked, selected will also be ignored)
                        type: "text",
                        "class": "test1"
                    },
                    vertical_orientation: "no", // useful for checkbox or radio groups
                    filter_widget: "datepicker",
                    filter_widget_properties: {
                        dateFormat: "yy-mm-dd",
                        changeMonth: true,
                        changeYear: true
                    },
                    returns_no_value: "no"
                }
            ],
            lookup_values: [
                {lk_option: "Level1", lk_value: "1"},
                {lk_option: "Level2", lk_value: "2"},
                {lk_option: "Level3", lk_value: "3", lk_selected: "yes"}
            ],
            lookup_values_ajax_url: "",
            validate_dateformat: ["DD/MM/YYYY"], // date validation using momentjs.com
            filter_value_conversion: {
                function_name: "user javascript function",
                args: [obj_arg1, obj_arg2, obj_argn]
            },
            filter_value_conversion_server_side: {
                function_name: "user function executed on server",
                args: [obj_arg1, obj_arg2, obj_argn]
            }
        }
    ];
    

Remarks

• If you don't specify filter_inteface, default filter inteface is applied:

filter_interface: [
	{
		filter_element: "input",
		filter_element_attributes: {type: "text"}
	}
]

• If you don't specify filter_element_attributes, default filter_element_attributes is applied: {}

User functions (filter value conversion)

Use can set custom functions for filter value conversion either javascript or server side functions.

Arguments can be passed as an array of objects. Each argument object can contain:

• a direct value: {"value": "DD/MM/YYYY"}
• or the filter value: {"filter_value": "yes"}

Example of javascript user function

        filterName: "DateUpdated", "filterType": "date", field: "date_updated", filterLabel: "Datetime updated",
        ...
        filter_value_conversion: {
            function_name: "local_datetime_to_UTC_timestamp",
            args: [
                {"filter_value": "yes"},
                {"value": "DD/MM/YYYY HH:mm:ss"}
            ]
        }
    }
        

Example of server-side user function

        {
            filterName: "DateInserted", "filterType": "date", field: "date_inserted", filterLabel: "Date inserted",
            ...
            filter_value_conversion_server_side: {
                function_name: "date_encode",
                args: [
                    {"filter_value": "yes"},
                    {"value": "d/m/Y"}
                ]
            }
        }
        

Options

$("#element_id").jui_filter_rules({

	filters: [],

	filter_rules: [],

	decimal_separator: ".",
	htmlentities: false,

	// styles
	bootstrap_version: false,

	containerClass: "filter_rules_container",

	rulesGroupContainerClass: "rules_group_container",
	rulesGroupHeaderClass: "rules_group_header",
	rulesGroupBodyClass: "rules_group_body",

	rulesGroupConditionContainerClass: "rules_group_condition_container",
	rulesGroupConditionListClass: "rules_group_condition_list",

	rulesGroupToolsContainerClass: "rules_group_tools_container",
	rulesGroupToolsListClass: "rules_group_tools_list",

	rulesListClass: "rules_list",
	rulesListLiClass: "rules_list_li",
	rulesListLiErrorClass: "rules_list_error_li",
	rulesListLiAppliedClass: "rules_list_applied_li",

	filterContainerClass: "filter_container",
	filterListClass: "filter_list",

	operatorsListContainerClass: "operators_list_container",
	operatorsListClass: "operators_list",

	filterValueContainerClass: "filter_value_container",
	filterInputTextClass: "filter_input_text",
	filterInputNumberClass: "filter_input_number",
	filterInputDateClass: "filter_input_date",
	filterInputCheckboxClass: "filter_input_checkbox",
	filterInputRadioClass: "filter_input_radio",
	filterSelectClass: "filter_select",

	filterGroupListClass: "filter_group_list",
	filterGroupListItemHorizontalClass: "filter_group_list_item_horizontal",
	filterGroupListItemVerticalClass: "filter_group_list_item_vertical",

	ruleToolsContainerClass: "rule_tools_container",
	ruleToolsClass: "rule_tools_list",

	noFiltersFoundClass: "no_filters_found",

	// elements id prefix
	group_dl_id_prefix: "group_",
	group_condition_id_prefix: "group_cond_",
	group_tools_id_prefix: "group_tools_",
	rule_li_id_prefix: "rule_",
	filters_list_id_prefix: "filters_list_",
	operators_container_id_prefix: "oper_wrap_",
	operators_list_id_prefix: "oper_list_",
	filter_value_container_id_prefix: "flt_wrap_",
	filter_element_id_prefix: "flt_",
	filter_element_name_prefix: "flt_name_",
	rule_tools_id_prefix: "rule_tools_",

	// events
	onSetRules: function() {
	},
	onValidationError: function() {
	}

});

Methods

getDefaults

    $("#element_id").jui_filter_rules('getDefaults');
    

getOption

    $("#element_id").jui_filter_rules('getOption', 'option_name');
    

getAllOptions

    $("#element_id").jui_filter_rules('getAllOptions');
    

setOption

    $("#element_id").jui_filter_rules('setOption', 'option_name', option_value, reinit);
    

    $("#element_id").jui_filter_rules({option1_name: option1_value, etc});
    

refresh

    $("#element_id").jui_filter_rules('refresh');
    

destroy

    $("#element_id").jui_filter_rules('destroy');
    

getRules

    $("#element_id").jui_filter_rules('getRules', 0, []);
    

setRules

    $("#element_id").jui_filter_rules('setRules', a_rules);
    

markRuleAsApplied

    $("#element_id").jui_filter_rules('markAllRulesAsApplied', 'rule_element_id', true);
    

markRuleAsError

    $("#element_id").jui_filter_rules('markRuleAsError', 'rule_element_id', true);
    

markRuleAsPending

    $("#element_id").jui_filter_rules('markRuleAsPending', 'rule_element_id');
    

markAllRulesAsApplied

    $("#element_id").jui_filter_rules('markAllRulesAsApplied');
    

clearAllRules

    $("#element_id").jui_filter_rules('clearAllRules');
    

Events

onSetRules

    $("#element_id").jui_filter_rules({
        onSetRules: function() {
			// your code here
        }
    });
    

onValidationError

    $("#element_id").jui_filter_rules({
        onValidationError: function(event, data) {
            alert(data["err_description"] + ' (' + data["err_code"] + ')');
            data.elem_filter.focus();
        }
    });
    

data is an object:

    {
        err_code: 'err_code',
        err_description: 'description',
        elem_filter: 'the filter element as jquery object' // optional
    }