Repository is archived
No commit activity in last 3 years
No release in over 3 years
A great and easy visual condition builder to your rails project
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Runtime

< 6, >= 3
 Project Readme

Visual Condition Builder

A great and easy condition builder to your rails project

How to install

Add it to your Gemfile:

gem 'visual_condition_builder'

Run the following command to install it:

$ bundle install
$ rails generate visual_condition_builder:install

Add it to your app/assets/stylesheets/application.css

*= require visual_condition_builder

Add it to your app/assets/javascripts/application.js

//= require visual_condition_builder

Dependency

To work properly, the builder needs your project to have:

  • jQuery

The builder already has some plugins that can conflict with your current plugins:

Select2 Languages

Select2 supports multiple languages by simply including the right language JS file (visual_condition_builder/select2_i18n/it, visual_condition_builder/select2_i18n/pt-BR, etc.) after visual_condition_builder in your application.js

//= require visual_condition_builder/select2_i18n/en
//= require visual_condition_builder/select2_i18n/pt-BR

Dictionaries

The condition builder information is based on a dictionary, so you need to create your dictionaries as needed.

To generate the dictionary structure run:

$ rails g visual_condition_builder:dictionary example

Will be created a file app/condition_dictionaries/example_dictionary.rb:

class ExampleDictionary < VisualConditionBuilder::Dictionary

  dictionary do
    param :name
  end

end

You can create multiple contexts for a dictionary, so give it a name:

  dictionary :simple do
    param :name
  end
  
  dictionary :complex do
    param :first_name
    param :last_name
  end

Params

You have no restrictions on the use of parameters, they have no binding with models or any element of the application. You can pass arguments to customize how the condition generator will be created:

  dictionary do
    param :name, type: 'STRING', operators: [:eq]
    param :created_at, type: 'DATE', operators: [{operator: 'eq', label: 'Equal', multiple: true, no_value: false}]
    param :updated_at, type: 'DATE', operators: [{operator: 'between', label: 'Between ... and ...', multiple: 2, no_value: false}]
    param :today, type: 'DATE', operators: [{operator: 'eq', label: 'Equal', multiple: false, no_value: true}]
  end

See below all the arguments you can use:

Param Description
label Label of the field, if not informed, will search in the visual_condition_builder.*.yml. (default: param name)
type Type of the field. Responsible for defining how the values will be inserted (DatePicker, Numeric Mask, ...)
operators Defines which operators you want to use, if not informed, the default operators will be used
values Sets the default values for this field, restricting the user to those values.
group Creates a separation in the field list by grouping the fields with this group

By default, the condition builder implements some operators and arguments, allowing you to enter only the operator name, like: operators: [:eq, :between] You can also inform operators: [] to hide operator's box.

List of default operators:

Operator Description Default Arguments
between Between .. e .. multiple: 2
today Today(date) no_value: true
yesterday Yesterday(date) no_value: true
tomorrow Tomorrow(date) no_value: true
this_week First day of Current Week .. Last day of Current Week no_value: true
last_week First day of Last Week .. Last day of Last Week no_value: true
next_week First day of Next Week .. Last day of Next Week no_value: true
eq Is exactly equal to a given value multiple: false
not_eq Opposite :eq multiple: false
matches Is like a given value multiple: false
does_not_match Opposite :matches multiple: false
lt is less than a given value multiple: false
gt is greater than a given value multiple: false
lteq is less than or equal to a given value multiple: false
gteq is greater than or equal to a given value multiple: false
in is within a specified list multiple: true
not_in Opposite :in multiple: true
cont contains a given value multiple: false
not_cont Opposite :not_cont multiple: false
cont_any contains any of the given values multiple: true
not_cont_any Opposite :cont_any multiple: true
cont_all contains all of the given values multiple: true
not_cont_all Opposite :cont_all multiple: true
start begins with a given value multiple: false
not_start Opposite :start multiple: false
end ends with a given value multiple: false
not_end Opposite :end multiple: false
true where a field is true no_value: true, multiple: false
not_true Opposite :true no_value: true, multiple: false
false where a field is false no_value: true, multiple: false
not_false Opposite :false no_value: true, multiple: false
present where a field is present no_value: true, multiple: false
not_present where a field is not present no_value: true, multiple: false
blank where a field is blank no_value: true, multiple: false
null where a field is null no_value: true, multiple: false
not_null Opposite :null no_value: true, multiple: false

if you dont fill the operators, the builder will use the operators by field type. If a type is not informed, it will be considered STRING

