script.aculo.us - Preenchimento automático

Pronto para uso, script.aculo.us oferece suporte a duas fontes para preenchimento automático -

Fontes remotas (obtidas através do Ajax),
Fontes locais (arrays de string nos scripts de sua página da web).

Dependendo da fonte que você está planejando usar, você instanciará Ajax.Autocompleter ou Autocompleter.Local , respectivamente. Embora equipados com opções específicas, esses dois objetos compartilham um grande conjunto de recursos e fornecem uma experiência de usuário uniforme.

Existem quatro coisas que você sempre passará para esses objetos ao construí-los -

O campo de texto que você deseja tornar autocompletável. Como de costume, você pode passar o próprio campo ou o valor de seu atributo id =.
O contêiner para opções de preenchimento automático, que acabará contendo uma <ul> </li> lista de opções para escolher. Novamente, passe o elemento diretamente ou seuid =. Este elemento é geralmente um simples <div>.</p> </li>
A fonte de dados, que será expressa, dependendo do tipo de fonte, como um array JavaScript de strings ou como um URL para a fonte remota.
Finalmente, as opções. Como sempre, eles são fornecidos como uma espécie de hash, e ambos os objetos de preenchimento automático podem se virar sem nenhuma opção personalizada; existem padrões adequados para tudo.

Para usar os recursos de preenchimento automático de script.aculo.us, você precisará carregar os módulos controls.js e effects.js junto com o módulo prototype.js. Portanto, seu carregamento mínimo para script.aculo.us será semelhante a este -

<script type = "text/javascript" src = "/javascript/prototype.js"></script>
<script type = "text/javascript"  src = "/javascript/scriptaculous.js?load = effects,controls"></script>

Criando um Completador Automático Ajax

A sintaxe de construção é a seguinte -

new Ajax.Autocompleter(element, container, url [ , options ] )

O construtor do Ajax.Autocompleter aceita quatro parâmetros -

O nome do elemento ou referência a um campo de texto que deve ser preenchido com uma escolha de dados.
O nome do elemento ou referência a um elemento <div> a ser usado como um menu de opções pelo controle.
A URL do recurso do lado do servidor que fornecerá as opções.
As opções habituais de hash.

Opções

Você pode usar uma ou mais das seguintes opções ao criar seu objeto Ajax.Autocompleter.

Sr. Não	Opção e descrição
1	paramName O nome do parâmetro de consulta que contém o conteúdo do campo de texto postado no recurso do lado do servidor. O padrão é o nome do campo de texto.
2	minChars Número de caracteres que devem ser inseridos antes que uma solicitação de opções do lado do servidor possa ser disparada. O padrão é 1.
3	Frequency O intervalo, em segundos, entre as verificações internas para ver se uma solicitação para o recurso do lado do servidor deve ser postada. O padrão é 0,4.
4	Indicator O id ou referência a um elemento a ser exibido enquanto uma solicitação de escolhas do lado do servidor está em andamento. Se omitido, nenhum elemento é revelado.
5	Parameters Uma string de texto contendo parâmetros de consulta extras a serem passados para o recurso do lado do servidor.
6	updateElement Uma função de retorno de chamada a ser acionada quando o usuário seleciona uma das opções retornadas do servidor que substitui a função interna que atualiza o campo de texto com o valor escolhido.
7	afterUpdateElement Uma função de retorno de chamada a ser disparada após a função updateElement ter sido executada.
8	Tokens Uma única sequência de texto ou matriz de sequências de texto que indicam tokens a serem usados como delimitadores para permitir que vários elementos sejam inseridos no campo de texto, cada um dos quais pode ser preenchido automaticamente individualmente.

Exemplo

<html>
   <head>
      <title>Simple Ajax Auto-completer Example</title>
		
      <script type = "text/javascript" src = "/javascript/prototype.js"></script>
      <script type = "text/javascript" src = "/javascript/scriptaculous.js?load = effects,controls"></script>
      
      <script type = "text/javascript">
         window.onload = function() {
            new Ajax.Autocompleter(
               'autoCompleteTextField',
               'autoCompleteMenu',
               '/script.aculo.us/serverSideScript.php', {}
            );
         }
      </script>
   </head>
   
   <body>
      <p>Type something in this box and then select suggested option from the list </p>

      <div>
         <label>Text field:</label>
         <input type = "text" id = "autoCompleteTextField"/>
         <div id = "autoCompleteMenu"></div>
      </div>
   </body>
