Archive | Docs

RSS feed for this section

System Requirements

PHP Autocomplete requires web server that supports PHP 5.3 and higher.

  • PHP 5.3 or later
  • Apache, Tomcat, or Microsoft IIS web server

PHP Autocomplete is prepackaged with required jQuery autocomplete Select2 Javascript libraries and server side components. Developers don’t have to download them separately. PHP Auto complete does not require a database to work.

Installation

First and foremost, download the PHP Autocomplete from the download page, and then extract the zip file in your web server root folder.

In conf.php, simply set PAC_PATH representing the relative or absolute URL to the PHP Autocomplete library.

Assuming phpAutocomplete folder is inside the web root:

define('PAC_PATH','/phpAutocomplete/');

Then include conf.php in on top of the every page.

require_once("../conf.php");

Constructor

PHP Autocomplete constructor takes two parameters and must attach to an existing HTML <select> tag, or a <input type=”hidden”>.

When attached to <input type=”hidden”>, use the second parameter to load from a data array.

Signature:

public function __constructor(string $sel_id, array $data )

Parameters:

  • $sel_id: The id attribute of either <select> or <input type=”hidden”> tag
  • $data: Initial data to load the dropdown (Hidden Input only)

Remark:

  • The $sel_id must have a corresponding <select> or <input type=”hidden”> tag with the exact same id.
  • The $sel_id must be unique

Example 1 (when attached to a <select> tag):

<?php
$pac = new C_PhpAutocomplete('foobar');
$pac -> display('SELECT');
?>
<select id="foobar" multiple>
    <option></option>
    <option id="1">Apple</option>
    <option id="2">Google</option>
    <option id="3">Microsoft</option>
    <option id="4">Facebook</option>
    <option id="5">Twitter</option>
</select>

Example 2 (when attached to a <input type=”hidden”> tag):

<?php
$data = array(array('id'=>1, 'text'=>'Apple'),
              array('id'=>2, 'text'=>'Google'),
              array('id'=>3, 'text'=>'Microsoft'),
              array('id'=>4, 'text'=>'Facebook'),
              array('id'=>5, 'text'=>'Twitter'));
$pac = new C_PhpAutocomplete('foobar');
$pac -> display('INPUT');
?>
<input id="foobar" type="hidden" />

add_event()

Add event handler. A typical use of this method is to pass Select2 event name, then a Javascript event handler function. Note that the generated Javascript methods is injected BEFORE end of $(document).ready(…)

Signature:

public function add_event(param1, param2, ....)

Parameter:

  • variable-length argument lists

A list of supported events:

  • change
  • select2-opening
  • select2-open
  • select2-close
  • select2-highlight
  • select2-selecting
  • select2-removing
  • select2-removed
  • select2-loaded
  • select2-focus
  • select2-blur
  • select2-clearing

Example:

$pac -> add_event('select2-close', 'function() { console.log("close"); }');

disable_search()

Disable search. This essentially removes the search from the dropdown. Disable search makes the control looks like a regular dropdown.

Note that when either set_max_input_length() or set_min_input_length() method is presented, disable_search() is ignored.

Signature:

public function disable_search()

display()

Display the auto-complete control finally. When attached to <select>, set $tag to SELECT, or INPUT when attached to <input type=”hidden”>.This should be the LAST method to call.

Signature:

public function display(string $tag = 'INPUT', bool $script_include = true)

Parameters:

  • $tag: “SELECT” or “INPUT” (default to “INPUT”, case sensitive)
  • $script_include: true or false indicates whether to include required jQuery autocomplete JavaScript libraries (default to true).

enable_closeonselect()

Whether to collapse the dropdown after a selection is made. Allows rapid selection in multi-select mode. Only applies in multi-select mode.

Signature:

public function enable_closeonselect(bool $closeOnSelect = true )

Parameters:

  • $closeOnSelect: Default to true

enable_combobox()

Enable combobox. It is disabled by default. By default, PHP Autocomplete only allows value from existing options in the dropdown. When combobox is enabled, new value can be added to the selection.

Signature:

public function enable_combobox(bool $enable = true )

Parameters:

  • $enable: true or false

enable_readonly()

Set the auto complete control to be read only.

Signature:

public function enable_readonly(bool $readonly = false )

Parameters:

  • $readonly: true or false

set_child()

Set cascading/dependent/nested drop-down. See online example for more details.

Signature:

public function set_child(C_PhpAutocomplete $pac_obj, JavaScript $child_js_dataname )

Parameters:

  • $pac_obj: object
  • $child_js_dataname: variable name that references to data array

set_width()

Set width. Currently height must be adjusted in CSS. In the future release, the height will be also adjustable in this method.

Signature:

public function set_width(Width $w )

Parameters:

  • $w: e.g. “600px”,

enable_dnd_sort()

Drag and drop sorting of multiple selected choices (using JQuery UI sort).The sorting is only available when control is attached to <input type=”hidden”>.