Type Default Operators
DATE, DATETIME eq, between, today, yesterday, tomorrow, this_week, last_week, next_week, present, blank
TIME eq, between, present, blank
DECIMAL, INTEGER eq, between
STRING cont, eq, start, end, present, blank
... eq

The values parameter must be informed to the constructor so the user can make a selection between them.

  dictionary do
    param :status, values: [{id: 1, label: 'Active', id: 2, label: 'Inactive'}]
    param :status_list, values: MyStatus.all.dictionary_values(:code, :title)
    param :status_proc, values: -> { current_user.get_status }
    param :status_ajax, values: -> { ajax_my_status_path }
  end

In all the above examples the result must always follow the structure:

[
    {id: 1, label: 'Example'},
    {id: 2, label: 'Example 2'},
    {id: 'A', label: 'Example 3'},
    {id: 'Text', label: 'My Text'}
]

When using an AJAX call, the condition generator will make requests by passing two types of parameters: ** init ** or ** key **:

  • init - is the parameter with the initial value of the list. When the plugin tries to load the list it should show an initial value before the search made by the user, so this initial value must be returned through the parameter init
  • key - is the parameter with the value entered by the user to return the values from the list.

The return must follow the standard dictionary value structure and return in JSON format. Example of a controller that implements this function:

class CitiesController < ApplicationController
  def ajax
    if params[:init]
      @cities = City.where(id: params[:init])
    else
      @cities = City.where('cities.name LIKE ?', "%#{params[:key]}%").order(:name).limit(100)
    end
    render json: @cities.select('cities.id, cities.name AS label').to_json
  end
end

Methods

Dictionary Class have public methods to get informations about self:

  • fields(dictionary_context_name)
  • dictionary(dictionary_context_name)
  • dictionary(dictionary_context_name, rails_request)
  • dictionaries
#example_dictionary.rb
class ExampleDictionary < VisualConditionBuilder::Dictionary

  dictionary do
    param :name
  end

  dictionary :complex do
    param :name
    param :age
  end
  
  dictionary :app_request do
    param :cities, values: -> { ajax_cities_path }
  end

end

#rails console
ExampleDictionary.fields
# =>  {:name=>{:label=>"Name", :type=>"STRING"}}

ExampleDictionary.fields(:complex)
# =>  {:name=>{:label=>"Name", :type=>"STRING"}, :age=>{:label=>"Age", :type=>"STRING"}}

ExampleDictionary.dictionary
# =>  [{:type=>"STRING", :operators=>[{:operator=>:cont, :multiple=>false, :no_value=>false, :label=>"Contém"}, {:operator=>:eq, :multiple=>false, :no_value=>false, :label=>"Igual"}, {:operator=>:start, :multiple=>false, :no_value=>false, :label=>"Começa com"}, {:operator=>:end, :multiple=>false, :no_value=>false, :label=>"Termina com"}, {:operator=>:present, :no_value=>true, :multiple=>false, :label=>"Presente"}, {:operator=>:blank, :no_value=>true, :multiple=>false, :label=>"Não Presente"}], :values=>[], :group=>"", :label=>"Name", :field=>:name}]

ExampleDictionary.dictionary(:complex)
# =>  [{:type=>"STRING", :operators=>[{:operator=>:cont, :multiple=>false, :no_value=>false, :label=>"Contém"}, {:operator=>:eq, :multiple=>false, :no_value=>false, :label=>"Igual"}, {:operator=>:start, :multiple=>false, :no_value=>false, :label=>"Começa com"}, {:operator=>:end, :multiple=>false, :no_value=>false, :label=>"Termina com"}, {:operator=>:present, :no_value=>true, :multiple=>false, :label=>"Presente"}, {:operator=>:blank, :no_value=>true, :multiple=>false, :label=>"Não Presente"}], :values=>[], :group=>"", :label=>"Name", :field=>:name}, {:type=>"STRING", :operators=>[{:operator=>:cont, :multiple=>false, :no_value=>false, :label=>"Contém"}, {:operator=>:eq, :multiple=>false, :no_value=>false, :label=>"Igual"}, {:operator=>:start, :multiple=>false, :no_value=>false, :label=>"Começa com"}, {:operator=>:end, :multiple=>false, :no_value=>false, :label=>"Termina com"}, {:operator=>:present, :no_value=>true, :multiple=>false, :label=>"Presente"}, {:operator=>:blank, :no_value=>true, :multiple=>false, :label=>"Não Presente"}], :values=>[], :group=>"", :label=>"Age", :field=>:age}] 

