view release on metacpan or  search on metacpan

doc/html/AutoCompleter.html  view on Meta::CPAN

    </div>
  </div>
  <div class="TN_node" id="CONSTRUCTOR">
    <h2 class="TN_label">CONSTRUCTOR</h2>
    <div class="TN_content">
      <pre>  var myAutocompleter = new GvaScript.Autocompleter(datasource, options);</pre>

  <div class="TN_node" id="Datasources">
    <h3 class="TN_label">Datasources</h3>
    <div class="TN_content">
        <div class="TN_node" id="Origin">
    <h4 class="TN_label">Origin</h4>
    <div class="TN_content">
      <p>A datasource may be</p>
<ul>
<li><a name="item_a_plain_string"></a><b>a plain string</b>
<p>The string is taken as a base URL. Whenever a suggestion list is needed,
the autocompleter will send an Ajax requests to that URL, concatenated with 
the current value in the associated field. So for example if we have</p>
<pre>  var ac = new GvaScript.Autocompleter("/myapp/completion?search=");
  ..
  &lt;input name="someInput" onfocus="ac.complete(this)"&gt;</pre>

<p>and user has typed <code>ab</code> in the input field, then an Ajax request
will be sent to <code>/myapp/completion?search=ab</code>.</p>
<p>The server should return a JSON array, in the format explained below.</p>
</li>
<li><a name="item_a_callback_function"></a><b>a callback function</b>
<p>That function will be called, with the current value of the field
as single argument.</p>
</li>
<li><a name="item_an_array"></a><b>an array</b>
<p>The array is taken as in-memory datasource. The returned suggestion
list is either the complete array (when <code>options.ignorePrefix</code> is true)
or just the list of items that are prefixed by the current value 
of the field. See also <code>options.caseSensitive</code>.</p>
</li>
<li><a name="item_an_object__JSONP_"></a><b>an object (JSONP)</b>
<p>Useful when accessing data on a different domain via JSONP services.</p>
<pre>  Ex :   { json_url: 'http://search.yahooapis.com/WebSearchService/V1/relatedSuggestion?appid=YahooDemo&amp;query=?1&amp;output=json&amp;callback=?2',
           json_list: 'ResultSet/Result' }</pre>

<p>The object should hold details of the JSONP service to be called.</p>
<p><code>json_url</code> : url to call with placeholders (?1, ?2) for value to look for and callback method respectively.</p>
<p><code>json_list</code> : path to the list in the json response</p>
</li>
</ul>

    </div>
  </div>
  <div class="TN_node" id="Format_of_suggestions_returned_by_datasources">
    <h4 class="TN_label">Format of suggestions returned by datasources</h4>
    <div class="TN_content">
      <p>Datasources should return a list of suggestions in the form
of a Javascript array (in case of Ajax requests, the response 
should be a JSON body containing a single array).</p>
<p>For each suggestion in the array, the autocompleter needs
a <i>label</i> (an HTML fragment to display in suggestion
dropdown lists) and a <i>value</i> (a plain string to put into
the text field when the suggestion is selected). So 
each suggestion may be either</p>
<ul>
<li><a name="item_a_plain_string"></a><b>a plain string</b>
<p>this string will be used both as label and as value.</p>
</li>
<li><a name="item_an_inline_object"></a><b>an inline object</b>
<p>this object is supposed to have a <code>label</code> property and a 
<code>value</code> property. Actually, these are the default names for
the properties; they can be changed in the constructor options.</p>
<p>The <code>label</code> property may contain rich HTML, i.e. including
formatting tags.</p>
</li>
</ul>

    </div>
  </div>

    </div>
  </div>
  <div class="TN_node" id="Options">
    <h3 class="TN_label">Options</h3>
    <div class="TN_content">
      <p>The options to construct an autocompleter object are :</p>
<ul>
<li><a name="item_minimumChars"></a><b>minimumChars</b>
<p>How many characters are needed before trying to find suggestions.</p>
</li>
<li><a name="item_labelField"></a><b>labelField</b>
<p>Name of the field that contains the HTML to display
(default is <code>label</code>).</p>
</li>
<li><a name="item_valueField"></a><b>valueField</b>
<p>Name of the field that contains the value to put in input element
(default is <code>value</code>).</p>
</li>
<li><a name="item_autoSuggest"></a><b>autoSuggest</b>
<p>Boolean value; toggles whether suggestions are displayed automatically
when available (true by default). If false, suggestions are only
displayed when the <code>ARROW_DOWN</code> key is pressed.</p>
</li>
<li><a name="item_autoSuggestDelay"></a><b>autoSuggestDelay</b>
<p>How many milliseconds to wait after a keypress before displaying 
suggestions. Default is 200.</p>
</li>
<li><a name="item_typeAhead"></a><b>typeAhead</b>
<p>If true (the default), the current suggestion will be automatically 
inserted into the input element.</p>
</li>
<li><a name="item_maxHeight"></a><b>maxHeight</b>
<p>Maximum height for the suggestion DIV (in pixels).
Default is 200.</p>
</li>
<li><a name="item_minWidth"></a><b>minWidth</b>
<p>Minimum width for the suggestion DIV (in pixels)
Default is 200.</p>
</li>
<li><a name="item_offsetX"></a><b>offsetX</b>
<p>Offset (in pixels) from the left border of the 
input element to the left border of the 
suggestion DIV.

