From 1215de575d9cda66b434f21dafdf44f986638b71 Mon Sep 17 00:00:00 2001 From: friendica Date: Mon, 9 Jul 2012 23:23:20 -0700 Subject: slider --- .../development-bundle/docs/autocomplete.html | 880 +++++++++++++++++++++ 1 file changed, 880 insertions(+) create mode 100644 include/jquery_ui/development-bundle/docs/autocomplete.html (limited to 'include/jquery_ui/development-bundle/docs/autocomplete.html') diff --git a/include/jquery_ui/development-bundle/docs/autocomplete.html b/include/jquery_ui/development-bundle/docs/autocomplete.html new file mode 100644 index 000000000..6247969cb --- /dev/null +++ b/include/jquery_ui/development-bundle/docs/autocomplete.html @@ -0,0 +1,880 @@ + + +
+

jQuery UI Autocomplete

+
+

Overview

+
+

Autocomplete, when added to an input field, enables users to quickly find and select from a pre-populated list of values as they type, leveraging searching and filtering.

+

By giving an Autocomplete field focus or entering something into it, the plugin starts searching for entries that match and displays a list of values to choose from. By entering more characters, the user can filter down the list to better matches.

+

This can be used to enter previous selected values, for example you could use Autocomplete for entering tags, to complete an address, you could enter a city name and get the zip code, or maybe enter email addresses from an address book.

+

You can pull data in from a local and/or a remote source: Local is good for small data sets (like an address book with 50 entries), remote is necessary for big data sets, like a database with hundreds or millions of entries to select from.

+

Autocomplete can be customized to work with various data sources, by just specifying the source option. A data source can be:

+
    +
  • an Array with local data
    • +
  • a String, specifying a URL
    • +
  • a Callback
    • +
+

Expected data format

+

The data from local data, a url or a callback can come in two variants:

+
    +
  • An Array of Strings:
    [ "Choice1", "Choice2" ]
    • +
  • An Array of Objects with label and value properties:
    [ { label: "Choice1", value: "value1" }, ... ]
    • +
+

The label property is displayed in the suggestion menu. The value will be inserted into the input element after the user selected something from the menu. If just one property is specified, it will be used for both, eg. if you provide only value-properties, the value will also be used as the label.

+

When a String is used, the Autocomplete plugin expects that string to point to a URL resource that will return JSON data. It can be on the same host or on a different one (must provide JSONP). The Autocomplete plugin does not filter the results, instead the request parameter "term" gets added to the URL, which the server-side script should use for filtering the results. The data itself can be in the same format as the local data described above.

+

The third variation, the callback, provides the most flexibility, and can be used to connect any data source to Autocomplete. The callback gets two arguments:

+
    +
  • A request object, with a single property called "term", which refers to the value currently in the text input. For example, when the user entered "new yo" in a city field, the Autocomplete term will equal "new yo".
    • +
  • A response callback, which expects a single argument to contain the data to suggest to the user. This data should be filtered based on the provided term, and can be in any of the formats described above for simple local data (String-Array or Object-Array with label/value/both properties). It's important when providing a custom source callback to handle errors during the request. You must always call the response callback even if you encounter an error. This ensures that the widget always has the correct state.
    • +
+

The label is always treated as text, if you want the label to be treated as html you can use Scott González' html extension. The demos all focus on different variations of the source-option - look for the one that matches your use case, and take a look at the code.

+
+
+

Dependencies

+
    +
  • UI Core
    • +
  • UI Widget
    • +
  • UI Position
    • +
+
+
+

Example

+
+ +

+A simple jQuery UI Autocomplete.
+

+
$("input#autocomplete").autocomplete({
+    source: ["c++", "java", "php", "coldfusion", "javascript", "asp", "ruby"]
+});
+
+

+

+
<!DOCTYPE html>
+<html>
+<head>
+  <link href="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8/themes/base/jquery-ui.css" rel="stylesheet" type="text/css"/>
+  <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.5/jquery.min.js"></script>
+  <script src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8/jquery-ui.min.js"></script>
+  
+  <script>
+  $(document).ready(function() {
+    $("input#autocomplete").autocomplete({
+    source: ["c++", "java", "php", "coldfusion", "javascript", "asp", "ruby"]
+});
+  });
+  </script>
+</head>
+<body style="font-size:62.5%;">
+  
+<input id="autocomplete" />
+
+</body>
+</html>
+
+