ExampleDictionary.dictionaries
# =>  {:default=>[{:type=>"STRING", :operators=>[{:operator=>:cont, :multiple=>false, :no_value=>false, :label=>"Contém"}, {:operator=>:eq, :multiple=>false, :no_value=>false, :label=>"Igual"}, {:operator=>:start, :multiple=>false, :no_value=>false, :label=>"Começa com"}, {:operator=>:end, :multiple=>false, :no_value=>false, :label=>"Termina com"}, {:operator=>:present, :no_value=>true, :multiple=>false, :label=>"Presente"}, {:operator=>:blank, :no_value=>true, :multiple=>false, :label=>"Não Presente"}], :values=>[], :group=>"", :label=>"Name", :field=>:name}], :padrao=>[{:type=>"STRING", :operators=>[{:operator=>:cont, :multiple=>false, :no_value=>false, :label=>"Contém"}, {:operator=>:eq, :multiple=>false, :no_value=>false, :label=>"Igual"}, {:operator=>:start, :multiple=>false, :no_value=>false, :label=>"Começa com"}, {:operator=>:end, :multiple=>false, :no_value=>false, :label=>"Termina com"}, {:operator=>:present, :no_value=>true, :multiple=>false, :label=>"Presente"}, {:operator=>:blank, :no_value=>true, :multiple=>false, :label=>"Não Presente"}], :values=>[], :group=>"", :label=>"Name", :field=>:name}, {:type=>"STRING", :operators=>[{:operator=>:cont, :multiple=>false, :no_value=>false, :label=>"Contém"}, {:operator=>:eq, :multiple=>false, :no_value=>false, :label=>"Igual"}, {:operator=>:start, :multiple=>false, :no_value=>false, :label=>"Começa com"}, {:operator=>:end, :multiple=>false, :no_value=>false, :label=>"Termina com"}, {:operator=>:present, :no_value=>true, :multiple=>false, :label=>"Presente"}, {:operator=>:blank, :no_value=>true, :multiple=>false, :label=>"Não Presente"}], :values=>[], :group=>"", :label=>"Age", :field=>:age}]}

ExampleDictionary.dictionary(:app_request)
# => [{:values=>#<Proc:0x00000008ddffb0@/path_to_project/app/condition_dictionaries/example_dictionary.rb:12 (lambda)>, :type=>"STRING", ...

ExampleDictionary.dictionary(:app_request, rails_app_request)
# =>  [{:values=>"/cities/ajax", :type=>"STRING", ...

Helpers

(class) dictionary_values(param_id, param_label)

It should be used in objects of type: Array or ActiveRecord::Relation, the first parameter is id and the second is label for the dictionary

dictionary do
  param :book_id, values: Book.all.dictionary_values(:code, :title)
  #MyService.myarray = [['Active','1'], ['Inactive','2'], ['Blocked','3']] 
  param :status, values: MyService.myarray.dictionary_values(1, 0)
end

(view) conditions_fields(name_of_dictionary)

Creates a field selector in a dropdown element (bootstrap).

= conditions_fields :example
-# with context:
= conditions_fields({:dictionary_name => :context_name})

You can create the list item manually ExampleDictionary.fields (dictionary_name) (example_dictionary.rb), you must have 'clickable' elements with an add-condition-field class and data-field: field_name attribute

%a.add-condition-field{href: '#', data: {field: 'name'}} Name
%a.add-condition-field{href: '#', data: {field: 'age'}} Age
%a.add-condition-field{href: '#', data: {field: 'example'}} Example Field

(view) build_conditions(name_of_dictionary, *arguments)

How create condition builder in you view:

= form_tag my_controller_path, method: :get do
    -# condition builder don't create input field with values, create it:
    = hidden_field_tag('my_conditions', @example_conditions.to_json)
    -# DropDown with fields
    = conditions_fields :example
    -# Conditions Element
    = build_conditions :example, input: '#my_conditions', select2Config: {allowClear: true}

Default element id: dictionary_name + context_name + condition_container: example_default_condition_container

To create based on a specific context dictionary use:

= build_conditions({:dictionary_name => :context_name}, input: '#my_conditions', select2Config: {allowClear: true})

Its possible change conditions_fields title:

= conditions_fields :example, title: 'Click here to select a field'

Possible arguments for build_conditions are:

Param Description
placeholder Placeholder for inputs {operators: 'Select a operator...', values: 'Enter a value...'},
values initial values to fill conditions, format: [[field, operator, value], [field, operator, [value1, value2]]]
input to get initial values and save values on change from a html element, like: #my_input_element
debug to see debugs flags. default: false
numericConfig When the field is decimal type then the generator will create an input with numeric mask. Default {aSep: '', aDec: '.', aSign: ''}. See Auto Numeric Plugin
select2Config: Select2 Configuration. Default {theme: "bootstrap", width: 'auto', placeholder: '', allowClear: false, dropdownAutoWidth: 'true', tags: false, language: "en"}, but some parameters can be overwritten by condition builder. See Select2 Plugin

You can also create the builder manually by calling the jquery plugin:

//my_dictionary_json = ExampleDictionary.dictionary(:example).to_json
//my_initial_values = [['name','eq','My Name']]
var builder = $('#div-container').conditionBuilder({
    placeholder: {values: 'Select a Value'},
    dictionary: my_dictionary_json,
    values: my_initial_values,
    select2Config: {language: 'pt-BR'} //visual_condition_builder/select2_i18n/pt-BR
});

Javascript Methods/Callback

The conditions builder plugin have two actions:

  • Clear - clear the conditions rows
  • Result - return the conditions values on change fields, operators or values.

Example:

$(document).ready(function () {
    //get the builder instance
    var $conditionBuilder = $('#example_default_condition_container').data('conditionBuilder');

    //clear conditions rows
    $('#button_to_clear_list').on('click',function(e){
      e.preventDefault();
      $conditionBuilder.clear_rows();
    });
    
    //Callback on change conditions
    $conditionBuilder.result = function(data) {
        //result data object: [[field, operator, value], [field, operator, [value1, value2]]]
        console.log(data);
        //convert to STRING before send FORM
        var json_data = JSON.stringify(data);
    }
});

Converters

Condition Builder have converters of values to use in controller:

  • Ransack - Convert conditions values ['name', 'eq', 'My Name'] in {:name_eq => "My Name"}
  @example_conditions = JSON.parse(params[:my_conditions] ||= '[]')
  ransack_params = VisualConditionBuilder::Converter.to_ransack(@example_conditions)
  @q = source.ransack(ransack_params)
  @records = @q.result.paginate(page: params[:page], per_page: 10)

i18N

When you create the conditions with build_conditions and conditions_fields the builder automacaly translate attributes for you. See locale file example config/locales/visual_condition_builder.pt-BR.yml: Parameters with dots in the name are converted to underscores, example: "address.number" => "address_number"

pt-BR:
  condition_builder:
    dropdown: 'Filtros'
    operators:
      between: 'Entre ... e ...'
      today: 'Hoje'
      yesterday: 'Ontem'
      tomorrow: 'Amanhã'
      this_week: 'Essa Semana'
      last_week: 'Semana Passada'
      next_week: 'Próxima Semana'
      eq: 'Igual'
      not_eq: 'Diferente'
      matches: 'Parecido'
      does_not_match: 'Não é Parecido'
      lt: 'Menor'
      gt: 'Maior'
      lteq: 'Menor ou Igual'
      gteq: 'Maior ou Igual'
      in: 'Possui todos'
      not_in: 'Não possui todos'
      cont: 'Contém'
      not_cont: 'Não Contém'
      cont_any: 'Contém algum'
      not_cont_any: 'Não Contém algum'
      cont_all: 'Contém todos'
      not_cont_all: 'Não contém todos'
      start: 'Começa com'
      not_start: 'Não começa com'
      end: 'Termina com'
      not_end: 'Não termina com'
      true: 'Verdadeiro'
      not_true: 'Não Verdadeiro'
      false: 'Falso'
      not_false: 'Não Falso'
      present: 'Presente'
      blank: 'Não Presente'
      null: 'Nulo'
      not_null: 'Não Nulo'
    placeholder:
      operators: 'Selecione um operador'
      values: 'Selecione um valor'
    dictionaries:
      exemplo: 'Meu Dicionário de Exemplo'
  condition_dictionaries:
    exemplo:
      name: 'Name'
      age: 'Age'
      address_number: "Adress Number"

Bug reports

If you discover any bugs, feel free to create an issue on GitHub. Please add as much information as possible to help us fixing the possible bug. We also encourage you to help even more by forking and sending us a pull request.

https://github.com/brunoporto/visual_condition_builder/issues

Maintainers

License

The MIT License (MIT) Copyright (c) 2016 Bruno Porto

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.