/
boxselect.html
163 lines (149 loc) · 8.92 KB
/
boxselect.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<title>Ext.ux.form.field.BoxSelect</title>
<!-- ExtJS -->
<link rel="stylesheet" type="text/css" href="http://dev.sencha.com/deploy/ext-4.0.2a/resources/css/ext-all.css" />
<script type="text/javascript" src="http://dev.sencha.com/deploy/ext-4.0.2a/bootstrap.js"></script>
<link rel="stylesheet" type="text/css" href="../src/BoxSelect.css" />
<script type="text/javascript" src="../src/BoxSelect.js"></script>
<!-- Shared -->
<link rel="stylesheet" type="text/css" href="http://dev.sencha.com/deploy/ext-4.0.2a/examples/shared/example.css" />
<!-- Example -->
<script type="text/javascript" src="boxselect.js"></script>
<style type="text/css">
.example {
width: 600px;
border: 1px solid #CCC;
padding: 0 10px;
margin: 0 0 10px;
}
.x-fieldset {
margin-top: 20px;
}
ul.config-options, ul.config-options ul {
margin-bottom: 20px;
margin-left: 20px;
}
.config-options li {
list-style: disc inside;
}
.example pre {
margin-bottom: 20px;
}
</style>
</head>
<body>
<h1>BoxSelects</h1>
<p>The js is not minified so it is readable. See <a href="boxselect.js">boxselect.js</a> to view the code for these examples.</p>
<p>Ext.ux.form.field.BoxSelect extends <a href="http://docs.sencha.com/ext-js/4-0/#/api/Ext.form.field.ComboBox">Ext.form.field.ComboBox</a> to
provide a more 'multiSelect'-friendly control. The careful efforts made in this extension enable most (if not all) of the
<a href="http://dev.sencha.com/deploy/ext-4.0.2a/examples/form/combos.html">ComboBox examples</a> to convert to BoxSelects easily. The examples
included here showcase the differences between the default control and this extension.</p>
<div class="example">
<h2>Basic Configuration</h2>
<p>All configuration values for <a href="http://docs.sencha.com/ext-js/4-0/#/api/Ext.form.field.ComboBox">ComboBox</a> should work, but some defaults are changed:</p>
<ul class="config-options">
<li>
<a href="http://docs.sencha.com/ext-js/4-0/#/api/Ext.form.field.ComboBox-cfg-multiSelect">multiSelect</a> is defaulted to <b>true</b>.<br />
Though single-select is supported, the primary use case for BoxSelect is multiSelect.
</li>
<li>
<a href="http://docs.sencha.com/ext-js/4-0/#/api/Ext.form.field.ComboBox-cfg-forceSelection">forceSelection</a> is defaulted to <b>true</b>.<br />
Most typical uses of multiple selections are from pre-formed lists, with some rare exceptions like multiple emails with auto-suggest.
</li>
<li>
<a href="http://docs.sencha.com/ext-js/4-0/#/api/Ext.form.field.ComboBox-cfg-typeAhead">typeAhead</a> is still defaulted to <b>false</b>, but
support for this feature has been added for multiSelect='true'. The basic combobox control does not support typeAhead in multiSelect configurations.
</li>
<li>
<p><a href="http://docs.sencha.com/ext-js/4-0/#/api/Ext.form.field.ComboBox-cfg-value">value</a> can be used to initialize multiSelect values. The
same formats of values are accepted for this as are accepted by calls to setValue.</p>
<ul>
<li>A string associated to the configured <a href="http://docs.sencha.com/ext-js/4-0/#/api/Ext.form.field.ComboBox-cfg-valueField">valueField</a></li>
<li>When multiSelect is true, a string that is split using the field's
<a href="http://docs.sencha.com/ext-js/4-0/#/api/Ext.form.field.ComboBox-cfg-delimiter">delimiter</a></li>
<li>An array of values associated to the configured
<a href="http://docs.sencha.com/ext-js/4-0/#/api/Ext.form.field.ComboBox-cfg-valueField">valueField</a></li>
<li>An array of records of the Model type associated to the field's
<a href="http://docs.sencha.com/ext-js/4-0/#/api/Ext.form.field.ComboBox-cfg-store">store</a></li>
</ul>
</li>
</ul>
<div id="basicBoxselect"></div>
</div>
<div class="example">
<h2>Single Select</h2>
<p>While the primary use case for BoxSelect is for multiple selection, single selection can also be set with multiSelect: false.
If you want this to be the default case for all BoxSelect's, you can do so by adding the following before your BoxSelects are created:</p>
<pre>Ext.ux.form.field.BoxSelect.prototype.multiSelect = false;</pre>
<div id="singleSelect"></div>
</div>
<div class="example">
<h2>Automatic querying of remote stores for unknown values</h2>
<p>If <a href="http://docs.sencha.com/ext-js/4-0/#/api/Ext.form.field.ComboBox-cfg-queryMode">queryMode</a> is set to 'remote',
<a href="http://docs.sencha.com/ext-js/4-0/#/api/Ext.form.field.ComboBox-cfg-forceSelection">forceSelection</a> is set to true,
and a value is passed to the BoxSelect that is not in the store, a query will be sent to the store's configured proxy with a
parameter with the name of the <a href="http://docs.sencha.com/ext-js/4-0/#/api/Ext.form.field.ComboBox-cfg-valueField">valueField</a>,
and a value of the unknown values separated by the configured <a href="http://docs.sencha.com/ext-js/4-0/#/api/Ext.form.field.ComboBox-cfg-delimiter">delimiter</a>. For
example if the valueField is 'exampleIdField' and the delimiter is ', ' and unknown values '17' and '3281' are set, the following parameters
will be passed to <a href="http://docs.sencha.com/ext-js/4-0/#/api/Ext.data.Store-method-load">store.load()</a>:</p>
<pre>{ exampleIdField: '17, 3281' }</pre>
<p>This attempt to load the unknown values will be performed only once per initValue/setValue call. Any records that are still
unknown after this request will be removed from the field's value, but all known values will be retained.</p>
</div>
<div class="example">
<h2>forceSelection: false -- Multiple Emails with Auto-suggest</h2>
<p>The combo below illustrates the usage of 'forceSelection: false' with the BoxSelect component to enable the
entry of multiple email addresses, with auto-suggestions provided from the attached store. New records are
created using the user input for both the configured
<a href="http://docs.sencha.com/ext-js/4-0/#/api/Ext.form.field.ComboBox-cfg-displayField">displayField</a> and
<a href="http://docs.sencha.com/ext-js/4-0/#/api/Ext.form.field.ComboBox-cfg-valueField">valueField</a>. These new
records are <b>not</b> added to the combo's store automatically.</p>
<p>There are three methods of determining when a new entry will be created:</p>
<ul class="config-options">
<li>
When the user types the configured <a href="http://docs.sencha.com/ext-js/4-0/#/api/Ext.form.field.ComboBox-cfg-delimiter">delimiter</a> (defaults to ', '),
the value that the user entered before the delimiter will be used to create a new record.
</li>
<li>
<a href="#">createNewOnEnter</a> is defaulted to false. If set to true, a new entry will be created when the user presses Enter.
This configuration option only applies if forceSelection is false.
</li>
<li>
<a href="#">createNewOnBlur</a> is defaulted to false. If set to true, a new entry will be created when focus leaves the input
field. This configuration option only applies if forceSelection is false, and is superceded by
<a href="http://docs.sencha.com/ext-js/4-0/#/api/Ext.form.field.ComboBox-cfg-autoSelect">autoSelect</a> and
<a href="http://docs.sencha.com/ext-js/4-0/#/api/Ext.form.field.ComboBox-cfg-selectOnTab">selectOnTab</a>.
</li>
</ul>
<div id="emailSuggest"></div>
</div>
<div class="example">
<h2>Other configuration options</h2>
<p>The following configuration options are specific to the BoxSelect.</p>
<ul class="config-options">
<li><a href="#">createNewOnEnter</a> - please see the above forceSelection: false example.</li>
<li><a href="#">createNewOnBlur</a> - please see the above forceSelection: false example.</li>
<li><a href="#">stacked</a> is defaulted to false. If set to true, the labelled items will fill to the width of the list instead
of being only as wide as the displayed value</li>
<li><a href="#">pinList</a> is defaulted to true. If set to false, the pick list will automatically collapse after a selection is made
when multiSelect is true. This mimics the default behavior when multiSelect is false.</li>
</ul>
<div id="stackedSelect"></div>
</div>
<div class="example">
<h2>Value setting and events</h2>
<p>The following shows examples of manually managing the values of the field and displays the value-based events. Except where noted,
the mixedValue parameters can be specified in any of the forms listed in the Basic Configuration examples above. In general, getRawValue
and setRawValue should not be used, as of ExtJS 4 they are formally for the rendered field output only.</p>
<ul class="config-options">
<li><a href="#">addValue(mixedValue)</a></li>
<li><a href="#">removeValue(mixedValue)</a></li>
<li><a href="#">getValueRecords()</a></li>
</ul>
<div id="valueSetting"></div>
</div>
</body>
</html>