+

+
+
+
+

Options

+
    + +
  • +
    +

    disabled

    +
    +
    Type:
    +
    Boolean
    + +
    Default:
    +
    false
    + +
    +
    +
    +

    Disables (true) or enables (false) the autocomplete. Can be set when initialising (first creating) the autocomplete.

    +
    +
    +

    Code examples

    +
    + +
    + Initialize a autocomplete with the disabled option specified. +
    +
    +
    $( ".selector" ).autocomplete({ disabled: true });
    +
    + + +
    + Get or set the disabled option, after init. +
    +
    +
    //getter
+var disabled = $( ".selector" ).autocomplete( "option", "disabled" );
+//setter
+$( ".selector" ).autocomplete( "option", "disabled", true );
    +
    + +
    +
    +
    • + + +
  • +
    +

    appendTo

    +
    +
    Type:
    +
    Selector
    + +
    Default:
    +
    "body"
    + +
    +
    +
    +

    Which element the menu should be appended to.

    +
    +
    +

    Code examples

    +
    + +
    + Initialize a autocomplete with the appendTo option specified. +
    +
    +
    $( ".selector" ).autocomplete({ appendTo: "#someElem" });
    +
    + + +
    + Get or set the appendTo option, after init. +
    +
    +
    //getter
+var appendTo = $( ".selector" ).autocomplete( "option", "appendTo" );
+//setter
+$( ".selector" ).autocomplete( "option", "appendTo", "#someElem" );
    +
    + +
    +
    +
    • + + +
  • +
    +

    autoFocus

    +
    +
    Type:
    +
    Boolean
    + +
    Default:
    +
    false
    + +
    +
    +
    +

    If set to true the first item will be automatically focused.

    +
    +
    +

    Code examples

    +
    + +
    + Initialize a autocomplete with the autoFocus option specified. +
    +
    +
    $( ".selector" ).autocomplete({ autoFocus: true });
    +
    + + +
    + Get or set the autoFocus option, after init. +
    +
    +
    //getter
+var autoFocus = $( ".selector" ).autocomplete( "option", "autoFocus" );
+//setter
+$( ".selector" ).autocomplete( "option", "autoFocus", true );
    +
    + +
    +
    +
    • + + +
  • +
    +

    delay

    +
    +
    Type:
    +
    Integer
    + +
    Default:
    +
    300
    + +
    +
    +
    +

    The delay in milliseconds the Autocomplete waits after a keystroke to activate itself. A zero-delay makes sense for local data (more responsive), but can produce a lot of load for remote data, while being less responsive.

    +
    +
    +

    Code examples

    +
    + +
    + Initialize a autocomplete with the delay option specified. +
    +
    +
    $( ".selector" ).autocomplete({ delay: 0 });
    +
    + + +
    + Get or set the delay option, after init. +
    +
    +
    //getter
+var delay = $( ".selector" ).autocomplete( "option", "delay" );
+//setter
+$( ".selector" ).autocomplete( "option", "delay", 0 );
    +
    + +
    +
    +
    • + + +
  • +
    +

    minLength

    +
    +
    Type:
    +
    Integer
    + +
    Default:
    +
    1
    + +
    +
    +
    +

    The minimum number of characters a user has to type before the Autocomplete activates. Zero is useful for local data with just a few items. Should be increased when there are a lot of items, where a single character would match a few thousand items.

    +
    +
    +

    Code examples

    +
    + +
    + Initialize a autocomplete with the minLength option specified. +
    +
    +
    $( ".selector" ).autocomplete({ minLength: 0 });
    +
    + + +
    + Get or set the minLength option, after init. +
    +
    +
    //getter
+var minLength = $( ".selector" ).autocomplete( "option", "minLength" );
+//setter
+$( ".selector" ).autocomplete( "option", "minLength", 0 );
    +
    + +
    +
    +
    • + + +
  • +
    +

    position

    +
    +
    Type:
    +
    Object
    + +
    Default:
    +
    { my: "left top", at: "left bottom", collision: "none" }
    + +
    +
    +
    +

    Identifies the position of the Autocomplete widget in relation to the associated input element. The "of" option defaults to the input element, but you can specify another element to position against. You can refer to the jQuery UI Position utility for more details about the various options.

    +
    +
    +

    Code examples

    +
    + +
    + Initialize a autocomplete with the position option specified. +
    +
    +
    $( ".selector" ).autocomplete({ position: { my : "right top", at: "right bottom" } });
    +
    + + +
    + Get or set the position option, after init. +
    +
    +
    //getter
