view release on metacpan or  search on metacpan

lib/Alien/GvaScript/AutoCompleter.pod  view on Meta::CPAN

Inline object that specifies dependencies between the field
controlled by the autocompleter, and other fields in the same form.
When leaving the autocompleted field (C<onBlur>), the dependent fields
will be updated automatically. This only works for autocompleters
in strict mode.

Each key in the inline object specifies the name of a field related
to the autocompleted field. If field names are in dotted notation, 
then the related field is taken as a path relative to the autocompleted
field : so for example if the autocompleted field has name
C<some.very.3.long.2.path>, then the C<foo> entry in
C<dependentFields> will refer to field C<some.very.3.long.2.foo>.


The corresponding value (in our example above: C<firstname>) is
the name of a property to extract from the C<choice> member
that validated the current input. However, the autocompleted field
may also contain an empty value (in which case the related fields
are also emptied), or an illegal value (in which case the related
fields are filled with string C<ILLEGAL_***>, where C<***> is the 
key from the inline object).

If the C<choice> member is not an object, but just a string,
then that string is copied to the dependent field, therefore ignoring
the hash value (C<firstname> in our example).

As a special case, if the hash value is an empty string,
then the dependent field is emptied, ignoring whatever
information may be in the C<choice> element.


The dependent fields structure might also be specified as
an HTML attribute C<ac:dependentFields>, instead of an option 
to the Javascript object :

  <input name="some.very.3.long.2.path"
         onfocus="ac.autocomplete(this)"
         ac:dependentFields="{foo:'firstname',bar:'lastname',id:'id'}" />
  ...
  <input type="hidden"
         name="some.very.3.long.2.id" />



=back

=head1 METHODS

=head2 autocomplete(inputField)

Returns an event handler to be bound to the C<onfocus> event on
an input field, i.e.

  <input name="someInput" onfocus="myAutoCompleter.complete(this)">

The autocompleter will automatically register 
C<onblur>, C<onclick> and C<onkeydown> handlers on the same field, so avoid
setting your own, which may cause unpredictable interactions.
However the autocompleter has its own event model 
to which you can bind your handling code
(see the L<EVENTS> section below).

=head2 detach(inputField)

Permanently detaches the input field from the autocompleter object
(i.e. removes C<onblur> and C<onkeypress> handlers
that were previously set by the first invocation of the 
C<autocomplete> method).

=head2 displayMessage(messageText)

Displays the given message within 
a newly created dropdown DIV under the input field.
Used internally to warn for example about illegal values.


=head1 EVENTS

For a general explanation on registering handlers
for GvaScript events, see the L<event> documentation.
In short, you can register handlers either on the 
HTML input element, as in 

  <input name="someInput" onfocus = "myAutoCompleter.complete(this)"
                          onBind  = "bindHandler(this, event)"
                          onLeave = "leaveHandler">

or on the javascript object, as in 

   myAutocompleter.onBind = function(event) {
        bindHandler(event.target, event)
   };
   myAutocompleter.onLeave = leaveHandler;

Below is the list of events generated by
autocompleter objects.

=head2 onBind

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 L</"autocomplete"> method.

=head2 onLeave

This event is triggered whenever the autocompleter object 
cuts the association with an input field; typically this
occurs when the input field loses focus.

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 C<onLeave> event may be
triggered I<before> the C<onLegalValue> or C<onIllegalValue> events.


=head2 onComplete

[OBSOLETE; use C<onLegalValue> or C<onIllegalValue> instead]

This event is triggered whenever the user has chosen
an item in the displayed suggestion list.
The event handler may use C<event.index> to know the index of the
selected choice.


=head2 onLegalValue

This event is triggered when the autocompleter is in strict mode,
the input field has just been left (C<onBlur> event), and the 
autocompleter was able to verify that the current input value
belongs to the list of available choices.

The event contains a C<value> property (current value in the 
input element), and a C<choice> property (member of the 
C<choices> array that matches the current value).
The C<controller> 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.

=head2 onIllegalValue

This event is triggered when the autocompleter is in strict mode,
the input field has just been left (C<onBlur> event), and the 
autocompleter was not able to verify that the current input value
belongs to the list of available choices.

The event only contains a C<value> property (current value in the 
input element). The C<controller> property is null (same reasons