doc/html/AutoCompleter.html  view on Meta::CPAN

    <div class="TN_content">
      <p>Displays the given message within 
a newly created dropdown DIV under the input field.
Used internally to warn for example about illegal values.</p>

    </div>
  </div>

    </div>
  </div>
  <div class="TN_node" id="EVENTS">
    <h2 class="TN_label">EVENTS</h2>
    <div class="TN_content">
      <p>For a general explanation on registering handlers
for GvaScript events, see the <i>event</i> documentation.
In short, you can register handlers either on the 
HTML input element, as in</p>
<pre>  &lt;input name="someInput" onfocus = "myAutoCompleter.complete(this)"
                          onBind  = "bindHandler(this, event)"
                          onLeave = "leaveHandler"&gt;</pre>

<p>or on the javascript object, as in</p>
<pre>   myAutocompleter.onBind = function(event) {
        bindHandler(event.target, event)
   };
   myAutocompleter.onLeave = leaveHandler;</pre>

<p>Below is the list of events generated by
autocompleter objects.</p>
  <div class="TN_node" id="onBind">
    <h3 class="TN_label">onBind</h3>
    <div class="TN_content">
      <p>This event is triggered whenever the autocompleter object 
becomes associated with an input field; typically this
occurs when the input field receives focus and then
calls the <a href="#autocomplete">/"autocomplete"</a> method.</p>

    </div>
  </div>
  <div class="TN_node" id="onLeave">
    <h3 class="TN_label">onLeave</h3>
    <div class="TN_content">
      <p>This event is triggered whenever the autocompleter object 
cuts the association with an input field; typically this
occurs when the input field loses focus.</p>
<p>If in strict mode, the autocompleter object will also
check if the final value is legal or illegal with respect
to the list of available choices. This may require an
additional Ajax call, so the <code>onLeave</code> event may be
triggered <i>before</i> the <code>onLegalValue</code> or <code>onIllegalValue</code> events.</p>

    </div>
  </div>
  <div class="TN_node" id="onComplete">
    <h3 class="TN_label">onComplete</h3>
    <div class="TN_content">
      <p>[OBSOLETE; use <code>onLegalValue</code> or <code>onIllegalValue</code> instead]</p>
<p>This event is triggered whenever the user has chosen
an item in the displayed suggestion list.
The event handler may use <code>event.index</code> to know the index of the
selected choice.</p>

    </div>
  </div>
  <div class="TN_node" id="onLegalValue">
    <h3 class="TN_label">onLegalValue</h3>
    <div class="TN_content">
      <p>This event is triggered when the autocompleter is in strict mode,
the input field has just been left (<code>onBlur</code> event), and the 
autocompleter was able to verify that the current input value
belongs to the list of available choices.</p>
<p>The event contains a <code>value</code> property (current value in the 
input element), and a <code>choice</code> property (member of the 
<code>choices</code> array that matches the current value).
The <code>controller</code> property is null because the event may
occur after the autocompleter object has been detached from the input
field and has been perhaps already bound to another field, so interacting 
with the autocompleter from the event handler would lead to inconsistencies.</p>

    </div>
  </div>
  <div class="TN_node" id="onIllegalValue">
    <h3 class="TN_label">onIllegalValue</h3>
    <div class="TN_content">
      <p>This event is triggered when the autocompleter is in strict mode,
the input field has just been left (<code>onBlur</code> event), and the 
autocompleter was not able to verify that the current input value
belongs to the list of available choices.</p>
<p>The event only contains a <code>value</code> property (current value in the 
input element). The <code>controller</code> property is null (same reasons
as <code>onLegalValue</code> above).</p>
<p>return <code>true</code> in onIllegalValue handler to override the illegal behavior; i.e. coloring the 
input in red and invalidating the dependentFields.</p>

    </div>
  </div>
  <div class="TN_node" id="onHighlight">
    <h3 class="TN_label">onHighlight</h3>
    <div class="TN_content">
      <p>This event is triggered when a choice in the dropdown list
of choices is highlighted.
The event handler may use <code>event.index</code> to know the index of the
highlighted choice.</p>

    </div>
  </div>
  <div class="TN_node" id="onCancel">
    <h3 class="TN_label">onCancel</h3>
    <div class="TN_content">
      <p>This event is triggered when the user presses the <code>ESCAPE</code> key.</p>

    </div>
  </div>

    </div>
  </div>

</div>
</body>
</html>