README.md in visual_condition_builder-0.0.3 vs README.md in visual_condition_builder-0.1.0

- old
+ new

@@ -1,155 +1,416 @@ -# Search Builder +# Search Builder +[![Code Climate](https://codeclimate.com/github/brunoporto/visual_condition_builder/badges/gpa.svg)](https://codeclimate.com/github/brunoporto/visual_condition_builder) A great and easy search builder to your rails project -### Instalação +## How to install Add it to your **Gemfile**: ```ruby gem 'visual_condition_builder' ``` -Rubn the following command to install it: +Run the following command to install it: ```sh $ bundle install +$ rails generate visual_condition_builder:install ``` Add it to your **app/assets/stylesheets/application.css** ```js - *= require visual_condition_builder +*= require visual_condition_builder ``` Add it to your **app/assets/javascripts/application.js** ```js - //= require visual_condition_builder +//= require visual_condition_builder ``` -### Dependencies +## Dependency + Antes de iniciar o plugin você precisa ter o jQuery adicionado no seu application.js Caso você tenha os seguintes plugins jQuery indicados no seu application.js, você deve remover: -- select2 -- autoNumeric +- [select2](https://github.com/select2/select2) +- [autoNumeric](https://github.com/BobKnothe/autoNumeric#default-settings--supported-options) - ### 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** ```js -//= require visual_condition_builder +//= require visual_condition_builder/select2_i18n/en //= require visual_condition_builder/select2_i18n/pt-BR ``` -## Como usar +## Dictionaries -Instancie em um elemento jQuery passando os parametros necessários: +As informações do gerador de condições são baseadas em um dicionário, portanto é necessário que você crie seus dicionários de acordo com o necessário. -```javascript -var builder = $('#div-exemplo-regras').ruleBuilder({ - dicionario: [], - regras: [], - texto_instrucao: { - campos: 'Selecione um campo', - operadores: 'Selecione um operador', - valores: 'Informe um valor' - }, - permite_brancos: true, - resultado: function(dados) { - //RETORNO DO RESULTADO EM JSON - } -}); +Para gerar um novo dicionário use o comando: + +```sh +$ rails g visual_condiction_builder:dictionary example ``` -Nos parâmetros dicionário e regras você pode informar diretamente um objeto com os dados ou informar uma url para carregar os dados. Atualmente o carregamento dessa fonte de dados é feita de forma síncrona); -```javascript -var dicionario = [{ - "variavel": "nome_do_campo", // - "tipo": "STRING", // - "descricao": "descricao_do_campo", // - "operadores": [ - {"operador": "simbolo_do_operador", "descricao": "texto_do_operador"}, - {"operador": "=", "descricao": "Igual"}, - {"operador": "EMPTY", "descricao": "Vazio", "sem_valor": "true"}, - {"operador": "IN", "descricao": "Presente em", "multiplo": "true"}, - {"operador": "BETWEEN", "descricao": "Entre", "multiplo": "2" } - ], - "valores": [ - {"id": "1", "label": "Um"}, - {"id": "65465", "label": "José da Silva"}, - {"id": "2016-06-15", "label": "Data de Hoje"}, - {"id": "50.8", "label": "Valor Total"} - ] -}]; +Será criado um arquivo na pasta `app/condition_dictionaries/example_dictionary.rb` com a seguinte estrutura: + +```ruby +class ExampleDictionary < VisualConditionBuilder::Dictionary + + dictionary do + param :name + end + +end ``` -### Parâmetros -#### **dicionario** +Você pode criar multiplos contextos para esse dicionário: +```ruby + dictionary :simple do + param :name + end + + dictionary :complex do + param :first_name + param :last_name + end +``` -> Array de Hash: `[{},{},{}, ...]` +### Params -- *variavel*: Indica qual será o VALUE utilizado no `<option>` do `<select>` na coluna CAMPO -- *tipo*: Qual o tipo do valor do campo, esse tipo influência nos valores. Ex: Date mostra um datepicker no `<input>` do valor. - - STRING, DECIMAL(n), INTEGER, DATE, TIME -- *descricao*: Indica qual será o TEXT utilizado no `<option>` do `<select>` na coluna CAMPO -- *operadores*: Array de Hash com os operadores que esse campo possibilita selecionar. - - *operador*: Indica qual será o VALUE utilizado no `<option>` do `<select>` na coluna OPERADOR - - *descricao*: Indica qual será o TEXT utilizado no `<option>` do `<select>` na coluna OPERADOR - - *sem_valor*: Indica que esse operador não requer um valor, logo ele não será exibido. - - *multiplo*: Indica que o campo possibilita informar multiplos valores. Caso você passe um número para esse campo, esse número indicará quantas caixas de valores serão exibidas para esse campo. -- *valores*: É o Array dos valores que será exibidos para o usuário durante a seleção desse campo. Caso você não informe valores, será exibido um campo em aberto de acordo com o tipo selecionado. Também pode ser informado uma URL para carregar os dados diretamente dessa fonte. - - *id*: Indica qual será o VALUE utilizado no `<option>` do `<select>` na coluna VALOR - - *label*: Indica qual será o TEXT utilizado no `<option>` do `<select>` na coluna VALOR - - *Exemplo*: `"valores": [{"id": "S", "label": "Sim" }, {"id": "N", "label": "Não" }]` +Você não tem restrição ao uso dos parametros, pois eles não tem ligação com model ou qualquer outro elemento da aplicação. +Ao informar os parametros você pode passar argumentos para personalizar a forma como o gerador de condições será criado: -#### **regras** +```ruby + 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 +``` -> Array de Array: `[[],[], ...]` +Veja abaixo todos os argumentos que você pode usar na construção dos operadores: -Esse parâmetro permite informar os dados que serão pré-selecionados ao carregar o plugin, é o estado inicial do plugin. -O array interno das regras sempre deverá ser informado com 3 elementos: `["CAMPO], "OPERADOR", "VALOR"]`, onde o valor poderá ser uma outra array caso esse campo permita seleção de múltiplos valores. +**TABELA DE PARAMETROS DE OPERADORES** -Exemplo: +Por padrão, o gerador de condições implementa alguns operadores e argumentos, possibilitando que você informe apenas o nome do operador `operators: [:eq, :between]` -```javascript -var regras = [ - ["nome_do_campo", "simbolo_do_operador", "id_do_valor"], - ["campo_sim_ou_nao", "=", "S"], - ["campo_decimal", "=", "88884.55"], - ["campo_multiplo_2", "BETWEEN", ["2015-07-21","2015-07-30"]], - ["campo_multiplo_true", "IN", ["A","B","C","D"]] -]; +Lista de operadores padrões do gerador de condições + +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 (not null and not a blank string) | no_value: true, multiple: false +blank | Opposite :present | 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 + +Caso você não informe os operadores, o gerador de condições irá selecionar os operadores baseado no tipo informado: +*Se um tipo não for informado, será considerado 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 + +Também é possível informar listas de valores ou valores pré-definidos para que o gerador de condições para carregar esses valores por padrão: + +```ruby + 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: -> { MyService.get_status } + param :status_ajax, values: ajax_my_status_path + end ``` -#### **permite_brancos** +Em todos os exemplos acima o resultado deve sempre seguir a estrutura : -> Boleano: true/false +```ruby +[ + {id: 1, label: 'Example'}, + {id: 2, label: 'Example 2'}, + {id: 'A', label: 'Example 3'}, + {id: 'Text', label: 'My Text'} +] +``` -Esse campo permite informar se as caixas de seleção irão ou não iniciar com valor "vazio" para que o usuário possa selecionar. Caso *false* seja informado o primeiro valor de cada coluna será pré-selecionado. +Quando for utilizar uma chamada AJAX o gerador de condições fará requisições passando dois tipos de parametros: **init** ou **key**, onde: +* init - é o parametro com o valor inicial da lista. Quando o plugin tenta carregar a lista ele deverá mostrar um valor inicial antes da busca feita pelo usuário, portanto esse valor inicial deve ser retornado através do parametro init: +* key - é o parametro com o valor digitado pelo usuário para efetuar o retorno dos valores da lista. -#### **resultado** +O retorno deverá seguir a estrutua padrão de valores do dicionário e retornar em formato JSON. Exemplo de um controller que implementa essa função: +```ruby +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 +``` -> Função: `function(dados){}` +### Methods -Callback de retorno dos dados em JSON (type object), o retorno segue o mesmo padrão do parâmetro regra, logo o mesmo formato que você informa para pré-popular o plugin será o formato que o plugin retornará apóas as modificações do usuário. +Dictionary Class have public methods to get informations about self: +* fields(dictionary_context_name) +* dictionary(dictionary_context_name) +* dictionaries -Exemplo: +```ruby +#example_dictionary.rb +class ExampleDictionary < VisualConditionBuilder::Dictionary + + dictionary do + param :name + end + + dictionary :complex do + param :name + param :age + 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}]} +``` + +## Helpers + +#### (class) dictionary_values(param_id, param_label) +Deve ser utilizado em objetos do tipo: Array ou ActiveRecord::Relation e usa o primeiro parametro como **id** e o segundo como **label** na construção da estrutura de valores para o dicionário +```ruby +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) +Cria um seletor de campos em um elemento dropdown (bootstrap). +```haml += conditions_fields :example +-# with context: += conditions_fields({:dictionary_name => :context_name}) +``` + +Mas você pode fazer a geração da lista de campos manualmente através do método `ExampleDictionary.fields(dictionary_name)` *(example_dictionary.rb)*, nesse caso você deve ter elementos "clicáveis" com a classe `add-condition-field` e atributo `data-field: field_name` + ```haml +%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) + +Cria o gerador de condições na sua view: +```haml += form_tag obrigacoes_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} +``` +Por padrão será gerado um elemento com o id no padrão dictionary_name + context_name + condition_container: `example_default_condition_container` + +Para criar baseado em um dicionário de contexto específico use: +```haml += build_conditions({:dictionary_name => :context_name}, input: '#my_conditions', select2Config: {allowClear: true}) +``` +Os argumentos possíveis para o build_conditions são: + +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](https://github.com/BobKnothe/autoNumeric#default-settings--supported-options) +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](https://github.com/select2/select2) + +Também é possível criar o builder manualmente chamando o plugin jquery diretamente: ```javascript - var resultado = function(objJSON) { - //CONVERTO JSON EM STRING COMO EXEMPLO... - var stringJSON = JSON.stringify(objJSON); - } +//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 +}); ``` -Esse callback é chamado toda vez que o usuário faz uma modificação no plugin. Caso você queira forçar a recuperação desses dados através de um botão, você pode fazer: +## 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: + ```javascript - var builder = $('#div-exemplo-regras').ruleBuilder({ - //... - }); +$(document).ready(function () { + //get the builder instance + var $conditionBuilder = $('#example_default_condition_container').data('conditionBuilder'); - $('#meu-botao').click(function(){ - var objJSON = builder.getResultado(); - //CONVERTO JSON EM STRING COMO EXEMPLO... - var stringJSON = JSON.stringify(objJSON); - }); -``` + //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"}` + +```ruby + @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`: + +```yml +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: + nome: 'Nome' + idade: 'Idade' +``` + +## 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 + +* Bruno Porto (https://github.com/brunoporto) + +## 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. \ No newline at end of file