By default the user can enter any input that he wants. Entering text will filter down the suggestions to the available matches. When set to false, this parameter either restricts the user to the given suggestions (in which case pressing ENTER will not trigger anything). When set to true, this parameter allows the user to enter custom entries and have them be added to his selected values.

Example with allowFreeEntries set to false:

$('#ms-allowFreeEntries').magicSuggest({
  allowFreeEntries: false,
  data: ['Paris', 'New York', 'Gotham']
});
              

By default the user cannot enter the same value twice. When set to true, each value can be entered multiple times.

Example with allowDuplicates set to true:

$('#ms-allowDuplicates').magicSuggest({
  allowDuplicates: true,
  data: ['Paris', 'New York', 'Gotham']
});
              

The component uses jQuery's underlying $.ajax() method that can be further configured by passing this property. This is useful for example when one needs to add converters or perform cross-site requests.

Example with ajaxConfig set to add xhrFields field:

$('#ms-ajaxConfig').magicSuggest({
  data: 'http://nicolasbize.com/magicsuggest/get_cities.php',
  ajaxConfig: {
    xhrFields: {
      withCredentials: true,
    }
  }
});
              

As the user types in the combo, the combo's contents will most likely end up displaying a single suggestion. This parameter will automatically add it to the selection when Enter is pressed. When set to false, the user has to use the keyboard arrows or the mouse to make his selection.

Example with autoSelect set to false :

$('#ms-autoSelect').magicSuggest({
  autoSelect: false,
  allowFreeEntries: false,
  data: ['Paris', 'New York', 'Gotham']
});
              

From jQuery's doc: A pre-request callback function that can be used to modify the XMLHTTPRequest object before it is sent.
Use this to set custom headers, etc. The jqXHR and settings objects are passed as arguments. This is an Ajax Event.
Returning false in the beforeSend function will cancel the request Defaults to function(){ }

Example with beforeSend set to cancel the request :

$('#ms-beforeSend').magicSuggest({
  data: 'wrong_url.php',
  beforeSend: function(xhr, settings) {
    return false;
  }
});
              

When the MagicSuggest component is rendered, the input field is surrounded with a div container that has a base class called ms-ctn. By specifying a custom class, it will be put next to the ms-ctn specifications, thus enabling you to override the base CSS settings.

Example with cls set to custom to render a blue combo with a flat square style :

/** Custom style to place in a CSS declaraction **/
.custom, .custom input {
  color: blue;
  background: #ECEEFF !important;
  border-radius: 0 !important;
}

$('#ms-cls').magicSuggest({
  cls: 'custom'
});
              

MagicSuggest's combo is filled with JSON records that have at least a name and an id. The records can hold as many information as you need, but by default the component displays some text and associates a value to it. The data parameter is there to provide the necessary info to fill up the combo as the user searches through suggestions. Expected value formats for the parameter include:

• An array of strings, such as ['Paris', 'New York']

  Note that in this case, no id is specified. MagicSuggest will generate ids equal to the given names, with the risk of having duplicate ids. Hence the previous code is equivalent to data: [{"id":"Paris", "name":"Paris"}, {"id":"New York", "name":"New York"}].

• An array of JSON objects, such as [{"id":0, "name":"Paris"}, {"id":1, "name":"New York"}]

  Note that Object Literal Notation is also accepted: [{id:0, name:"Paris"}, {id:1, name:"New York"}]

• A JSON object containing its data within the results property: {"results": [{"id":0, "name":"Paris"}, {"id":1, "name":"New York"}]}

  Note that Object Literal Notation is also accepted: {"results": [{id:0, name:"Paris"}, {id:1, name:"New York"}]}
  This can be useful when you wish to pass other variables along the provided data.

The data can be provisionned in a static way or in a dynamic way:

• No Data (default value)

  When left blank, the combo box will not suggest anything. This can be useful if you want to provide a custom tags box where the user can enter as many custom tags as he wants. In that case make sure that allowFreeEntries is set to true (default value).

