= Campo de Entrada Autocompletável =

== Plugin: wf_autocomplete_input_init ==

'''Descrição:''' Insere código que referencia arquivos de javascript responsáveis pela funcionalidade.

'''Parâmetros:''' <nenhum>

'''Exemplo:'''

{{{
{wf_autocomplete_input_init}
}}}

Observação: antes de utilizar "wf_autocomplete_input" (seja uma ou mais vezes), deve-se fazer uma '''única''' chamada ao plugin "wf_autocomplete_input_init". 

----

== Plugin: wf_autocomplete_input ==

'''Descrição:''' Este plugin insere um ''input'' que, conforme o usuário digita uma nova entrada, são filtrados e mostrados os valores que podem ser selecionados.[[br]]
Este componente possui dois modos de funcionamento:
 * POPULATE_ON_LOAD: Todos os valores são armazenados em um cache previamente através de uma requisição ajax.
 * REPOPULATE_ON_CHANGE: Os valores vão sendo armazenados em um cache conforme são feitas as requisições ajax. Este modo foi desenvolvido de forma que não haja 2 chamadas ajax idênticas, ou seja, apenas entradas diferentes farão novas chamadas.
Em ambos os modos a classe e o método que serão invocados devem ser implementados no processo e são passados por parêmetro no momento em que o desenvolvedor utiliza o componente


'''Parâmetros:'''

  name: o nome que o componente irá receber.

  ajaxClass: classe ajax que será utilizada para fazer a consulta.

  ajaxMethod: método da classe que será invocado para preencher a lista de opções.

  methodParam: (opcional) parâmetro para o método que será invocado para preencher a lista de opções.

  minLength: (opcional) número mínimo de caracteres necessários para que as opções apareçam na lista.

  idValue: (opcional) o id de um item previamente selecionado (não é visível para o usuário).

  textValue: (opcional) o texto de um item inicialmente selecionado (é visível para o usuário).

  style: (opcional) estilo para o campo input.

  mode: (opcional) modo de funcionamento do componente: POPULATE_ON_LOAD ou REPOPULATE_ON_CHANGE


'''Parâmetros obrigatórios:'''

  name

  ajaxClass

  ajaxMethod

'''Valor padrão:'''

  minLength: 1

  style: "width: 200px"

  mode: "POPULATE_ON_LOAD"

'''Exemplo de utilização:'''

{{{
  {wf_autocomplete_input name="_cidade" ajaxClass="abrirOS" ajaxMethod="recuperaCidades" methodParam=1}
}}}

O exemplo acima cria um ''input'' e carrega o cache com o retorno do método '''"recuperaCidades"''' que, com o parâmetro '''"1"''', recupera as cidades do Paraná. Como não foi informado o modo de funcionamento, é utilizado o modo padrão, onde o cache é carregado uma única vez, ou seja, não há outras chamadas ajax durante o uso do componente. Caso queira deixar explícito que o modo utilizado é este, deve-se informar '''"mode='POPULATE_ON_LOAD'"'''.

{{{
  {wf_autocomplete_input name="_cidade_atendimento" ajaxClass="abrirOS" ajaxMethod="recuperaCidadesPorChave" idValue=1 textValue="Curitiba, PR" mode="REPOPULATE_ON_CHANGE"}
}}}

O exemplo acima cria um ''input'' que contém valores iniciais, identificados pelo ''"idValue"'' e ''"textValue"''. O modo '''REPOPULATE_ON_CHANGE''' indica que cada nova entrada fará uma chamada ajax, cujo retorno será armazenado no cache. O uso do cache possibilita que sejam feitas um menor número de chamadas ajax.

'''IMPORTANTE:'''

 * Usando-se este plugin no modo '''REPOPULATE_ON_CHANGE''', não é necessário passar o parâmetro ''"methodParam"'', pois o parâmetro do método será o conteúdo do campo ''input'' em que o usuário está digitando.

 * Sobre o array de retorno da chamada ajax:
   * Os métodos chamados na requisição ajax devem retornar um array no formato:
   {{{
    Array
    (
      [id_1] => texto_1
      [id_2] => texto_2
       ...
    )
   }}}
   * No exemplo das cidades do Paraná, ao digitar 'arap', o método deve retornar:
   {{{
    Array
    (
      [10062] => Arapongas, PR
      [78] => Arapoti, PR
      [10064] => Arapuã, PR
    )
   }}}
    * Neste caso, o componente será apresentado da seguinte forma:[[br]]
     [[Image(autocomplete_cidade.jpg)]]

 * Caso haja a necessidade de passar outros parâmetros ao campo que não sejam tratados pelo componente, eles serão apenas repassados ao elemento ''input''.

 * Ao tirar o foco do campo ''input'', é feita uma verificação se o conteúdo do componente é válido (se encontra no cache, ou não). O resultado é apresentado como mostram as figuras:[[br]]
   [[Image(autocomplete_cidade_ok.jpg)]][[br]]
   [[Image(autocomplete_cidade_nok.jpg)]]