Skip to content

Commit 64cb528

Browse files
kevin-brownkevin-brown
committed
Set up a public event relay
Now Select2 can fire jQuery events that will match the corresponding internal events. The `open` and `close` events are now publicly accessible. The selection adapter was chosen because it is the least likely to be moved, but handles the most common events. This `EventRelay` decorator should theoretically be able to decorate any of the adapters, as they all have the `bind` method that it needs.
1 parent bba967b commit 64cb528

11 files changed

Lines changed: 267 additions & 11 deletions

File tree

‎dist/js/select2.amd.full.js‎

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1226,6 +1226,31 @@ define('select2/selection/search',[
12261226
return Search;
12271227
});
12281228

1229+
define('select2/selection/eventRelay',[
1230+
'jquery'
1231+
], function ($) {
1232+
function EventRelay () { }
1233+
1234+
EventRelay.prototype.bind = function (decorated, container, $container) {
1235+
var self = this;
1236+
var relayEvents = ['open', 'close'];
1237+
1238+
decorated.call(this, container, $container);
1239+
1240+
container.on('*', function (name, params) {
1241+
if (relayEvents.indexOf(name) === -1) {
1242+
return;
1243+
}
1244+
1245+
var evt = $.Event('select2:' + name, params);
1246+
1247+
self.$element.trigger(evt);
1248+
});
1249+
};
1250+
1251+
return EventRelay;
1252+
});
1253+
12291254
define('select2/translation',[
12301255

12311256
], function () {
@@ -3299,6 +3324,7 @@ define('select2/defaults',[
32993324
'./selection/placeholder',
33003325
'./selection/allowClear',
33013326
'./selection/search',
3327+
'./selection/eventRelay',
33023328

33033329
'./utils',
33043330
'./translation',
@@ -3323,7 +3349,7 @@ define('select2/defaults',[
33233349
], function ($, ResultsList,
33243350

33253351
SingleSelection, MultipleSelection, Placeholder, AllowClear,
3326-
SelectionSearch,
3352+
SelectionSearch, EventRelay,
33273353

33283354
Utils, Translation, DIACRITICS,
33293355

@@ -3444,6 +3470,11 @@ define('select2/defaults',[
34443470
SelectionSearch
34453471
);
34463472
}
3473+
3474+
options.selectionAdapter = Utils.Decorate(
3475+
options.selectionAdapter,
3476+
EventRelay
3477+
);
34473478
}
34483479

34493480
if (typeof options.language === 'string') {

‎dist/js/select2.amd.js‎

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1226,6 +1226,31 @@ define('select2/selection/search',[
12261226
return Search;
12271227
});
12281228

1229+
define('select2/selection/eventRelay',[
1230+
'jquery'
1231+
], function ($) {
1232+
function EventRelay () { }
1233+
1234+
EventRelay.prototype.bind = function (decorated, container, $container) {
1235+
var self = this;
1236+
var relayEvents = ['open', 'close'];
1237+
1238+
decorated.call(this, container, $container);
1239+
1240+
container.on('*', function (name, params) {
1241+
if (relayEvents.indexOf(name) === -1) {
1242+
return;
1243+
}
1244+
1245+
var evt = $.Event('select2:' + name, params);
1246+
1247+
self.$element.trigger(evt);
1248+
});
1249+
};
1250+
1251+
return EventRelay;
1252+
});
1253+
12291254
define('select2/translation',[
12301255

12311256
], function () {
@@ -3299,6 +3324,7 @@ define('select2/defaults',[
32993324
'./selection/placeholder',
33003325
'./selection/allowClear',
33013326
'./selection/search',
3327+
'./selection/eventRelay',
33023328

33033329
'./utils',
33043330
'./translation',
@@ -3323,7 +3349,7 @@ define('select2/defaults',[
33233349
], function ($, ResultsList,
33243350

33253351
SingleSelection, MultipleSelection, Placeholder, AllowClear,
3326-
SelectionSearch,
3352+
SelectionSearch, EventRelay,
33273353

33283354
Utils, Translation, DIACRITICS,
33293355

@@ -3444,6 +3470,11 @@ define('select2/defaults',[
34443470
SelectionSearch
34453471
);
34463472
}
3473+
3474+
options.selectionAdapter = Utils.Decorate(
3475+
options.selectionAdapter,
3476+
EventRelay
3477+
);
34473478
}
34483479

34493480
if (typeof options.language === 'string') {

‎dist/js/select2.full.js‎

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10761,6 +10761,31 @@ define('select2/selection/search',[
1076110761
return Search;
1076210762
});
1076310763

10764+
define('select2/selection/eventRelay',[
10765+
'jquery'
10766+
], function ($) {
10767+
function EventRelay () { }
10768+
10769+
EventRelay.prototype.bind = function (decorated, container, $container) {
10770+
var self = this;
10771+
var relayEvents = ['open', 'close'];
10772+
10773+
decorated.call(this, container, $container);
10774+
10775+
container.on('*', function (name, params) {
10776+
if (relayEvents.indexOf(name) === -1) {
10777+
return;
10778+
}
10779+
10780+
var evt = $.Event('select2:' + name, params);
10781+
10782+
self.$element.trigger(evt);
10783+
});
10784+
};
10785+
10786+
return EventRelay;
10787+
});
10788+
1076410789
define('select2/translation',[
1076510790

1076610791
], function () {
@@ -12834,6 +12859,7 @@ define('select2/defaults',[
1283412859
'./selection/placeholder',
1283512860
'./selection/allowClear',
1283612861
'./selection/search',
12862+
'./selection/eventRelay',
1283712863

1283812864
'./utils',
1283912865
'./translation',
@@ -12858,7 +12884,7 @@ define('select2/defaults',[
1285812884
], function ($, ResultsList,
1285912885

1286012886
SingleSelection, MultipleSelection, Placeholder, AllowClear,
12861-
SelectionSearch,
12887+
SelectionSearch, EventRelay,
1286212888

1286312889
Utils, Translation, DIACRITICS,
1286412890

@@ -12979,6 +13005,11 @@ define('select2/defaults',[
1297913005
SelectionSearch
1298013006
);
1298113007
}
13008+
13009+
options.selectionAdapter = Utils.Decorate(
13010+
options.selectionAdapter,
13011+
EventRelay
13012+
);
1298213013
}
1298313014

1298413015
if (typeof options.language === 'string') {

‎dist/js/select2.full.min.js‎

Lines changed: 2 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎dist/js/select2.js‎

Lines changed: 32 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1654,6 +1654,31 @@ define('select2/selection/search',[
16541654
return Search;
16551655
});
16561656

1657+
define('select2/selection/eventRelay',[
1658+
'jquery'
1659+
], function ($) {
1660+
function EventRelay () { }
1661+
1662+
EventRelay.prototype.bind = function (decorated, container, $container) {
1663+
var self = this;
1664+
var relayEvents = ['open', 'close'];
1665+
1666+
decorated.call(this, container, $container);
1667+
1668+
container.on('*', function (name, params) {
1669+
if (relayEvents.indexOf(name) === -1) {
1670+
return;
1671+
}
1672+
1673+
var evt = $.Event('select2:' + name, params);
1674+
1675+
self.$element.trigger(evt);
1676+
});
1677+
};
1678+
1679+
return EventRelay;
1680+
});
1681+
16571682
define('select2/translation',[
16581683

16591684
], function () {
@@ -3727,6 +3752,7 @@ define('select2/defaults',[
37273752
'./selection/placeholder',
37283753
'./selection/allowClear',
37293754
'./selection/search',
3755+
'./selection/eventRelay',
37303756

37313757
'./utils',
37323758
'./translation',
@@ -3751,7 +3777,7 @@ define('select2/defaults',[
37513777
], function ($, ResultsList,
37523778

37533779
SingleSelection, MultipleSelection, Placeholder, AllowClear,
3754-
SelectionSearch,
3780+
SelectionSearch, EventRelay,
37553781

37563782
Utils, Translation, DIACRITICS,
37573783

@@ -3872,6 +3898,11 @@ define('select2/defaults',[
38723898
SelectionSearch
38733899
);
38743900
}
3901+
3902+
options.selectionAdapter = Utils.Decorate(
3903+
options.selectionAdapter,
3904+
EventRelay
3905+
);
38753906
}
38763907

38773908
if (typeof options.language === 'string') {

‎dist/js/select2.min.js‎

Lines changed: 2 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/examples.html‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -396,6 +396,67 @@ <h2>Example code</h2>
396396
</div>
397397
</section>
398398

399+
<section id="events" class="row">
400+
<div class="col-md-4">
401+
<h1>Events</h1>
402+
403+
<p>
404+
Select2 will trigger some events on the original select element,
405+
allowing you to integrate it with other components. You can find more
406+
information on events
407+
<a href="options.html#events">on the options page</a>.
408+
</p>
409+
410+
<p>
411+
<select class="js-states js-example-events form-control"></select>
412+
</p>
413+
414+
<p>
415+
<select class="js-states js-example-events form-control" multiple="multiple"></select>
416+
</p>
417+
418+
<p>
419+
<code>change</code> is fired whenever an option is selected or removed.
420+
</p>
421+
422+
<p>
423+
<code>select2:open</code> is fired whenever the dropdown is opened.
424+
</p>
425+
426+
<p>
427+
<code>select2:close</code> is fired whenever the dropdown is closed.
428+
</p>
429+
</div>
430+
<div class="col-md-8">
431+
<h2>Example code</h2>
432+
433+
<ul class="js-event-log"></ul>
434+
435+
<pre data-fill-from=".js-code-events"></pre>
436+
437+
<script type="text/javascript" class="js-code-events">
438+
var $eventLog = $(".js-event-log");
439+
var $eventSelect = $(".js-example-events");
440+
441+
$eventSelect.on("select2:open", function (e) { log("select2:open"); });
442+
$eventSelect.on("select2:close", function (e) { log("select2:close"); });
443+
444+
$eventSelect.on("change", function (e) { log("change"); });
445+
446+
function log (name, args) {
447+
args = args || {};
448+
var $e = $("<li>" + name + " -> " + JSON.stringify(args) + "</li>");
449+
$eventLog.append($e);
450+
$e.animate({ opacity: 1 }, 10000, 'linear', function () {
451+
$e.animate({ opacity: 0 }, 2000, 'linear', function () {
452+
$e.remove();
453+
});
454+
});
455+
}
456+
</script>
457+
</div>
458+
</section>
459+
399460
<section id="tags" class="row">
400461
<div class="col-md-4">
401462
<h1>Tagging support</h1>
@@ -838,6 +899,8 @@ <h2>Example code</h2>
838899
$(".js-example-programmatic").select2();
839900
$(".js-example-programmatic-multi").select2();
840901

902+
$eventSelect.select2();
903+
841904
$tags.select2({
842905
tags: ['red', 'blue', 'green']
843906
});

‎docs/index.html‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,13 +15,13 @@ <h1>Select2</h1>
1515
</div>
1616
<div class="col-md-6 jumbotron-side">
1717
<p>
18-
<a href="announcements-4.0.html" class="btn btn-success btn-lg">
18+
<a href="https://github.com/select2/select2/releases" class="btn btn-success btn-lg">
1919
<i class="fa fa-download fa-lg"></i>
2020
Download
2121
</a>
2222
</p>
2323
<p>
24-
<strong>Version</strong> 4.0.0 <em>beta</em>
24+
<strong>Version</strong> 4.0.0 <em>beta 1</em>
2525
</p>
2626
</div>
2727
</div>

‎docs/options.html‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -632,6 +632,45 @@ <h1>Events</h1>
632632
component that state has changed, as well as an adapter that allows some
633633
of these events to be relayed to the outside word.
634634
</p>
635+
636+
<dl class="dl-horizontal">
637+
<dt>Adapter</dt>
638+
<dd>
639+
<code title="select2/selection">SelectionAdapter</code>
640+
</dd>
641+
642+
<dt>Decorator</dt>
643+
<dd>
644+
<code title="select2/selection/eventRelay">EventRelay</code>
645+
</dd>
646+
</dl>
647+
648+
<h2>
649+
Public events
650+
</h2>
651+
652+
<p>
653+
All public events are relayed using the jQuery event system, and they are
654+
triggered on the <code>&lt;select&gt;</code> element that Select2 is
655+
attached to. You can attach to them using the
656+
<a href="https://api.jquery.com/on/"><code>.on</code> method</a> provided
657+
by jQuery.
658+
</p>
659+
660+
<h2>
661+
Internal events
662+
</h2>
663+
664+
<p>
665+
Select2 triggers internal events using its own internal event system,
666+
which allows adapters to communicate with each other. These events are not
667+
accessible through the jQuery event system.
668+
</p>
669+
670+
<p>
671+
You can find more information on the public events triggered by individual
672+
adapters in <a href="#adapters">the individual adapter documentation</a>.
673+
</p>
635674
</section>
636675

637676
<section id="adapters">

0 commit comments

Comments
 (0)