• Static Source

  A static source will remain the same during the lifespam of the component. Simply pass one of the expected value format as a value to the data property.

• Dynamic Source: Url

  By providing a URL for the data property, MagicSugest will perform an ajax request to retrieve the data necessary to populate the combo box. The request will include a query parameter containing the text that the user has typed, thus giving the server enough information to send back narrowed results. Make sure the results match one of the expected value format.

• Dynamic Source: Function

  You can pass a function which will be called everytime the component needs to fetch the data to fill the combo.
  The function can include an argument which will contain the text that the user has typed (same as query for ajax)

$('#ms-data-no-data').magicSuggest({});

$('#ms-data-static-data').magicSuggest({
  data: [{"id":0, "name":"Paris"}, {"id":1, "name":"New York"}]
});

$('#ms-data-ajax').magicSuggest({
  data: 'get_cities.php'
});

$('#ms-data-function').magicSuggest({
  data: function(q){
    var e = q || '', r=[], c = ['Paris', 'New York', 'Gotham'];
    for(var i=0; i<c.length; i++){
      if(c[i].toLowerCase().indexOf(e.toLowerCase()) > -1)
        r.push({id: i, name: c[i]});
    }
    return r;
  }
});
              

When performing an ajax call through the data's specified URL, MagicSuggest will pass a base parameter called query containing the current text entered by the user. All parameters and values specified in the dataUrlParams will also be passed along. This can be especially useful in a form if the combo's suggestions depend upon a prior field.

Example with dataUrlParams set to pass out some random info :

$('#ms-dataUrlParams').magicSuggest({
  data: 'get_cities.php',
  dataUrlParams: { id: 34 }
});
              

When disabled, the user is not able to change the combo's selection or to interact with the component.

Example with disabled set to true :

$('#ms-disabled').magicSuggest({
  data: ['Paris', 'New York', 'Gotham'],
  disabled: true
});
              

When specified, each record may have that specific property that triggers a disabled item if set to true.

Example with disabledField set to a newly given 'disabled' property in the JSON results:

$('#ms-disabledField').magicSuggest({
  data: [{id:0, name:'Male', disabled: true}, {id:1, name:'Female'}],
  disabledField: 'disabled'
});
              

When providing records to the combo, the component needs to know which object property to display. This property allows you to specify a custom record property.

Example with displayField set to gender :

$('#ms-displayField').magicSuggest({
  data: [{id:0, gender:'Male'}, {id:1, gender:'Female'}],
  displayField: 'gender'
});
              

When set to false, the user can only make selections by clicking on the combobox or its right trigger. Setting this setting to false will set expandOnFocus's default to true.

Example with editable set to false :

$('#ms-editable').magicSuggest({
  data: ['Paris', 'New York', 'Gotham'],
  editable: false
});
              

When set to true, the combo will be expanded as soon as its data is loaded upon startup.

Example with expanded set to true :

$('#ms-expanded').magicSuggest({
  data: ['Paris', 'New York', 'Gotham'],
  expanded: true
});
              

When set to true, the combo will be expand when clicked upon or when focus is gained through keyboard's tab. Also, because the focus is kept when making a selection, the combo will stay expanded until the focus is lost. This is useful when the user needs to make several selections fast.

Example with expandOnFocus set to true :

$('#ms-expandOnFocus').magicSuggest({
  data: ['Paris', 'New York', 'Gotham'],
  expandOnFocus: true
});
              

MagicSuggest allows the combo's contents to be grouped by categories. The records that need to be grouped should contain their category as a property. Look at data.json and data-groupby.json to see an example of the data passed to the component.

Example with groupBy set to 'country' :

$('#ms-groupBy').magicSuggest({
  data: 'data.json',
  groupBy: 'country'
});
$('#ms-groupBy2').magicSuggest({
  data: 'data-groupby.json',
  groupBy: 'country.name'
});
              

When hiding the trigger, the combo becomes expanded when:

• the user starts typing in the combo or uses the up/down arrow
• the combo gains focus and expandOnFocus is set to true

