Download source - 3.

05 Kb

Introduction
Most auto-complete textboxes may have a reverse effect on end-users. Instead of
helping them get things done faster, they get irritated by design flaws made by the
programmer. (Admittedly, I've made such design flaws too.)

I got to learn this lesson when designing my first auto-complete edit control, found
here[^]. Although it seemingly looks intuitive, I forgot to consider the fact that what
if the end-user wanted to type just 'ap' but the 'ple' appears out of nowhere? This
means that the end-user would then have to hunt for, and press the delete key.

After seeing how GMail made its auto-complete, I took the idea and implemented
my own version of the auto-complete control.

Auto-complete textbox control:

Timeout: 3000ms
Deliminator: ; and ,
Options: ('an apple','alligator','elephant','pear','kingbird','kingbolt',
'kingcraft','kingcup','kingdom','kingfisher','kingpin')

How does it work?

The important event that will fire whenever the user press any key is onkeydown.
The onkeydown event handles all the normal character input and is in charge of
creating the auto-complete list. It also handles keys like 'up', 'down' and 'enter'.

Using the JavaScript regexp() object, the script will run through the array
containing the keywords and match them one by one. After which, a DIV will be
created dynamically using document.createElement(). Finally, when the user
presses the 'Enter' key, the DIV will be detached and the input box updated.

The user can also select the options using the mouse. This is done through a three
events: onmouseover, onmouseout, and onclick.

How do you implement it into your own textbox?

Firstly, include the .js file into your script:

<script language="javascript" type="text/javascript"

src="actb.js"></script>

Next, create an array (in JavaScript) containing the keywords:

customarray = new Array('apple','pear','mango','pineapple',

'orange','banana','durian', 'jackfruit','etc');

Apply the widget to your using javascript:

actb(document.getElementById('textbox_id'),customarray);

And you're done!

Tweakability
This auto-complete edit control has some customizable features:

/* ---- Variables ---- */

this.actb_timeOut = -1; // Autocomplete Timeout in ms (-1: autocomplete never time out)
this.actb_lim = 4; // Number of elements autocomplete can show (-1: no limit)
this.actb_firstText = false; // should the auto complete be limited to the beginning of keyword?
this.actb_mouse = true; // Enable Mouse Support
this.actb_delimiter = new Array(' ',','); // Delimiter for multiple autocomplete. Set it to empty array for single autocomplete
this.actb_startcheck = 1; // Show widget only after this number of characters is typed in.
/* ---- Variables ---- */

/* --- Styles --- */

this.actb_bgColor = '#888888';
this.actb_textColor = '#FFFFFF';
this.actb_hColor = '#000000';
this.actb_fFamily = 'Verdana';
this.actb_fSize = '11px';
this.actb_hStyle = 'text-decoration:underline;font-weight="bold"';
/* --- Styles --- */

this.actb_keywords = new Array();

The styles are pretty self-explanatory; tweak the values for best results for your own
website. Firstly, the variable actb_timeOut controls how long the auto-complete
list's timeout should be (i.e., after x ms, the list will disappear). By default, it is set
to -1, which represents no timeout.

Next, the variable actb_lim limits the number of elements the list will show, to
prevent over-spamming. If you do not want to set any limit, set it to -1.

Thirdly, the actb_firstText variable determines whether the match with the
keywords-array should only start from the first character or if the match can be any
arbitrary match within the keyword. For example, if firstText is set to true, then a
given string "ello" will match with "hello".

Also, the actb_mouse variable determines whether the control should respond to
mouse events. Mouse support works when user clicks on the auto-complete list that
appears.

The actb_delimiter variable allows for the much requested multiple auto-
complete feature. Set a custom delimiter, or even multiple delimiters, like semi-
colon (;) or comma (,), and the engine will complete words separated by the given
delimiter.

Lastly, actb_startcheck controls the number of characters that must be typed in

before the textbox will display the control. Thanks to flyasfly for this suggestion.

Implementations
As of version 1.3, all of the above mentioned are public variables. This can be
useful in emulating controls like Google Suggest. When you apply the control to
your textbox using the actb function, it returns an object.

Changing the autocomplete list

obj = actb(document.getElementById('textbox_id'),customarray);
// ... after some time ...
obj.actb_keyword = new Array('this','is','a','new','set','of','keywords');

Multiple auto-complete textboxes

obj = new actb(document.getElementById('textbox_id'),customarray);

obj2 = new actb(document.getElementById('textbox2_id'),customarray2);

Multiple textboxes (different options)

obj = new actb(document.getElementById('textbox_id'),customarray);

obj.actb_mouse = false; // no mouse support
obj2 = new actb(document.getElementById('textbox2_id'),customarray2);
obj2.actb_startcheck = 2; // start actb only after 2nd character

Todo
Add second array (customarrayDesc) for display desciption in the list (ex =>
[an apple : it's an apple] instead of [an apple]. Suggestion by angelo77
Many other features suggested by CPians, some of which might be beyond
me at the moment but I'll still try my best!

Tested browsers
Internet Explorer 6.0.28
Mozilla Firefox version 1.0.3

Finally...
Thank you to all of you who has supported, modified, and offered your suggestions
to the control! I'm extremely apologetic for the inactiveness of this project because
of schoolwork etc. However, I still try my best to work on it whenever anyone has a
new feature request!

License
This control will be, from effect of version 1.1, published under Creative Common
License [^]

Change Log
1.31: 12/5/2005
Fix: Fix a bug with actb_bgColor styles due to typo
Fix: Now caret does not move away (firefox) when user presses enter
or tab
1.3: 8 May 2005
Added: actb_startcheck the number of characters that start the widget
contro. Thanks to flyasfly for suggestion
Change: All 'tweakabilities' and styles have been changed to public
variable.
Fix: Fixed an IE-specific bug which prevents the caret position of
textarea to be retrieved. Now widget works for textarea too.
1.2: 9 Apr 2005
Change: Converted the code of actb widget to OOP
Fix: Mouse click bug that disallow autocomplete control from deleting
itself
Added: the keywords array ( actb_keyword) becomes a public variable,
so it can be modified from the parent script
1.1: 6 Dec 2004
Fix: Metacharacters escaped before parsing with RegExp
Added: Multiple Delimiter
Added: Tab now completes the text like enter
Change: Now, only an event is needed for control to work; the rest are
attached dynamically.
Fix: Bugs with caret position in Firefox: originally, 'up' and 'down' keys
will change caret position in the textbox for firefox. This problem has
been rectified.
1.0: 23 Nov 2004
Fix: some miscellaneouss bugs in mouse support ( actb_removedisp()
cannot be executed properly)
Fix: actb_timeout now works fine with mouse support on
Added: When user moves the mouse over each individual option, the
options will be highlighted.
Added: Multiple auto-complete! This works even if you're editing
previous "fields".
0.9: 6 Oct 2004
Fix: A bug concerning clientHeight which apparently Mozilla does
not support. Thanks Cameron Smith for pointing out.
Added: This control now supports phrases with spaces in between.
Thanks to Miguel Vieira.
Added: This control has mouse support. Thanks to Alecacct and
everyone for the idea.
18 Aug 2004
Basic engine created
Article posted!