</html>

Agora, precisamos de um servidor para acessar essa página e servir a URL da fonte de dados (serverSideScript.php). Você manterá uma lógica completa para exibir sugestões neste script.

Por exemplo, estamos mantendo um texto HTML simples em serverSideScript.php . Você pode escrever seu script usando CGI, PHP, Ruby ou qualquer outro script do lado do servidor para escolher as sugestões apropriadas e formatá-las na forma de <ul><li>...</li> </ul> e passá-las de volta para o programa do chamador.

<ul>
   <li>One</li>
   <li>Two</li>
   <li>Three</li>
   <li>Four</li>
   <li>Five</li>
   <li>Six</li>
</ul>

Isso produzirá o seguinte resultado -

com diferentes opções discutidas na tabela acima.

Criando um Completador Automático Local

A criação de um completador automático local é quase idêntica à criação de um completador automático Ajax, conforme discutimos na seção anterior.

A principal diferença está em como o conjunto de dados de apoio a ser usado para o preenchimento automático é identificado para o controle.

Com um completador automático Ajax, fornecemos a URL de um recurso do lado do servidor que realizaria a filtragem necessária, de acordo com a entrada do usuário, e retornaria apenas os elementos de dados correspondentes. Com um Autocompleter local, fornecemos a lista completa de elementos de dados em vez disso, como uma matriz de String JavaScript, e o próprio controle executa a operação de filtragem em seu próprio código de cliente.

Toda a sintaxe de construção é na verdade a seguinte -

new Autocompleter.Local(field, container, dataSource [ , options ] );

O construtor do Autocompleter.Local aceita quatro parâmetros -

O nome do elemento ou referência a um campo de texto que deve ser preenchido com uma escolha de dados.
O nome do elemento ou referência a um elemento <div> a ser usado como um menu de opções pelo controle
Para o terceiro parâmetro, em vez de um URL, como no complemento automático assistido pelo servidor, fornecemos uma pequena matriz String, que contém todos os valores possíveis.
As opções habituais de hash.

Opções

Você pode usar uma ou mais das seguintes opções ao criar seu objeto Autocompleter.Local.

Sr. Não	Opção e descrição
1	Choices O número de opções a serem exibidas. O padrão é 10.
2	partialSearch Ativa a correspondência no início de palavras incorporadas nas strings de conclusão. O padrão é verdadeiro.
3	fullSearch Ativa a correspondência em qualquer lugar nas strings de conclusão. O padrão é falso.
4	partialChars Define o número de caracteres que devem ser digitados antes que qualquer correspondência parcial seja tentada. O padrão é 2.
5	ignoreCase Ignora maiúsculas e minúsculas ao combinar. O padrão é verdadeiro.

Exemplo

<html>
   <head>
      <title>Simple Ajax Auto-completer Example</title>
		
      <script type = "text/javascript" src = "/javascript/prototype.js"></script>
      <script type = "text/javascript"  src = "/javascript/scriptaculous.js?load = effects,controls"></script>
      
      <script type = "text/javascript">
         window.onload = function() {
            new Autocompleter.Local(
               'autoCompleteTextField',
               'autoCompleteMenu',
               ['abcdef','abcdeg','xyzabcefg', 'tybabdefg','acdefg'],
               {ignoreCase:false}
            );
         }
      </script>
   </head>

   <body>
      <p>Type something in this box and then select suggested option from the list </p>
		
      <div>
         <label>Text field:</label>
         <input type = "text" id = "autoCompleteTextField"/>
         <div id = "autoCompleteMenu"></div>
      </div>		
   </body>
</html>

Quando exibido, e após o caractere 'a' ser digitado na caixa de texto, ele exibe todas as opções correspondentes.

Use nosso compilador online para uma melhor compreensão do código com as diferentes opções discutidas na tabela acima.

Isso produzirá o seguinte resultado -