Example with hideTrigger set to true :

$('#ms-hideTrigger').magicSuggest({
  data: 'data.json',
  hideTrigger: true
});
              

As the combo's contents get filtered as the user types what he is looking for, highlighting helps the user visually see why the combo's choices are there. This default setting can be turned off using this parameter.

Example with highlight set to false :

$('#ms-highlight').magicSuggest({
  data: 'data.json',
  highlight: false
});
              

If you need to access the component from anywhere in the code, you can give it its own id. This enables you to call upon it to retrieve its properties / methods / events after the component has been created.

Example with id set to 'my-custom-id' :

var myCustomId = $('#ms-id').magicSuggest({
  data: ['Paris', 'New York', 'Gotham'],
  id: 'my-custom-id'
});
$($('#my-custom-id').magicSuggest()).on(
  'selectionchange', function(e, cb, s){
     alert(s);
  }
);
              

MagicSuggest includes a tiny information text that is displayed on the top-right corner of the component. While this text can be hidden / disabled, it can be a great helper for the user to understand or see live-validation of his choices. infoMsgCls enables you to customize the way that it looks.

Example with infoMsgCls set to custom :

$('#ms-infoMsgCls').magicSuggest({
  data: ['Paris', 'New York', 'Gotham'],
  infoMsgCls: 'custom'
});
              

Some external libraries such as AngularJS require the input fields to be configured in a particular way. This parameter allows additional parameters which will be passed down to the input dom element.
It is advised to pass JSON and not just Object Literal Notation for this parameter.

Example with inputCfg set to {"ng-model":"customer.city"} :

$('#ms-inputCfg').magicSuggest({
  data: ['Paris', 'New York', 'Gotham'],
  inputCfg: {"ng-model":"customer.city"}
});
              

When the method validate is called, the container style can be modified through the use of a custom class appended only when the validation fails.

Example with invalidCls set to {"ng-model":"customer.city"} :

$('#ms-invalidCls').magicSuggest({
  data: ['Paris', 'New York', 'Gotham'],
  required: true,
  invalidCls: 'custom'
});
              

When mode is set to local, MagicSuggest takes care of filtering the records to display. This parameter sets the case sensitivity for that filtering process.

Example with matchCase set to true :

$('#ms-matchCase').magicSuggest({
  data: ['Paris', 'New York', 'Gotham'],
  matchCase: true
});
              

The size is set in pixels. Once expanded, the combo's height will try and take as much room as possible to display all of its records. In case there are too many results displayed, this parameter will limit the given size.

Example with maxDropHeight set to 145 px :

$('#ms-maxDropHeight').magicSuggest({
  data: 'data.json',
  maxDropHeight: 145
});
              

When allowFreeEntries is set to true, this parameter will limit the size in characters of an entry that can be set by the user. Set to null if you do not want any limit.

Example with maxEntryLength set to 5 :

$('#ms-maxEntryLength').magicSuggest({
  maxEntryLength: 5
});
              

A helper message is displayed when the user goes beyond the maxEntryLength parameter. The message is defined by a function that takes the entry as its only argument.
Defaults to function(v){ return 'Please reduce your entry by ' + v + ' character' + (v > 1 ? 's':'');}

Example with maxEntryRenderer set to display a friendlier message :

$('#ms-maxEntryRenderer').magicSuggest({
  maxEntryLength: 5,
  maxEntryRenderer: function(v) {
    return 'TOO LONG DUMMY!!';
  }
});
              

Because data may hold thousands of records, you may want to restrict the maximum amount of items displayed in the combo, thus making its scrollbar usable. Note that while the items are not all shown in the combo, they are still kept in memory and can be accessed or displayed if the contents is being filtered.

Example with maxSuggestions set to 10 :

$('#ms-maxSuggestions').magicSuggest({
  data: 'data.json',
  maxSuggestions: 3
});
              