Signature:

public function enable_dnd_sort(bool $sort = false )

Parameters:

  • $sort: true or false

format_results()

Template function to format list of selections that user can select

Signature:

public function format_results($js_format_function, string $frmt_result_css = '' )

Parameters:

  • $js_format_function: JavaScript function to format the selection
  • $frmt_result_css: Function used to add css classes to result elements.

enable_multiple()

Whether or not allows selection of multiple values.When attached to <select> tag this value will be ignored, and <select> multiple attribute will be used instead.

Signature:

public function enable_multiple(bool $multiple = false, integer $max_size = 0)

Parameters:

  • $multiple: True or false
  • $max_size: Maximum selection allowed. 0 = no limit

format_selection()

Template function to format the selection after user chose an option

Signature:

public function format_selection($js_format_function)

Parameters:

  • $js_format_function: JavaScript function to format the selection

load_remote_data()

Load remote JSONP data from URL. The JSON remote data must be an array of of “id”, “text” pair.

For example:

[
   {
      "id":"1",
      "text":"BOBA FETT"
   },
   {
      "id":"2",
      "text":"R2D2"
   },
   {
      "id":"3",
      "text":"JARJAR BINKS"
   }
]

Signature:

public function load_remote_data(URL $url )

Parameters:

  • $url: the remote file that contains the data.

load_data()

Load custom data from an array. The method overwrites any data loaded previously. Must attach to a hidden input field. The remote data is internally converted JSON format.

Example of data array:

$data = array(
           array('id'=>11, 'text'=>'ABC'), 
           array('id'=>22, 'text'=>'OPQ'), 
           array('id'=>33, 'text'=>'XYZ')
           );

Signature:

public function load_data(array $data)

Parameters:

  • $data: – Data array. The remote data must be an array of of “id”, “text” pair.

set_matcher()

Use this method to override how string match is conducted. By default, the PHP Autocomplete matches searched term anywhere in options. In most case, you don’t need to call this method. Keep in mind that only a single matcher can be used.

Signature:

public function set_matcher($js_cust_matcher)

Parameters:

  • $js_cust_matcher: JavaScript function to set custom matcher

Example that demos case sensitive search and must search from the beginning of the string

<?php
...
// only a single matcher can be used at a time
$pac->set_matcher('search_casesensitive_and_beginning');
...
?>
<script>
function search_casesensitive_and_startbeginning(term, text){
    return (text.indexOf(term)>=0)
            &&
            text.toUpperCase().indexOf(term.toUpperCase())==0;
}
</script>

set_max_input_length()

Maximum number of characters that can be entered to start a search. System default is 10 characters.

Signature:

public function set_max_input_length(integer $maximumInputLength = 10)

Parameters:

  • $maximumInputLength: Maximum input length

set_min_input_length()

Minimum number of characters required to start a search. System default is 0 (no minimum restriction).

Signature:

public function set_min_input_length(integer $minimumInputLength = 2)

Parameters:

  • $minimumInputLength: Minimum input length

set_placeholder()

Initial value selected if no other selection is made.

Signature:

public function set_placeholder(string $placeholder = ' ', bool $allowClear = true)

Parameters:

  • $placeholder: Placeholder text, e.g. “Please make a selection:”
  • $allowClear: Whether to display a clear button “x” to clear the select box back to the placeholder value once a selection is made.

set_query()

Use JavaScript function to load data. It can be used to add options dynamically. Applies to <input type=”hidden”> only.

Signature:

public function set_query($query_func)

Parameters:

  • $query_func

set_separator()

Separator character or string used to delimit ids in value attribute of the multi-valued selects. The default delimiter is the “,” character.

Signature:

public function set_separator(mixed $separator)

Parameters:

  • $separator: character(s).

set_sort_results()

Sorting displayed results. Sort the results list for searching before the results are displayed. Useful for sorting matches by relevance to the user’s search term.

Enter “length” to sort by length of characters, or “alpha” to sort alphabetically.

Signature:

public function set_sort_results(mixed $sort_func)

Parameters:

  • $sort_func: custom JavaScript sort function

set_tags()

Select from existing tags or create a new tag. Tags are the simplest form of data where the id is also the text. Take an array representing a list of tags. User can select from existing tags or create a new tag by picking the first choice which is what the user has typed into the search box.

Note that when tagging is enabled the user can select from pre-existing tags or create a new tag by picking the first choice which is what the user has typed into the search box so far.

Signature:

public function set_tags(array $tags, array $tokenSeparators)

Parameters:

  • $tags: Array
  • $tokenSeparators: An array of strings that define token separators.

set_init_selection()

Set initial selected value during page load. It can be a single or multiple values. The parameter must be an object array. You can also call readonly and enable properties with this method. See example for usage detail.

Signature:

public function set_init_selection(array $val)

Parameters:

  • $val: – An object array