magicsuggest
Version:
MagicSuggest is a multiple selection auto-suggest input box for Bootstrap 3.
1,073 lines (998 loc) • 197 kB
HTML
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="MagicSuggest is a multiple selection combo box built for bootstrap themes">
<meta name="author" content="Nicolas Bize">
<link rel="shortcut icon" href="http://nicolasbize.com/magicsuggest/assets/ico/favicon.ico">
<title>MagicSuggest - Documentation</title>
<link href="lib/bootstrap/css/bootstrap.min.css" rel="stylesheet">
<link href="assets/css/custom.css" rel="stylesheet">
<link href="lib/magicsuggest/magicsuggest.css" rel="stylesheet">
<link href="lib/gh-ribbon/gh-fork-ribbon.css" rel="stylesheet">
<!-- HTML5 shim and Respond.js IE8 support of HTML5 elements and media queries -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
<script src="https://oss.maxcdn.com/libs/respond.js/1.4.2/respond.min.js"></script>
<![endif]-->
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js"></script>
<script src="lib/bootstrap/js/bootstrap.min.js"></script>
<script src="lib/magicsuggest/magicsuggest.js"></script>
</head>
<body>
<div class="github-fork-ribbon-wrapper right">
<div class="github-fork-ribbon">
<a href="https://github.com/nicolasbize/magicsuggest">View on GitHub</a>
</div>
</div>
<a class="notice" href="../faviconx.html">Check out my new open source project, FavIconX!</a>
<div class="site-wrapper">
<div class="site-wrapper-inner">
<div class="cover-container">
<div class="masthead clearfix">
<div class="inner">
<h3 class="masthead-brand">MagicSuggest</h3>
<ul class="nav masthead-nav">
<li><a href="index.html">Home</a></li>
<li><a href="examples.html">Examples</a></li>
<li class="active"><a href="doc.html">Documentation</a></li>
<li><a href="tutorial.html">Tutorial</a></li>
</ul>
</div>
</div>
</div>
<div class="container doc">
<h1>Installation</h1>
<div class="row">
<h3>Requirements</h3>
<p>This library requires <a href="http://getbootstrap.com">Bootstrap 3</a> and <a href="http://jquery.com">jQuery 1.8+</a> to work</p>
<h3>1. Download the project</h3>
<p>Download the latest release by <a href="https://github.com/nicolasbize/magicsuggest/zipball/master">clicking here</a> and unzip its contents in your assets folder</p>
<h3>2. Include the libraries in your code</h3>
<p>Copy and paste the following code, replacing the paths where needed. Make sure that
<code>magicsuggest-min.js</code> is declared after jQuery:</p>
<pre><code><link href="assets/magicsuggest/magicsuggest-min.css" rel="stylesheet">
<script src="assets/magicsuggest/magicsuggest-min.js"></script></code></pre>
<p>Remember that it is good practice to declare the javascript at the end.</p>
<h3>3. Create a DOM element that will serve as a container</h3>
<p>For example, in your form, create a <code>div</code> or <code>input</code> tag:</p>
<pre><code><div id="magicsuggest"></div></code></pre>
<h3>4. Instanciate</h3>
<p>Create a script to configure the component. For example:</p>
<pre><code>
$(function() {
$('#magicsuggest').magicSuggest({
[...] // configuration options
});
});
</code></pre>
</div>
<h1>Configuration Options <span>(Click the names in red to see live examples)</span></h1>
<div class="row">
<div class="col-md-8"></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs">Type</div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs">Default</div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs">Since</div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs">Credits</div>
</div>
<!-- allowFreeEntries -->
<div class="row doc-entry" name="allowFreeEntries">
<div class="col-md-8 entry-title">
<a href="doc.html#" data-toggle="collapse" data-target="#desc-allowFreeEntries">
<code>allowFreeEntries</code></a> allows the user to enter non-suggested entries.
</div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="badge">boolean</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><code>true</code></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="label label-success">1.0</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"> </div>
</div>
<div class="collapse" id="desc-allowFreeEntries">
<div class="bs-callout bs-callout-danger">
<p>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 <code>false</code>, this parameter either restricts the user to the given suggestions (in which case pressing ENTER will not trigger anything).
When set to <code>true</code>, this parameter allows the user to enter custom entries and have them be added to his selected values.
</p>
<h6>Example with <code>allowFreeEntries</code> set to false:</h6>
<div class="row">
<div class="col-md-6">
<pre><code>
$('#ms-allowFreeEntries').magicSuggest({
<a href="doc.html#allowFreeEntries">allowFreeEntries</a>: false,
<a href="doc.html#data">data</a>: ['Paris', 'New York', 'Gotham']
});
</code></pre>
</div>
<div class="col-md-6">
<div class="form-group">
<label>Preventing custom entries</label>
<input id="ms-allowFreeEntries"/>
</div>
<script>
$(function() {
$('#ms-allowFreeEntries').magicSuggest({
allowFreeEntries: false,
data: ['Paris', 'New York', 'Gotham']
});
});
</script>
</div>
</div>
</div>
</div>
<!-- allowDuplicates -->
<div class="row doc-entry" name="allowDuplicates">
<div class="col-md-8 entry-title">
<a href="doc.html#" data-toggle="collapse" data-target="#desc-allowDuplicates">
<code>allowDuplicates</code></a> allows the user to reenter the same entry multiple times.
</div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="badge">boolean</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><code>false</code></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="label label-success">2.1</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><a href="https://github.com/https://github.com/mjohnson8165" target="_">mjohnson8165</a></div>
</div>
<div class="collapse" id="desc-allowDuplicates">
<div class="bs-callout bs-callout-danger">
<p>By default the user cannot enter the same value twice.
When set to <code>true</code>, each value can be entered multiple times.
</p>
<h6>Example with <code>allowDuplicates</code> set to true:</h6>
<div class="row">
<div class="col-md-6">
<pre><code>
$('#ms-allowDuplicates').magicSuggest({
<a href="doc.html#allowDuplicates">allowDuplicates</a>: true,
<a href="doc.html#data">data</a>: ['Paris', 'New York', 'Gotham']
});
</code></pre>
</div>
<div class="col-md-6">
<div class="form-group">
<label>Add multiple Paris! </label>
<input id="ms-allowDuplicates"/>
</div>
<script>
$(function() {
$('#ms-allowDuplicates').magicSuggest({
allowDuplicates: true,
data: ['Paris', 'New York', 'Gotham']
});
});
</script>
</div>
</div>
</div>
</div>
<!-- ajaxConfig -->
<div class="row doc-entry" name="ajaxConfig">
<div class="col-md-8 entry-title">
<a href="doc.html#" data-toggle="collapse" data-target="#desc-ajaxConfig">
<code>ajaxConfig</code></a> specifies the way ajax calls are made.
</div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="badge">object</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><code>{}</code></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="label label-success">2.0.1</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"> </div>
</div>
<div class="collapse" id="desc-ajaxConfig">
<div class="bs-callout bs-callout-danger">
<p>The component uses jQuery's underlying <code>$.ajax()</code> 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.
</p>
<h6>Example with <code>ajaxConfig</code> set to add <code>xhrFields</code> field:</h6>
<div class="row">
<div class="col-md-6">
<pre><code>
$('#ms-ajaxConfig').magicSuggest({
data: 'http://nicolasbize.com/magicsuggest/get_cities.php',
ajaxConfig: {
xhrFields: {
withCredentials: true,
}
}
});
</code></pre>
</div>
<div class="col-md-6">
<div class="form-group">
<label>Type <code>pa</code> and try hitting <code>Enter</code></label>
<input id="ms-ajaxConfig"/>
</div>
<script>
$(function() {
$('#ms-ajaxConfig').magicSuggest({
data: 'http://nicolasbize.com/magicsuggest/get_cities.php',
ajaxConfig: {
xhrFields: {
withCredentials: true,
}
}
});
});
</script>
</div>
</div>
</div>
</div>
<!-- autoSelect -->
<div class="row doc-entry" name="autoSelect">
<div class="col-md-8 entry-title">
<a href="doc.html#" data-toggle="collapse" data-target="#desc-autoSelect">
<code>autoSelect</code></a> automatically selects a result if only one match is found.
</div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="badge">boolean</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><code>true</code></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="label label-success">1.0</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"> </div>
</div>
<div class="collapse" id="desc-autoSelect">
<div class="bs-callout bs-callout-danger">
<p>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 <code>Enter</code> is pressed. When set to <code>false</code>,
the user has to use the keyboard arrows or the mouse to make his selection.
</p>
<h6>Example with <code>autoSelect</code> set to <code>false</code> :</h6>
<div class="row">
<div class="col-md-6">
<pre><code>
$('#ms-autoSelect').magicSuggest({
autoSelect: false,
allowFreeEntries: false,
data: ['Paris', 'New York', 'Gotham']
});
</code></pre>
</div>
<div class="col-md-6">
<div class="form-group">
<label>Type <code>pa</code> and try hitting <code>Enter</code></label>
<input id="ms-autoSelect"/>
</div>
<script>
$(function() {
$('#ms-autoSelect').magicSuggest({
autoSelect: false,
allowFreeEntries: false,
data: ['Paris', 'New York', 'Gotham']
});
});
</script>
</div>
</div>
</div>
</div>
<!-- beforeSend -->
<div class="row doc-entry" name="beforeSend">
<div class="col-md-8 entry-title">
<a href="doc.html#" data-toggle="collapse" data-target="#desc-beforeSend">
<code>beforeSend</code></a> if a custom jQuery function that is launched prior to the ajax request.
</div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="badge">function</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><code>{}</code></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="label label-success">2.1</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><a href="https://github.com/https://github.com/rdamborsky" target="_">rdamborsky</a></div>
</div>
<div class="collapse" id="desc-beforeSend">
<div class="bs-callout bs-callout-danger">
<p>From jQuery's doc: A pre-request callback function that can be used to modify the XMLHTTPRequest object before it is sent.<br/>
Use this to set custom headers, etc. The jqXHR and settings objects are passed as arguments. This is an Ajax Event. <br/>
Returning <code>false</code> in the beforeSend function will cancel the request
Defaults to <code>function(){ }</code>
</p>
<h6>Example with <code>beforeSend</code> set to cancel the request :</h6>
<div class="row">
<div class="col-md-6">
<pre><code>
$('#ms-beforeSend').magicSuggest({
data: 'wrong_url.php',
beforeSend: function(xhr, settings) {
return false;
}
});
</code></pre>
</div>
<div class="col-md-6">
<div class="form-group">
<label>No request sent when the combo is expanded</label>
<input id="ms-beforeSend"/>
</div>
<script>
$(function() {
$('#ms-beforeSend').magicSuggest({
data: 'wrong_url.php',
beforeSend: function(xhr, settings) {
return false;
}
});
});
</script>
</div>
</div>
</div>
</div>
<!-- cls -->
<div class="row doc-entry" name="cls">
<div class="col-md-8 entry-title">
<a href="doc.html#" data-toggle="collapse" data-target="#desc-cls">
<code>cls</code></a> specifies an additional CSS class to apply to the container element.
</div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="badge">string</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><code>''</code></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="label label-success">1.0</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"> </div>
</div>
<div class="collapse" id="desc-cls">
<div class="bs-callout bs-callout-danger">
<p>When the MagicSuggest component is rendered, the input field is surrounded with a div container that has a base class called
<code>ms-ctn</code>. By specifying a custom class, it will be put next to the <code>ms-ctn</code> specifications, thus enabling you to override the base CSS settings.</p>
<h6>Example with <code>cls</code> set to custom to render a blue combo with a flat square style :</h6>
<div class="row">
<div class="col-md-6">
<pre><code>
/** Custom style to place in a CSS declaraction **/
.custom, .custom input {
color: blue;
background: #ECEEFF !important;
border-radius: 0 !important;
}
$('#ms-cls').magicSuggest({
<a href="doc.html#cls">cls</a>: 'custom'
});
</code></pre>
</div>
<div class="col-md-6">
<div class="form-group">
<label>Using an additional custom class for the container</label>
<input id="ms-cls"/>
</div>
<script>
$(function() {
$('#ms-cls').magicSuggest({
cls: 'custom'
});
});
</script>
</div>
</div>
</div>
</div>
<!-- data -->
<div class="row doc-entry" name="data">
<div class="col-md-8 entry-title">
<a href="doc.html#" data-toggle="collapse" data-target="#desc-data">
<code>data</code></a> provides the entries to fill up the combo box.
</div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="badge">object</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><code>null</code></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="label label-success">1.0</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"> </div>
</div>
<div class="collapse" id="desc-data">
<div class="bs-callout bs-callout-danger">
<p>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 <code>data</code> 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:
<ul>
<li>
<h6>An array of strings, such as <code>['Paris', 'New York']</code></h6>
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 <code>data: [{"id":"Paris", "name":"Paris"}, {"id":"New York", "name":"New York"}]</code>.
</li>
<li>
<h6>An array of JSON objects, such as <code>[{"id":0, "name":"Paris"}, {"id":1, "name":"New York"}]</code></h6>
Note that Object Literal Notation is also accepted: <code>[{id:0, name:"Paris"}, {id:1, name:"New York"}]</code>
</li>
<li>
<h6>A JSON object containing its data within the <code>results</code> property: <code>{"results": [{"id":0, "name":"Paris"}, {"id":1, "name":"New York"}]}</code></h6>
Note that Object Literal Notation is also accepted: <code>{"results": [{id:0, name:"Paris"}, {id:1, name:"New York"}]}</code><br/>
This can be useful when you wish to pass other variables along the provided data.
</li>
</ul>
</p>
<p>The data can be provisionned in a <strong>static</strong> way or in a <strong>dynamic</strong> way:
<ul>
<li>
<h6>No Data (default value)</h6>
When left blank, the combo box will <strong>not</strong> 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 <a href="doc.html#allowFreeEntries"><code>allowFreeEntries</code></a> is set to true (default value).
</li>
<li>
<h6>Static Source</h6>
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.
</li>
<li>
<h6>Dynamic Source: Url</h6>
By providing a URL for the <code>data</code> property, MagicSugest will perform an ajax request to retrieve the data necessary to populate the combo box.
The request will include a <code>query</code> 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.
</li>
<li>
<h6>Dynamic Source: Function</h6>
You can pass a function which will be called everytime the component needs to fetch the data to fill the combo.<br/>
The function can include an argument which will contain the text that the user has typed (same as <code>query</code> for ajax)
</li>
</ul>
<div class="row">
<div class="col-md-6">
<pre><code>
$('#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;
}
});
</code></pre>
</div>
<div class="col-md-6">
<div class="form-group">
<label>No data (free entry values separated by ENTER key)</label>
<input id="ms-data-no-data"/>
</div>
<div class="form-group">
<label>JSON array provided</label>
<input id="ms-data-static-data"/>
</div>
<div class="form-group">
<label>Retrieving entries through Ajax</label>
<input id="ms-data-ajax"/>
</div>
<div class="form-group">
<label>Using a function</label>
<input id="ms-data-function"/>
</div>
<script>
$(function() {
$('#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;
}
});
});
</script>
</div>
</div>
</div>
</div>
<!-- dataUrlParams -->
<div class="row doc-entry" name="dataUrlParams">
<div class="col-md-8 entry-title">
<a href="doc.html#" data-toggle="collapse" data-target="#desc-dataUrlParams">
<code>dataUrlParams</code></a> adds additionals parameters given to the ajax call.
</div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="badge">object</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><code>{}</code></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="label label-success">1.2</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><a href="https://github.com/jayesbee" target="_">jayesbee</a></div>
</div>
<div class="collapse" id="desc-dataUrlParams">
<div class="bs-callout bs-callout-danger">
<p>When performing an ajax call through the <code>data</code>'s specified URL, MagicSuggest will pass a base parameter called <code>query</code>
containing the current text entered by the user. All parameters and values specified in the <code>dataUrlParams</code> will also be passed along.
This can be especially useful in a form if the combo's suggestions depend upon a prior field.</p>
<h6>Example with <code>dataUrlParams</code> set to pass out some random info :</h6>
<div class="row">
<div class="col-md-6">
<pre><code>
$('#ms-dataUrlParams').magicSuggest({
data: 'get_cities.php',
dataUrlParams: { id: 34 }
});
</code></pre>
</div>
<div class="col-md-6">
<div class="form-group">
<label>The server will receive 2 POST parameters: <code>query</code> and <code>id</code></label>
<input id="ms-dataUrlParams"/>
</div>
<script>
$(function() {
$('#ms-dataUrlParams').magicSuggest({
data: 'get_cities.php',
dataUrlParams: { id: 34 }
});
});
</script>
</div>
</div>
</div>
</div>
<!-- disabled -->
<div class="row doc-entry" name="disabled">
<div class="col-md-8 entry-title">
<a href="doc.html#" data-toggle="collapse" data-target="#desc-disabled">
<code>disabled</code></a> initializes the combo in a disabled state.
</div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="badge">boolean</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><code>false</code></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="label label-success">1.0</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"> </div>
</div>
<div class="collapse" id="desc-disabled">
<div class="bs-callout bs-callout-danger">
<p>When disabled, the user is not able to change the combo's selection or to interact with the component.</p>
<h6>Example with <code>disabled</code> set to true :</h6>
<div class="row">
<div class="col-md-6">
<pre><code>
$('#ms-disabled').magicSuggest({
data: ['Paris', 'New York', 'Gotham'],
disabled: true
});
</code></pre>
</div>
<div class="col-md-6">
<div class="form-group">
<label>A disabled MagicSuggest component</label>
<input id="ms-disabled"/>
</div>
<script>
$(function() {
$('#ms-disabled').magicSuggest({
data: ['Paris', 'New York', 'Gotham'],
disabled: true
});
});
</script>
</div>
</div>
</div>
</div>
<!-- disabledField -->
<div class="row doc-entry" name="disabledField">
<div class="col-md-8 entry-title">
<a href="doc.html#" data-toggle="collapse" data-target="#desc-disabledField">
<code>disabledField</code></a> specifies the JSON property that defines the disabled behaviour.
</div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="badge">string</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><code>null</code></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="label label-success">2.1</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"> </div>
</div>
<div class="collapse" id="desc-disabledField">
<div class="bs-callout bs-callout-danger">
<p>When specified, each record may have that specific property that triggers a disabled item if set to <code>true</code>.</p>
<h6>Example with <code>disabledField</code> set to a newly given 'disabled' property in the JSON results:</h6>
<div class="row">
<div class="col-md-6">
<pre><code>
$('#ms-disabledField').magicSuggest({
data: [{id:0, name:'Male', disabled: true}, {id:1, name:'Female'}],
disabledField: 'disabled'
});
</code></pre>
</div>
<div class="col-md-6">
<div class="form-group">
<label>Choose the right <code>gender</code></label>
<input id="ms-disabledField"/>
</div>
<script>
$(function() {
$('#ms-disabledField').magicSuggest({
data: [{id:0, name:'Male', disabled: true}, {id:1, name:'Female'}],
disabledField: 'disabled'
});
});
</script>
</div>
</div>
</div>
</div>
<!-- displayField -->
<div class="row doc-entry" name="displayField">
<div class="col-md-8 entry-title">
<a href="doc.html#" data-toggle="collapse" data-target="#desc-displayField">
<code>displayField</code></a> specifies the JSON property to be used for display.
</div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="badge">string</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><code>'name'</code></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="label label-success">1.0</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"> </div>
</div>
<div class="collapse" id="desc-displayField">
<div class="bs-callout bs-callout-danger">
<p>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.</p>
<h6>Example with <code>displayField</code> set to gender :</h6>
<div class="row">
<div class="col-md-6">
<pre><code>
$('#ms-displayField').magicSuggest({
data: [{id:0, gender:'Male'}, {id:1, gender:'Female'}],
displayField: 'gender'
});
</code></pre>
</div>
<div class="col-md-6">
<div class="form-group">
<label>Displaying the custom property <code>gender</code></label>
<input id="ms-displayField"/>
</div>
<script>
$(function() {
$('#ms-displayField').magicSuggest({
data: [{id:0, gender:'Male'}, {id:1, gender:'Female'}],
displayField: 'gender'
});
});
</script>
</div>
</div>
</div>
</div>
<!-- editable -->
<div class="row doc-entry" name="editable">
<div class="col-md-8 entry-title">
<a href="doc.html#" data-toggle="collapse" data-target="#desc-editable">
<code>editable</code></a> enables or prevents keyboard interaction.
</div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="badge">boolean</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><code>true</code></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="label label-success">1.0</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"> </div>
</div>
<div class="collapse" id="desc-editable">
<div class="bs-callout bs-callout-danger">
<p>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 <code>expandOnFocus</code>'s default to true.
</p>
<h6>Example with <code>editable</code> set to false :</h6>
<div class="row">
<div class="col-md-6">
<pre><code>
$('#ms-editable').magicSuggest({
data: ['Paris', 'New York', 'Gotham'],
editable: false
});
</code></pre>
</div>
<div class="col-md-6">
<div class="form-group">
<label>Preventing keyboard interaction with <code>editable</code> set to <code>false</code></label>
<input id="ms-editable"/>
</div>
<script>
$(function() {
$('#ms-editable').magicSuggest({
data: ['Paris', 'New York', 'Gotham'],
editable: false
});
});
</script>
</div>
</div>
</div>
</div>
<!-- expanded -->
<div class="row doc-entry" name="expanded">
<div class="col-md-8 entry-title">
<a href="doc.html#" data-toggle="collapse" data-target="#desc-expanded">
<code>expanded</code></a> sets the starting state for the combo.
</div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="badge">boolean</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><code>false</code></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="label label-success">1.0</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"> </div>
</div>
<div class="collapse" id="desc-expanded">
<div class="bs-callout bs-callout-danger">
<p>When set to true, the combo will be expanded as soon as its data is loaded upon startup.
</p>
<h6>Example with <code>expanded</code> set to true :</h6>
<div class="row">
<div class="col-md-6">
<pre><code>
$('#ms-expanded').magicSuggest({
data: ['Paris', 'New York', 'Gotham'],
expanded: true
});
</code></pre>
</div>
<div class="col-md-6">
<div class="form-group">
<label>An expanded combo</label>
<input id="ms-expanded"/>
</div>
<script>
$(function() {
$('#ms-expanded').magicSuggest({
data: ['Paris', 'New York', 'Gotham'],
expanded: true
});
});
</script>
</div>
</div>
</div>
</div>
<!-- expandOnFocus -->
<div class="row doc-entry" name="expandOnFocus">
<div class="col-md-8 entry-title">
<a href="doc.html#" data-toggle="collapse" data-target="#desc-expandOnFocus">
<code>expandOnFocus</code></a> automatically expands the combo upon focus.
</div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="badge">boolean</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><code>false</code></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="label label-success">1.0</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"> </div>
</div>
<div class="collapse" id="desc-expandOnFocus">
<div class="bs-callout bs-callout-danger">
<p>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.
</p>
<h6>Example with <code>expandOnFocus</code> set to true :</h6>
<div class="row">
<div class="col-md-6">
<pre><code>
$('#ms-expandOnFocus').magicSuggest({
data: ['Paris', 'New York', 'Gotham'],
expandOnFocus: true
});
</code></pre>
</div>
<div class="col-md-6">
<div class="form-group">
<label>Click on the combo to see its choices</label>
<input id="ms-expandOnFocus"/>
</div>
<script>
$(function() {
$('#ms-expandOnFocus').magicSuggest({
data: ['Paris', 'New York', 'Gotham'],
expandOnFocus: true
});
});
</script>
</div>
</div>
</div>
</div>
<!-- groupBy -->
<div class="row doc-entry" name="groupBy">
<div class="col-md-8 entry-title">
<a href="doc.html#" data-toggle="collapse" data-target="#desc-groupBy">
<code>groupBy</code></a> specifies the JSON property to be used for grouping.
</div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="badge">string</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><code>null</code></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="label label-success">1.1</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"> </div>
</div>
<div class="collapse" id="desc-groupBy">
<div class="bs-callout bs-callout-danger">
<p>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 <a href="data.json" target="_">data.json</a> and
<a href="data-groupby.json" target="_">data-groupby.json</a> to see an example of the data passed to the component.
</p>
<h6>Example with <code>groupBy</code> set to <code>'country'</code> :</h6>
<div class="row">
<div class="col-md-6">
<pre><code>
$('#ms-groupBy').magicSuggest({
data: 'data.json',
groupBy: 'country'
});
$('#ms-groupBy2').magicSuggest({
data: 'data-groupby.json',
groupBy: 'country.name'
});
</code></pre>
</div>
<div class="col-md-6">
<div class="form-group">
<label>A list of cities grouped by country</label>
<input id="ms-groupBy"/>
</div>
<div class="form-group">
<label>A list of cities grouped by country.name</label>
<input id="ms-groupBy2"/>
</div>
<script>
$(function() {
$('#ms-groupBy').magicSuggest({
data: 'data.json',
groupBy: 'country'
});
$('#ms-groupBy2').magicSuggest({
data: 'data-groupby.json',
groupBy: 'country.name'
});
});
</script>
</div>
</div>
</div>
</div>
<!-- hideTrigger -->
<div class="row doc-entry" name="hideTrigger">
<div class="col-md-8 entry-title">
<a href="doc.html#" data-toggle="collapse" data-target="#desc-hideTrigger">
<code>hideTrigger</code></a> hides the right trigger.
</div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="badge">boolean</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><code>false</code></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="label label-success">1.0</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"> </div>
</div>
<div class="collapse" id="desc-hideTrigger">
<div class="bs-callout bs-callout-danger">
<p>When hiding the trigger, the combo becomes expanded when:
<ul>
<li>the user starts typing in the combo or uses the up/down arrow</li>
<li>the combo gains focus and <code>expandOnFocus</code> is set to true</li>
</ul>
</p>
<h6>Example with <code>hideTrigger</code> set to <code>true</code> :</h6>
<div class="row">
<div class="col-md-6">
<pre><code>
$('#ms-hideTrigger').magicSuggest({
data: 'data.json',
hideTrigger: true
});
</code></pre>
</div>
<div class="col-md-6">
<div class="form-group">
<label>Start typing the name of a French or US city</label>
<input id="ms-hideTrigger"/>
</div>
<script>
$(function() {
$('#ms-hideTrigger').magicSuggest({
data: 'data.json',
hideTrigger: true
});
});
</script>
</div>
</div>
</div>
</div>
<!-- highlight -->
<div class="row doc-entry" name="highlight">
<div class="col-md-8 entry-title">
<a href="doc.html#" data-toggle="collapse" data-target="#desc-highlight">
<code>highlight</code></a> emphasizes the typed text in the combo's suggestions.
</div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="badge">boolean</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><code>true</code></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="label label-success">1.0</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"> </div>
</div>
<div class="collapse" id="desc-highlight">
<div class="bs-callout bs-callout-danger">
<p>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.
</p>
<h6>Example with <code>highlight</code> set to <code>false</code> :</h6>
<div class="row">
<div class="col-md-6">
<pre><code>
$('#ms-highlight').magicSuggest({
data: 'data.json',
highlight: false
});
</code></pre>
</div>
<div class="col-md-6">
<div class="form-group">
<label>Start typing the name of a French or US city</label>
<input id="ms-highlight"/>
</div>
<script>
$(function() {
$('#ms-highlight').magicSuggest({
data: 'data.json',
highlight: false
});
});
</script>
</div>
</div>
</div>
</div>
<!-- id -->
<div class="row doc-entry" name="id">
<div class="col-md-8 entry-title">
<a href="doc.html#" data-toggle="collapse" data-target="#desc-id">
<code>id</code></a> gives the component a specific identifier.
</div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="badge">string</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><code>null</code></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="label label-success">1.1</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"> </div>
</div>
<div class="collapse" id="desc-id">
<div class="bs-callout bs-callout-danger">
<p>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.
</p>
<h6>Example with <code>id</code> set to <code>'my-custom-id'</code> :</h6>
<div class="row">
<div class="col-md-6">
<pre><code>
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);
}
);
</code></pre>
</div>
<div class="col-md-6">
<div class="form-group">
<label>Start typing the name of a French or US city</label>
<input class="ms-id"/>
</div>
<script>
$(function() {
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);
}
);
});
</script>
</div>
</div>
</div>
</div>
<!-- infoMsgCls -->
<div class="row doc-entry" name="infoMsgCls">
<div class="col-md-8 entry-title">
<a href="doc.html#" data-toggle="collapse" data-target="#desc-infoMsgCls">
<code>infoMsgCls</code></a> adds a class to the information text.
</div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="badge">string</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><code>''</code></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"><span class="label label-success">1.1</span></div>
<div class="col-md-1 hidden-md hidden-sm hidden-xs"> </div>
</div>
<div class="collapse" id="desc-infoMsgCls">
<div class="bs-callout bs-callout-danger">
<p>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.
<code>infoMsgCls</code> enables you to customize the way that it looks.
</p>
<h6>Example with <code>infoMsgCls</code> set to <code>custom</code> :</h6>
<div class="row">
<div class="col-md-6">
<pre><code>
$('#ms-infoMsgCls').magicSuggest({
data: ['Paris', 'New York', 'Gotham'],
infoMsgCls: 'custom'
});
</code></pre>