Set this to 1 to get the behaviour of a classic combo box. Set this to null to remove the limit. Once the limit has been reached, a message specified by maxSelectionRenderer will be displayed in the helper section to notify the user.

Example with maxSelection set to 3 :

$('#ms-maxSelection').magicSuggest({
  maxSelection: 3
});
              

• Set to get to include the query parameters in the URL of a GET request.
• Set to post to include the query parameters in the message body of a POST request.

Example with method set to get :

$('#ms-method').magicSuggest({
  method: 'get',
  data: 'get_cities.php'
});
              

When there is a lot of data, filtering and sorting may take some time so it may sometimes be wise to ask for a couple of characters before processing and displaying the results.

Example with minChars set to 2 :

$('#ms-minChars').magicSuggest({
  minChars: 2,
  data: 'data.json'
});
              

A helper message is displayed when the user needs to type more characters before seeing any results into the combo. The message is defined by a function that takes the entry as its only argument.
Defaults to function(v){ return 'Please type ' + v + ' more character' + (v > 1 ? 's':'');}

Example with minCharsRenderer set to display a heroic message :

$('#ms-minCharsRenderer').magicSuggest({
  minChars: 2
  minCharsRenderer: function(v){
    return 'Be more precise Spiderman!!';
  },
  data: 'data.json'
});
              

When this component is included in a form, its value is passed along with other form components to be processed by the server. This parameter allows you to identify the resources in the post or get request that is done on the server. Because the component allows for multiple selections, it behaves just like a checkbox input element. Therefore, the real name used is in the form of an array like fruits[]. You may pass your string in the form cities or cities[], the hidden inputs that behave like checkboxes will have cities[] for name.

Example with name set to tags :

$('#ms-name').magicSuggest({
  name: 'tags'
});
              

When the user starts typing inside the combo, its content is being filtered (either server or client side, see mode). When no match is found, the helper is updated with this parameter. The default value is 'No suggestions'. Note that you can use {{query}} to reflect the user input, as shown in the example.

Example with noSuggestionText set to 'No result matching the term [...]' :

$('#ms-noSuggestionText').magicSuggest({
  noSuggestionText: 'No result matching the term {{query}}',
  data: ['Paris', 'New York', 'Gotham']
});
              

When no selection has been performed, the combo will display this string. Set to '' if you do not wish to see any strings placed.

Example with placeholder set to 'Make a selection' :

$('#ms-placeholder').magicSuggest({
  placeholder: 'Make a selection',
  data: ['Paris', 'New York', 'Gotham']
});
              

This parameter allows you to customize the name of the parameter sent to the server whose value is the current input string as entered by the user.

Example with queryParam set to 'q' :

$('#ms-queryParam').magicSuggest({
  queryParam: 'q',
  data: 'get_cities.php'
});
              

This parameter allows you to customize the way that the combo items are presented. You may pass a function whose parameter will be the current suggestion value. Make sure to render a proper closure in the given HTML or you will break the combo's DOM layout.

Example with renderer set to display the country's flag in front of the city names :

$('#ms-renderer').magicSuggest({
  renderer: function(data){
    var file = data.country === 'France' ? 'fr.png' : 'us.png';
    var img = 'assets/images/' + file;
    return '<img class="i" src="' + img + '"/>' + data.name;
  },
  allowFreeEntries: false,
  data: 'data.json'
});
              

When set to true, the validation performed on the component will return false if no selection has been made.

Example with required set to true :

$('#ms-required').magicSuggest({
  required: true
});
              

To get a look that is cleaner and ressembling a regular textbox, this option will change the DOM used to render the selected items and render them as a single string separated by default by commas (see resultAsStringDelimiter) when the component looses its focus.

Example with resultAsString set to true :

$('#ms-resultAsString').magicSuggest({
  resultAsString: true,
  data: 'data.json'
});
              

When displaying the results as a string, this parameter specifies how each result element is delimited.
By default, it is a comma-separated values like the GMail recipients combo box.

Example with resultAsStringDelimiter set to ';' :

