Script.aculo.us 简明教程

script.aculo.us - Auto Completion

默认情况下，script.aculo.us 支持两种自动完成来源 −

Out of the box, script.aculo.us supports two sources for auto-completion −

Remote sources (obtained through Ajax),
Local sources (string arrays in your web page’s scripts).

根据你计划使用的来源，你将分别实例化 Ajax.Autocompleter 或 Autocompleter.Local。尽管配有特定的选项，但这两个对象共享一组大型功能，并提供统一的用户体验。

Depending on the source you’re planning to use, you’ll instantiate Ajax.Autocompleter or Autocompleter.Local, respectively. Although equipped with specific options, these two objects share a large feature set and provide a uniform user experience.

在构建这些对象时，你始终会将以下四项传递给它们：

There are four things you’ll always pass to these objects while building them −

The text field you want to make autocompletable. As usual, you can pass the field itself or the value of its id = attribute.
The container for autocompletion choices, which will end up holding a <ul></li> list of options to pick from. Again, pass the element directly or its id =. This element is most often a simple <div>.</p></li>
The data source, which will be expressed, depending on the source type, as a JavaScript array of strings or as a URL to the remote source.
Finally, the options. As always, they’re provided as a hash of sorts, and both autocompletion objects can make do with no custom option; there are suitable defaults for everything.

为了使用 script.aculo.us 的自动完成功能，你需要加载 controls.js 和 effects.js 模块以及 prototype.js 模块。所以，script.aculo.us 的最小加载量看起来像这样 −

To use script.aculo.us’s autocompletion capabilities, you’ll need to load the controls.js and effects.js modules along with the prototype.js module. So, your minimum loading for script.aculo.us will look like this −

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

Creating an Ajax Auto-Completer

构建语法如下 −

The construction syntax is as follows −

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

Ajax.Autocompleter 的构造函数接受四个参数 −

The constructor for the Ajax.Autocompleter accepts four parameters −

The element name or reference to a text field that is to be populated with a data choice.
The element name or reference to a <div> element to be used as a menu of choices by the control.
The URL of the server-side resource that will supply the choices.
The usual options hash.

Options

创建你的 Ajax.Autocompleter 对象时，你可以使用以下一个或多个选项。

You can use one or more of the following options while creating your Ajax.Autocompleter object.

Sr.No	Option & Description
1	paramName The name of the query parameter containing the content of the text field that is posted to the server-side resource. Defaults to the name of the text field.
2	minChars Number of characters that must be entered before a server-side request for choices can be fired off. Defaults to 1.
3	Frequency The interval, in seconds, between internal checks to see if a request to the server-side resource should be posted. Defaults to 0.4.
4	Indicator The id or reference to an element to be displayed while a server-side request for choices is underway. If omitted, no element is revealed.
5	Parameters A text string containing extra query parameters to be passed to the server-side resource.
6	updateElement A callback function to be triggered when the user selects one of the choices returned from the server that replaces the internal function that updates the text field with the chosen value.
7	afterUpdateElement A callback function to be triggered after the updateElement function has been executed.
8	Tokens A single text string, or array of text strings that indicate tokens to be used as delimiters to allow multiple elements to be entered into the text field, each of which can be auto-completed individually.

Example

<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>

现在，我们需要服务器端来访问此页面并提供数据源 URL (serverSideScript.php)。您将保持一个完整的逻辑来在此脚本中显示建议。

Now, we need a server side to access this page and serve the data source URL (serverSideScript.php). You will keep a complete logic to display suggestions in this script.

就示例而言，我们在 serverSideScript.php 中保留了一个简单的 HTML 文本。您可以使用 CGI、PHP、Ruby 或任何其他服务器端脚本编写脚本以选择合适的建议，并将它们格式化为 <ul><li>…</li></ul> 形式并将其传递回调用程序。

Just for example, we are keeping a simple HTML text in serverSideScript.php. You can write your script using CGI, PHP, Ruby, or any other server side scripting to choose appropriate suggestions and format them in the form of <ul><li>…</li></ul> and pass them back to the caller program.

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

这将生成以下结果：

This will produce following result −

本文档中讨论了不同选项。

with different options discussed in the above table.

Creating a Local Auto-Completer

创建本地自动完成器几乎与我们在前一节中讨论过的创建 Ajax 自动完成器相同。

Creating a local auto-completer is almost identical to creating an Ajax Auto-completer as we have discussed in the previous section.

主要区别在于如何识别用于自动完成的备用数据集。

The major difference lies in how the backing data set to use for auto-completion is identified to the control.

通过 Ajax 自动完成器，我们提供了服务器端资源的 URL，该资源会执行必需的过滤（根据用户输入），并仅返回匹配的数据元素。通过本地自动完成器，我们改为提供数据元素的完整列表（以 JavaScript 字符串数组的形式），并且控件本身在其自己的客户端代码内执行过滤操作。

With an Ajax Auto-completer, we have supplied the URL of a server-side resource that would perform the necessary filtering, given the user input, and return only the data elements that matched. With a Local Autocompleter, we supply the full list of data element instead, as a JavaScript String array, and the control itself performs the filtering operation within its own client code.

整个构造语法实际上如下所示 −

The whole construction syntax is actually as follows −

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

自动完成器的构造函数接受四个参数：

The constructor for the Autocompleter.Local accepts four parameters −

The element name or reference to a text field that is to be populated with a data choice.
The element name or reference to a <div> element to be used as a menu of choices by the control
For the third parameter, instead of a URL as with the server-assisted auto-completer, we supply a small String array, which contains all of the possible values.
The usual options hash.

Options

在创建 Autocompleter.Local 对象时，您可以使用以下一个或多个选项。

You can use one or more of the following options while creating your Autocompleter.Local object.

Sr.No	Option & Description
1	Choices The number of choices to display. Defaults to 10.
2	partialSearch Enables matching at the beginning of words embedded within the completion strings. Defaults to true.
3	fullSearch Enables matching anywhere within the completion strings. Defaults to false.
4	partialChars Defines the number of characters that must be typed before any partial matching is attempted. Defaults to 2.
5	ignoreCase Ignores case when matching. Defaults to true.

Example

<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>

显示出来，并且在文本框中键入字符“a”之后，它将显示所有匹配的选项。

When displayed, and after the character 'a' is typed into the text box, it displays all the matching options.

使用我们的在线编译器，更好地理解上面表格中讨论的各种选项的代码。

Use our online compiler for a better understanding of the code with different options discussed in the above table.

这将生成以下结果：

This will produce following result −