+var position = $( ".selector" ).autocomplete( "option", "position" );
+//setter
+$( ".selector" ).autocomplete( "option", "position", { my : "right top", at: "right bottom" } );
    +
    + +
    +
    +
    • + + +
  • +
    +

    source

    +
    +
    Type:
    +
    String, Array, Callback
    + +
    Default:
    +
    none, must be specified
    + +
    +
    +
    +

    Defines the data to use, must be specified. See Overview section for more details, and look at the various demos.

    +
    +
    +

    Code examples

    +
    + +
    + Initialize a autocomplete with the source option specified. +
    +
    +
    $( ".selector" ).autocomplete({ source: ["c++", "java", "php", "coldfusion", "javascript", "asp", "ruby"] });
    +
    + + +
    + Get or set the source option, after init. +
    +
    +
    //getter
+var source = $( ".selector" ).autocomplete( "option", "source" );
+//setter
+$( ".selector" ).autocomplete( "option", "source", ["c++", "java", "php", "coldfusion", "javascript", "asp", "ruby"] );
    +
    + +
    +
    +
    • + +
+
+
+

Events

+
    + +
  • +
    +

    create

    +
    +
    Type:
    +
    autocompletecreate
    +
    +
    +
    +

    This event is triggered when autocomplete is created.

    +
    +
    +

    Code examples

    +
    + +
    + Supply a callback function to handle the create event as an init option. +
    +
    +
    $( ".selector" ).autocomplete({
+   create: function(event, ui) { ... }
+});
    +
    + + +
    + Bind to the create event by type: autocompletecreate. +
    +
    +
    $( ".selector" ).bind( "autocompletecreate", function(event, ui) {
+  ...
+});
    +
    + +
    +
    +
    • + + + + + +
  • +
    +

    open

    +
    +
    Type:
    +
    autocompleteopen
    +
    +
    +
    +

    Triggered when the suggestion menu is opened.

    +
    +
    +

    Code examples

    +
    + +
    + Supply a callback function to handle the open event as an init option. +
    +
    +
    $( ".selector" ).autocomplete({
+   open: function(event, ui) { ... }
+});
    +
    + + +
    + Bind to the open event by type: autocompleteopen. +
    +
    +
    $( ".selector" ).bind( "autocompleteopen", function(event, ui) {
+  ...
+});
    +
    + +
    +
    +
    • + + +
  • +
    +

    focus

    +
    +
    Type:
    +
    autocompletefocus
    +
    +
    +
    +

    Before focus is moved to an item (not selecting), ui.item refers to the focused item. The default action of focus is to replace the text field's value with the value of the focused item, though only if the focus event was triggered by a keyboard interaction. Canceling this event prevents the value from being updated, but does not prevent the menu item from being focused.

    +
    +
    +

    Code examples

    +
    + +
    + Supply a callback function to handle the focus event as an init option. +
    +
    +
    $( ".selector" ).autocomplete({
+   focus: function(event, ui) { ... }
+});
    +
    + + +
    + Bind to the focus event by type: autocompletefocus. +
    +
    +
    $( ".selector" ).bind( "autocompletefocus", function(event, ui) {
+  ...
+});
    +
    + +
    +
    +
    • + + +
  • +
    +

    select

    +
    +
    Type:
    +
    autocompleteselect
    +
    +
    +
    +

    Triggered when an item is selected from the menu; ui.item refers to the selected item. The default action of select is to replace the text field's value with the value of the selected item. Canceling this event prevents the value from being updated, but does not prevent the menu from closing.

    +
    +
    +

    Code examples

    +
    + +
    + Supply a callback function to handle the select event as an init option. +
    +
    +
    $( ".selector" ).autocomplete({
+   select: function(event, ui) { ... }
+});
    +
    + + +
    + Bind to the select event by type: autocompleteselect. +
    +
    +
    $( ".selector" ).bind( "autocompleteselect", function(event, ui) {
+  ...
+});
    +
    + +
    +
    +
    • + + +
  • +
    +

    close

    +
    +
    Type:
    +
    autocompleteclose
    +
    +
    +
    +

    When the list is hidden - doesn't have to occur together with a change.

    +
    +
    +

    Code examples

    +
    + +
    + Supply a callback function to handle the close event as an init option. +
    +
    +
    $( ".selector" ).autocomplete({
+   close: function(event, ui) { ... }
+});
    +
    + + +
    + Bind to the close event by type: autocompleteclose. +
    +
    +
    $( ".selector" ).bind( "autocompleteclose", function(event, ui) {
+  ...
+});
    +
    + +
    +
    +
    • + + +
  • +
    +

    change

    +
    +
    Type:
    +
    autocompletechange
    +
    +
    +
    +

    Triggered when the field is blurred, if the value has changed; ui.item refers to the selected item.

    +
    +
    +

    Code examples

    +
    + +
    + Supply a callback function to handle the change event as an init option. +
    +
    +
    $( ".selector" ).autocomplete({
+   change: function(event, ui) { ... }
+});
    +
    + + +
    + Bind to the change event by type: autocompletechange. +
    +
    +
    $( ".selector" ).bind( "autocompletechange", function(event, ui) {
+  ...
+});
    +
    + +
    +
    +
    • + +