$('#ms-resultAsStringDelimiter').magicSuggest({
  resultAsStringDelimiter: ';',
  resultAsString: true
});
              

When data is given a JSON object (and not array), the component needs to know which property to inspect for its data. This parameter allows you to specify where to look in the object.

Example with resultsField set to cities :

$('#ms-resultsField').magicSuggest({
  resultsField: 'cities',
  data: 'object.json'
});
              

When set to true, the combo's keyboard cursor will automatically select the first element when multiple elements are returned. This allows the user to quickly hit Enter after his search query.

Example with selectFirst set to true :

$('#ms-selectFirst').magicSuggest({
  selectFirst: true,
  resultsField: 'cities',
  data: 'object.json'
});
              

Current selections are made to look like tags with a small deletion button in the form of an x. This property lets you customize they way that each selected item is being rendered.

Example with selectionCls set to 'custom' :

$('#ms-selectionCls').magicSuggest({
  selectionCls: 'custom',
  data: ['Paris', 'New York', 'Gotham']
});
              

Specifies where the selection is rendered. When not specified, the selection is rendered in a newly created DOM element according to selectionPosition

Example with selectionContainer set to $('#custom-ctn') :

$('#ms-selectionContainer').magicSuggest({
  selectionContainer: $('#custom-ctn'),
  data: ['Paris', 'New York', 'Gotham']
});
              

Either 'right', 'bottom' or 'inner' are accepted values. This parameter specifies where the selection should be rendered.

Example with selectionPosition set to 'bottom' :

$('#ms-selectionPosition').magicSuggest({
  selectionPosition: 'bottom',
  data: ['Paris', 'New York', 'Gotham']
});
              

Besides adding a CSS class with selectionCls, you can also change the generated DOM for each item. This allows you to display additional information or customize the rendered item any way you want.

Example with selectionRenderer set to show the country flag :

$('#ms-selectionRenderer').magicSuggest({
  selectionRenderer: function(data){
    var file = data.country === 'France' ? 'fr.png' : 'us.png';
    var img = 'assets/images/' + file;
    return '<img class="i" src="' + img + '"/>' + data.name;
  },
  allowFreeEntries: false,
  data: 'data.json'
});
              

Useful when you have limited horizontal space, such as on a sidebar filter for example. Note that this requires selectionPosition to be set to either 'bottom' or 'right'.

Example with selectionStacked set to true :

$('#ms-selectionStacked').magicSuggest({
  selectionStacked: true,
  selectionPosition: 'bottom',
  data: 'data.json'
});
              

The parameter only accepts values 'asc' and 'desc'. When mode is set to 'manual', the component takes care of sorting and filtering data. This parameter changes the way that the data is sorted.

Example with sortDir set to 'desc' :

$('#ms-sortDir').magicSuggest({
  sortDir: 'desc',
  sortOrder: 'name',
  data: 'data.json'
});
              

When given JSON objects in the data parameter, and with the mode set to 'local', the component will attempt to sort the given data. This property allows the data to be sorted according to any given property found on all JSON results.

Example with sortOrder set to 'name' :

$('#ms-sortOrder').magicSuggest({
  sortOrder: 'name',
  data: 'data.json'
});
              

The default behaviour is to look throughout all entries to see if it contains, as a substring, the input entered by the user. This parameter ensures that the entries suggested start with the given input.

Example with strictSuggest set to true :

$('#ms-strictSuggest').magicSuggest({
  strictSuggest: true,
  data: ['Henry Ford', 'Thierry Henry', 'Harrison Ford']
});
              

While you can add custom classes using the cls parameter, you may also add inline style using this parameter. The style is applied to the component's container (ie. what looks like a regular bootstrap textbox)

Example with style set to make the border in a straight angle:

$('#ms-style').magicSuggest({
  style: 'border-radius: 0 !important',
  data: ['Paris', 'New York', 'Gotham']
});
              

When set to true, the combo will expand no matter where the user clicks on the combobox. This is useful if you do not allow the user to type in the combo using the editable property.

