RetailCRM-Mirror/select2
1
0
Fork 0
mirror of synced 2025-02-04 06:09:23 +03:00
Code Issues Projects Releases Wiki Activity

Reorganize and expand AJAX documentation

Browse Source
This commit is contained in:
alexweissman 2017-09-11 20:25:30 -04:00
parent c9bd2ad716
commit 361f7fc312
2 changed files with 145 additions and 108 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

251
pages/06.data-sources/02.ajax/docs.md
View File

@ -1,5 +1,7 @@
--- ---
title: Ajax (remote data) title: Ajax (remote data)
metadata:
description: Select2 provides extensive support for populating dropdown items from a remote data source.
taxonomy: taxonomy:
category: docs category: docs
process: process:
@ -7,134 +9,49 @@ process:
never_cache_twig: true never_cache_twig: true
--- ---
Select2 comes with AJAX support built in, using jQuery's AJAX methods. In this example, we can search for repositories using GitHub's API. Select2 comes with AJAX support built in, using jQuery's AJAX methods. In this example, we can search for repositories using GitHub's API:
<select class="js-example-data-ajax form-control"> <select class="js-example-data-ajax form-control"></select>
<option value="3620194" selected="selected">select2/select2</option>
</select>
When using Select2 with remote data, the HTML required for the `select` is the same as any other Select2. If you need to provide default selections, you just need to include an `option` for each selection that contains the value and text that should be displayed. **In your HTML:**
``` ```
<select class="js-data-example-ajax"> <select class="js-data-example-ajax"></select>
<option value="3620194" selected="selected">select2/select2</option>
</select>
``` ```
You can configure how Select2 searches for remote data using the `ajax` option: **In your Javascript:**
<pre data-fill-from=".js-code-placeholder"></pre> ```
$('.js-example-data-ajax').select2({
<script type="text/javascript" class="js-code-placeholder">
$(".js-example-data-ajax").select2({
ajax: { ajax: {
url: "https://api.github.com/search/repositories", url: 'https://api.github.com/search/repositories',
dataType: 'json', dataType: 'json'
delay: 250, // Additional AJAX parameters go here; see the end of this chapter for the full code of this example
data: function (params) {
return {
q: params.term, // search term
page: params.page
};
},
processResults: function (data, params) {
// parse the results into the format expected by Select2
// since we are using custom formatting functions we do not need to
// alter the remote JSON data, except to indicate that infinite
// scrolling can be used
params.page = params.page || 1;
return {
results: data.items,
pagination: {
more: (params.page * 30) < data.total_count
}
};
},
cache: true
},
escapeMarkup: function (markup) { return markup; }, // let our custom formatter work
minimumInputLength: 1,
templateResult: formatRepo,
templateSelection: formatRepoSelection
});
function formatRepo (repo) {
if (repo.loading) return repo.text;
var markup = "<div class='select2-result-repository clearfix'>" +
"<div class='select2-result-repository__avatar'><img src='" + repo.owner.avatar_url + "' /></div>" +
"<div class='select2-result-repository__meta'>" +
"<div class='select2-result-repository__title'>" + repo.full_name + "</div>";
if (repo.description) {
markup += "<div class='select2-result-repository__description'>" + repo.description + "</div>";
}
markup += "<div class='select2-result-repository__statistics'>" +
"<div class='select2-result-repository__forks'><i class='fa fa-flash'></i> " + repo.forks_count + " Forks</div>" +
"<div class='select2-result-repository__stargazers'><i class='fa fa-star'></i> " + repo.stargazers_count + " Stars</div>" +
"<div class='select2-result-repository__watchers'><i class='fa fa-eye'></i> " + repo.watchers_count + " Watchers</div>" +
"</div>" +
"</div></div>";
return markup;
}
function formatRepoSelection (repo) {
return repo.full_name || repo.text;
}
</script>
Select2 will pass any options in the `ajax` object to jQuery's `$.ajax` function, or the `transport` function you specify.
>>> Select2 expects results from the remote endpoint to be filtered on the **server side**. If server-side filtering is not possible, you may be interested in using Select2's <a href="examples.html#data-array">support for data arrays</a> instead.
## Rate-limiting requests
You can tell Select2 to wait until the user has finished typing their search term before triggering the AJAX request. Simply use the `ajax.delay` configuration option to tell Select2 how long to wait after a user has stopped typing before sending the request:
```
$('select').select2({
ajax: {
delay: 250 // wait 250 milliseconds before triggering the request
} }
}); });
``` ```
## Transforming response data You can configure how Select2 searches for remote data using the `ajax` option. Select2 will pass any options in the `ajax` object to jQuery's `$.ajax` function, or the `transport` function you specify.
You can use the `ajax.processResults` option to transform the data returned by your API into the format expected by Select2: >>> For **remote data sources only**, Select2 does not create a new `<option>` element until the item has been selected for the first time. This is done for performance reasons. Once an `<option>` has been created, it will remain in the DOM even if the selection is later changed.
``` ## Request parameters
$('select').select2({
ajax: {
url: '/example/api',
processResults: function (data) {
return {
results: data.items
};
}
}
});
```
## Default values Select2 will issue a request to the specified URL when the user opens the control (unless there is a `minimumInputLength` set), and again every time the user types in the search box. By default, it will send the following as query string parameters:
You may wish to set a pre-selected default value for a Select2 control that receives its data from an AJAX request. - `term` : The current search term in the search box.
- `q` : Contains the same contents as `term`.
- `_type`: A "request type". Will usually be `query`, but changes to `query_append` for paginated requests.
- `page` : The current page number to request. Only sent for paginated (infinite scrolling) searches.
To do this, please refer to the following Stack Overflow answer: [Select2 4.0.0 initial value with AJAX](http://stackoverflow.com/q/30316586/359284#30328989). For example, Select2 might issue a request that looks like: `https://api.github.com/search/repositories?term=sel&_type=query&q=sel`.
## Additional request parameters
By default, Select2 will send the search query term as well as the pagination data as query parameters in requests.
Sometimes, you may need to add additional query parameters to the request. You can modify the parameters that are sent with the request by overriding the `ajax.data` option: Sometimes, you may need to add additional query parameters to the request. You can modify the parameters that are sent with the request by overriding the `ajax.data` option:
``` ```
$('select').select2({ $('#mySelect2').select2({
ajax: { ajax: {
url: 'https://api.github.com/search/repositories',
data: function (params) { data: function (params) {
var query = { var query = {
search: params.term, search: params.term,
@ -148,12 +65,58 @@ $('select').select2({
}); });
``` ```
## Transforming response data
You can use the `ajax.processResults` option to transform the data returned by your API into the format expected by Select2:
```
$('#mySelect2').select2({
ajax: {
url: '/example/api',
processResults: function (data) {
// Tranforms the top-level key of the response object from 'items' to 'results'
return {
results: data.items
};
}
}
});
```
>>> Select2 expects results from the remote endpoint to be filtered on the **server side**. If server-side filtering is not possible, you may be interested in using Select2's [support for data arrays](/data-sources/arrays) instead.
## Default (pre-selected) values
You may wish to set a pre-selected default value for a Select2 control that receives its data from an AJAX request.
To provide default selections, you may include an `<option>` for each selection that contains the value and text that should be displayed:
```
<select class="js-example-data-ajax form-control">
<option value="3620194" selected="selected">select2/select2</option>
</select>
```
To achieve this programmatically, you will need to [create and append a new `Option`](/programmatic-control/add-select-clear-items).
## Rate-limiting requests
You can tell Select2 to wait until the user has finished typing their search term before triggering the AJAX request. Simply use the `ajax.delay` configuration option to tell Select2 how long to wait after a user has stopped typing before sending the request:
```
$('#mySelect2').select2({
ajax: {
delay: 250 // wait 250 milliseconds before triggering the request
}
});
```
## Dynamic URLs ## Dynamic URLs
If there isn't a single url for your search results, or you need to call a function to determine the url to use, you can specify a callback for the `ajax.url` option to generate the url. The current search query will be passed in through the `params` option: If there isn't a single url for your search results, or you need to call a function to determine the url to use, you can specify a callback for the `ajax.url` option to generate the url. The current search query will be passed in through the `params` option:
``` ```
$('select').select2({ $('#mySelect2').select2({
ajax: { ajax: {
url: function (params) { url: function (params) {
return '/some/url/' + params.term; return '/some/url/' + params.term;
@ -167,7 +130,7 @@ $('select').select2({
Select2 uses the transport method defined in `ajax.transport` to send requests to your API. By default this transport method is `jQuery.ajax`, but it can be easily overridden: Select2 uses the transport method defined in `ajax.transport` to send requests to your API. By default this transport method is `jQuery.ajax`, but it can be easily overridden:
``` ```
$('select').select2({ $('#mySelect2').select2({
ajax: { ajax: {
transport: function (params, success, failure) { transport: function (params, success, failure) {
var request = new AjaxRequest(params.url, params); var request = new AjaxRequest(params.url, params);
@ -251,3 +214,75 @@ ajax: {
} }
} }
``` ```
## Additional examples
This code powers the Github example presented at the beginning of this chapter:
<pre data-fill-from=".js-code-placeholder"></pre>
<script type="text/javascript" class="js-code-placeholder">
$(".js-example-data-ajax").select2({
ajax: {
url: "https://api.github.com/search/repositories",
dataType: 'json',
delay: 250,
data: function (params) {
return {
q: params.term, // search term
page: params.page
};
},
processResults: function (data, params) {
// parse the results into the format expected by Select2
// since we are using custom formatting functions we do not need to
// alter the remote JSON data, except to indicate that infinite
// scrolling can be used
params.page = params.page || 1;
return {
results: data.items,
pagination: {
more: (params.page * 30) < data.total_count
}
};
},
cache: true
},
placeholder: 'Search for a repository',
escapeMarkup: function (markup) { return markup; }, // let our custom formatter work
minimumInputLength: 1,
templateResult: formatRepo,
templateSelection: formatRepoSelection
});
function formatRepo (repo) {
if (repo.loading) {
return repo.text;
}
var markup = "<div class='select2-result-repository clearfix'>" +
"<div class='select2-result-repository__avatar'><img src='" + repo.owner.avatar_url + "' /></div>" +
"<div class='select2-result-repository__meta'>" +
"<div class='select2-result-repository__title'>" + repo.full_name + "</div>";
if (repo.description) {
markup += "<div class='select2-result-repository__description'>" + repo.description + "</div>";
}
markup += "<div class='select2-result-repository__statistics'>" +
"<div class='select2-result-repository__forks'><i class='fa fa-flash'></i> " + repo.forks_count + " Forks</div>" +
"<div class='select2-result-repository__stargazers'><i class='fa fa-star'></i> " + repo.stargazers_count + " Stars</div>" +
"<div class='select2-result-repository__watchers'><i class='fa fa-eye'></i> " + repo.watchers_count + " Watchers</div>" +
"</div>" +
"</div></div>";
return markup;
}
function formatRepoSelection (repo) {
console.log(repo);
return repo.full_name || repo.text;
}
</script>

2
pages/06.data-sources/03.arrays/docs.md
View File

@ -60,6 +60,8 @@ $(".js-example-data-array-selected").select2({
}) })
</script> </script>
Unlike the case of items supplied by [AJAX data sources](/data-sources/ajax), items supplied as an array will be immediately rendered as `<option>` elements in the target `<select>` control.
## Backwards compatibility with the `tags` option ## Backwards compatibility with the `tags` option
In Select2 v3.5, this option was called `tags`. However in version 4.0, `tags` now handles the [tagging feature](/tagging). In Select2 v3.5, this option was called `tags`. However in version 4.0, `tags` now handles the [tagging feature](/tagging).