+
+
+

Methods

+
    + +
  • +
    +

    destroy

    +
    +
    Signature:
    +
    .autocomplete( "destroy" + + + + + + + +)
    +
    +
    +
    +

    Remove the autocomplete functionality completely. This will return the element back to its pre-init state.

    +
    +
    • + + +
  • +
    +

    disable

    +
    +
    Signature:
    +
    .autocomplete( "disable" + + + + + + + +)
    +
    +
    +
    +

    Disable the autocomplete.

    +
    +
    • + + +
  • +
    +

    enable

    +
    +
    Signature:
    +
    .autocomplete( "enable" + + + + + + + +)
    +
    +
    +
    +

    Enable the autocomplete.

    +
    +
    • + + +
  • +
    +

    option

    +
    +
    Signature:
    +
    .autocomplete( "option" + +, optionName + +, [value] + + + +)
    +
    +
    +
    +

    Get or set any autocomplete option. If no value is specified, will act as a getter.

    +
    +
    • + + +
  • +
    +

    option

    +
    +
    Signature:
    +
    .autocomplete( "option" + +, options + + + + + +)
    +
    +
    +
    +

    Set multiple autocomplete options at once by providing an options object.

    +
    +
    • + + +
  • +
    +

    widget

    +
    +
    Signature:
    +
    .autocomplete( "widget" + + + + + + + +)
    +
    +
    +
    +

    Returns the .ui-autocomplete element.

    +
    +
    • + + + + + +
  • +
    +

    close

    +
    +
    Signature:
    +
    .autocomplete( "close" + + + + + + + +)
    +
    +
    +
    +

    Close the Autocomplete menu. Useful in combination with the search method, to close the open menu.

    +
    +
    • + +
+
+
+

Theming

+

The jQuery UI Autocomplete plugin uses the jQuery UI CSS Framework to style its look and feel, including colors and background textures. We recommend using the ThemeRoller tool to create and download custom themes that are easy to build and maintain. +

+

If a deeper level of customization is needed, there are widget-specific classes referenced within the jquery.ui.autocomplete.css stylesheet that can be modified. These classes are highlighed in bold below. +

+ +

Sample markup with jQuery UI CSS Framework classes

+ <input class="ui-autocomplete-input"/>
+<ul class="ui-autocomplete ui-menu ui-widget ui-widget-content ui-corner-all">
+  <li class="ui-menu-item">
+    <a class="ui-corner-all">item 1</a>
+  </li>
+  <li class="ui-menu-item">
+    <a class="ui-corner-all">item 2</a>
+  </li>
+  <li class="ui-menu-item">
+    <a class="ui-corner-all">item 3</a>
+  </li>
+</ul> +

+ + Note: This is a sample of markup generated by the autocomplete plugin, not markup you should use to create a autocomplete. The only markup needed for that is <input/>. + +

+ +
+
+ +

+ + -- cgit v1.2.3