Example with toggleOnClick set to true:

$('#ms-toggleOnClick').magicSuggest({
  toggleOnClick: true,
  data: ['Paris', 'New York', 'Gotham']
});
              

To prevent the component from making too many queries, it waits for some time after the user's last keypress to send the AJAX request. You can actually set this parameter to 0 if you do not want the component to wait. In that case, it will make one query everytime a key is pressed within the component.

Example with typeDelay set to 0:

$('#ms-typeDelay').magicSuggest({
  typeDelay: 0,
  data: 'get_cities.php'
});
              

By setting this parameter to true, the tab key will not loose the focus but will add a selection made by the user to the current selections.

Example with useTabKey set to true:

$('#ms-useTabKey').magicSuggest({
  useTabKey: true
});
              

By setting this parameter to true, the , key will add a selection made by the user to the current selections.

Example with useCommaKey set to true:

$('#ms-useCommaKey').magicSuggest({
  useCommaKey: true
});
              

While set to true, odd lines will be given the additional class ms-res-odd which by default is a darker gray to have lines stand out better.

Example with useZebraStyle set to true:

$('#ms-useZebraStyle').magicSuggest({
  useZebraStyle: true,
  data: 'data.json'
});
              

Because the component generates an array of values, it expects an array of values as well. Make sure that valueField is properly set if the value field in your JSON records is different than id.

Example with value set to match the hottest places:

$('#ms-value').magicSuggest({
  value: [1,7,16,19],
  data: 'data.json'
});
              

When providing records to the combo, the component needs to know which object property to take as value. This property allows you to specify a custom record property.

Example with valueField set to 'name':

var ms = $('#ms-valueField').magicSuggest({
  valueField: 'name',
  data: 'data.json'
});
$(ms).on(
  'selectionchange', function(e, cb, s){
     alert(cb.getValue());
  }
);
              

You can add a custom regular expression to tell the component which entries should be considered valid or not. This is useful if your entries do not validate against a classic vtype

Example with vregex set to only accept values that have 1-5 chars:

var ms = $('#ms-vregex').magicSuggest({
  vregex: /^[a-z0-9_-]{1,5}$/
});
$(ms).on(
  'selectionchange', function(e, cb, s){
     alert("valid: " + this.isValid());
  }
);
              

Accepted values are: alpha, alphanum, email, url, ipaddress.

Example with vtype set to only accept ip addresses:

var ms = $('#ms-vtype').magicSuggest({
  vtype: 'ipaddress'
});
$(ms).on(
  'selectionchange', function(e, cb, s){
     alert("valid: " + this.isValid());
  }
);
              

This method adds one or multiple items to the current selection.

• objs can either be an array of JSON records or an array of values. In the case of values, make sure that the component is aware of what records these values correspond to.
• silent can shut off the triggered events as elements are being added to the combo.

Example with addToSelection set to add a couple of items to the initial value:

var ms = $('#ms-addToSelection').magicSuggest({
  data: 'data.json',
  value: [1,2]
});
ms.addToSelection([3,4,5]);
              

This method empties the component's selection.

• silent can shut off the triggered events as elements are cleared.

Example with clear set to clear the initial values:

var ms = $('#ms-clear').magicSuggest({
  data: 'data.json',
  value: [1,2]
});
ms.clear();
              

This method collapses the combo if it is expanded.

• silent can shut off the triggered events as the combo is collapsed.

Example with collapse set to collapse the collapse a combo that was initialized expanded:

var ms = $('#ms-collapse').magicSuggest({
  data: ['Paris', 'New York', 'Gotham'],
  expanded: true
});
ms.collapse();
              

This method disables the combo.

Example with disable:

var ms = $('#ms-disable').magicSuggest({});
ms.disable();
              

This method clears the value contained in the input tag.

Example with empty performed whenever a key is typed:

var ms = $('#ms-empty').magicSuggest({});
$(ms).on('keyup', function(){
  this.empty();
});
ms.empty();
              

This method enables a component that might have been in a disabled state.

Example with enable performed at startup:

var ms = $('#ms-enable').magicSuggest({
  disabled: true
});
ms.enable();
              

This method expands a component that might have been in a disabled state.

Example with expand performed at startup:

var ms = $('#ms-expand').magicSuggest({});
ms.expand();
              

This method returns all the suggestions contained in the combo box.

Example with getData upon selection:

var ms = $('#ms-getData').magicSuggest({
  data: ['Paris', 'New York', 'Gotham']
});
$(ms).on('selectionchange', function(){
  alert(JSON.stringify(ms.getData()));
});
              

This method isDisabled returns wheter or not the component is in a disabled state.

Example with isDisabled performed at startup:

var ms = $('#ms-isDisabled').magicSuggest({
  disabled: true,
  data: ['Paris', 'New York']
});
if(ms.isDisabled()){
  ms.setValue(['Paris']);
}
              

This method checks if each entry given by the user is valid. The field is invalid if any item is invalid (ie. not matching a vtype or vregex, or it is empty even though it is marked as required)

Example with isValid performed whenever the user adds custom email addresses:

var ms = $('#ms-isValid').magicSuggest({
  vtype: 'email'
});
$(ms).on('selectionchange', function(){
  alert("valid: " + this.isValid());
});
              

This method simply returns the parameters that the component sends on each AJAX request.

Example with getDataUrlParams performed at startup:

var ms = $('#ms-getDataUrlParams').magicSuggest({
  dataUrlParams: {id: 3}
});
$(ms).on('selectionchange', function(){
  alert(this.getDataUrlParams().id);
});
              

This method checks if each entry given by the user is valid.

Example with getName performed whenever the user selects a city:

var ms = $('#ms-getName').magicSuggest({
  name: 'cities',
  data: 'data.json'
});
$(ms).on('selectionchange', function(){
  alert("name:" + this.getName());
});
              

The objects passed to the component through the data parameter (whether static or through a dynamic AJAX call) are stored within the component. Whenever the user selects an item within the combo, it becomes part of the user selection. Those items can be retrieved using this method and then serialized before being sent to the server.

Example with getSelection performed whenever the user selects a city:

var ms = $('#ms-getSelection').magicSuggest({
  data: 'data.json'
});
$(ms).on('selectionchange', function(){
  alert(JSON.stringify(this.getSelection()));
});
              

The visual component is always made of a container with seperate DOMs for the user selection and what he is currently entering on his keyboard. This method returns the value contained into that input element.

Example with getRawValue performed when a word gets too long:

var ms = $('#ms-getRawValue').magicSuggest({});
$(ms).on('keyup', function(){
  if(ms.getRawValue().length > 4){
    alert("it's too big!");
  }
});
              

While getSelection() returns an array containing the full objects, this method only returns the value as defined by the valueField property.

Example with getValue performed whenever someone makes a selection:

var ms = $('#ms-getValue').magicSuggest({
  data: 'data.json'
});
$(ms).on('selectionchange', function(){
  alert(JSON.stringify(this.getValue()));
});
              

Removes one or multiple JSON objects from the current selection. Set boolean to true if you don't want the component to trigger an event when performing that change.

Example with removeFromSelection performed whenever someone makes a selection:

var ms = $('#ms-removeFromSelection').magicSuggest({
  data: 'data.json'
});
$(ms).on('selectionchange', function(){
  this.removeFromSelection(this.getSelection(), true);
  alert('Choose something else. Glory to Arstotzka!');
});
              

.

Example with setData set at startup:

var ms = $('#ms-setData').magicSuggest({});
ms.setData(['Paris', 'New York', 'Gotham']);
$(ms).on('selectionchange', function(){
  alert(JSON.stringify(this.getSelection()));
  this.setData([
    {id:1, name:'Blue'},
    {id:2, name:'Red'}
  ]);
});
              

This will set the name for the form component. Please remember that this component behaves like a lot of checkboxes that have the same name, like <input type="checkbox" name="cities[]" value="Paris"/> The name will always be in an array form so that the passed values can be interpreted as an array of values, just like if you were dealing with a bunch of checkboxes. In the following example, setting the name to cities[] would have resulted in the same DOM.

Example with setName set to 'cities':

var ms = $('#ms-setName').magicSuggest({
  data: 'data.json'
});
ms.setName('cities');
$(ms).on('selectionchange', function(){
  alert(this.getName());
});
              

This method allows you to set the current selection by providing an array of JSON objects.

Example with setSelection used to add free entries at startup:

var ms = $('#ms-setSelection').magicSuggest({});
ms.setSelection([{name:'Paris', value:1}]);
              

This method allows you to set the current selection by providing an array of values. Those values must match what can be found on the valueField JSON property of the current loaded combo's records.

Example with setValue used to preselect cities at startup:

var ms = $('#ms-setValue').magicSuggest({
  data: 'data.json'
});
ms.setValue([2, 3, 4]);
              

This method will set the additional parameters passed out to any AJAX call.

Example with setDataUrlParams used to add an id to the call:

var ms = $('#ms-setDataUrlParams').magicSuggest({
  data: 'data.json'
});
ms.setDataUrlParams({id:3});
$(ms).on('selectionchange', function(){
  alert(JSON.stringify(this.getDataUrlParams()));
});
              

This event is fired just before any AJAX request is performed.

Example firing beforeload:

var ms = $('#ms-beforeload').magicSuggest({
  data: 'data.json'
});
$(ms).on('beforeload', function(c){
  console.debug(this);
});
              

This event is always triggered when the component looses its focus.

Example firing blur:

var ms = $('#ms-blur').magicSuggest({});
$(ms).on('blur', function(c){
  alert('where are you going?');
});
              

This event is triggered when the component has been collapsed, either through clicking the mouse on the trigger or by clicking on another component that can be focused.

Example firing oncollapse:

var ms = $('#ms-oncollapse').magicSuggest({
  data: 'get_cities.php'
});
$(ms).on('collapse', function(c){
  alert('now closed. come back tomorrow.');
});
              

This event is fired when the component is expanded, either through its trigger, or when the user starts typing.

Example firing onexpand:

var ms = $('#ms-onexpand').magicSuggest({
  data: 'get_cities.php'
});
$(ms).on('expand', function(c){
  alert('now open for business.');
});
              

This event is triggered whenever the component gains focus, whether through the keyboard with the tab key, or with the mouse.

Example firing onfocus:

var ms = $('#ms-onfocus').magicSuggest({});
$(ms).on('focus', function(c){
  alert('Turning blue, I think i have the flu!');
});
              

this event is triggered as soon as the user presses a key while the component has focus.

Example firing onkeydown:

var ms = $('#ms-onkeydown').magicSuggest({});
$(ms).on('keydown', function(e,m,v){
  alert('Key code # ' + v.keyCode);
});
              

This event is triggered whenever the pressed key has been released.

Example firing onkeyup:

var ms = $('#ms-onkeyup').magicSuggest({});
$(ms).on('keyup', function(e, m, v){
  alert('Key code # ' + v.keyCode);
});
              

This event is fired when the AJAX request has been completed.

Example firing load:

var ms = $('#ms-onload').magicSuggest({
  data: 'get_cities.php',
  minChars: 1
});
$(ms).on('load', function(e,m){
  alert('finished loading!');
});
              

This event is fired whenever the user changes the current selection.

Example firing selectionchange:

var ms = $('#ms-onselectionchange').magicSuggest({
  data: 'get_cities.php'
});
$(ms).on('selectionchange', function(e,m){
  alert("values: " + JSON.stringify(this.getValue()));
});
              

This event is fired whenever the user clicks on the trigger on the side of the component.

Example firing triggerclick:

var ms = $('#ms-ontriggerclick').magicSuggest({
  data: 'get_cities.php'
});
$(ms).on('triggerclick', function(e,m){
  alert("don't shoot me!");
});