Skip to content

Commit f7d75b6

Browse files
kevin-brownkevin-brown
committed
Added more documentation
This adds documentation for a `dropdownParent` option which has not yet been created, but will come in the next commit.
1 parent 4cdda7e commit f7d75b6

3 files changed

Lines changed: 197 additions & 6 deletions

File tree

‎docs/_includes/head.html‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
<link href="vendor/css/prettify.css" type="text/css" rel="stylesheet" />
1818

1919
<style type="text/css">
20-
.navbar-inverse .navbar-brand { color: #fff; }
20+
body { font-size: 16px; }
2121
footer { background-color: #eee; margin-top: 1em; padding: 1em; text-align: center; }
22+
.navbar-inverse .navbar-brand { color: #fff; }
2223
</style>

‎docs/examples.html‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -372,9 +372,9 @@ <h1>Custom matcher</h1>
372372

373373
<p>
374374
This custom matcher uses a
375-
<a href="compatibility.html">compatibility module</a> that is only
376-
bundled in the
377-
<a href="getting-started#versions">full version of Select2</a>. You also
375+
<a href="options.html#compat-matcher">compatibility module</a> that is
376+
only bundled in the
377+
<a href="index.html#versions">full version of Select2</a>. You also
378378
have the option of using a
379379
<a href="options.html#matcher">more complex matcher</a>.
380380
</p>

‎docs/options.html‎

Lines changed: 192 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,8 @@ <h3 id="placeholder">
8686
<dt>Decorator</dt>
8787
<dd>
8888
<code title="select2/selection/placeholder">Placeholder</code>
89+
and
90+
<code title="select2/dropdown/hidePlaceholder">HidePlaceholder</code>
8991
</dd>
9092
</dl>
9193
</div>
@@ -108,6 +110,10 @@ <h3 id="placeholder">
108110
placeholders.
109111
</p>
110112

113+
<pre class="prettyprint linenums">
114+
placeholder: "Select a repository",
115+
</pre>
116+
111117
<p>
112118
If the <strong>value is an object</strong>, the object should be
113119
compatible with Select2's internal objects. The <code>id</code> should
@@ -116,13 +122,78 @@ <h3 id="placeholder">
116122
when that option is selected.
117123
</p>
118124

125+
<pre class="prettyprint linenums">
126+
placeholder: {
127+
id: "-1",
128+
text: "Select a repository"
129+
}
130+
</pre>
131+
119132
<div class="alert alert-info">
120-
You <strong>pass in an object</strong> when you are using a framework that
121-
<strong>creates its own placeholder option</strong>. The
133+
You should <strong>pass in an object</strong> when you are using a
134+
framework that <strong>creates its own placeholder option</strong>. The
122135
<strong>id</strong> should be the same as the <code>value</code>
123136
attribute on the <code>option</code>.
124137
</div>
125138

139+
<p id="allowClear">
140+
You can allow a selected option to be cleared back to the placeholder by
141+
enabling the <code>allowClear</code> option.
142+
</p>
143+
144+
<div class="row">
145+
<div class="col-sm-6">
146+
<dl class="dl-horizontal">
147+
<dt>Key</dt>
148+
<dd><code>allowClear</code></dd>
149+
150+
<dt>Value</dt>
151+
<dd>boolean</dd>
152+
</dl>
153+
</div>
154+
155+
<div class="col-sm-6">
156+
<dl class="dl-horizontal">
157+
<dt>Adapter</dt>
158+
<dd>
159+
<code title="select2/selection/base">SelectionAdapter</code>
160+
</dd>
161+
162+
<dt>Decorator</dt>
163+
<dd>
164+
<code title="select2/selection/allowClear">AllowClear</code>
165+
</dd>
166+
</dl>
167+
</div>
168+
</div>
169+
170+
<p>
171+
This will display an "x" that the user can click to clear the current
172+
selection. It is designed to be used for cases where a single selection
173+
can be made.
174+
</p>
175+
176+
<h3 id="multiple">
177+
Multiple selections
178+
</h3>
179+
180+
<p>
181+
Select2 can display either a single selection or multiple selections.
182+
</p>
183+
184+
<dl class="dl-horizontal">
185+
<dt>Key</dt>
186+
<dd><code>multiple</code></dd>
187+
188+
<dt>Value</dt>
189+
<dd>boolean (<code>true</code> or <code>false</code>)</dd>
190+
</dl>
191+
192+
This option will determine what the <code>SelectAdapter</code> (used by
193+
default) should use to set the value of the underlying <code>select</code>
194+
element. It will also determine if the <code>MultipleSelection</code>
195+
adapter should be used.
196+
126197
<h3 id="language">
127198
Internationalization (Language support)
128199
</h3>
@@ -369,6 +440,125 @@ <h3 id="tags">
369440
</p>
370441
</section>
371442

443+
<section id="dropdown">
444+
<div class="page-header">
445+
<h1>Dropdown</h1>
446+
</div>
447+
448+
<p>
449+
Select2 allows you to change the way that the dropdown works, allowing you
450+
to do anything from attach it to a different location in the document or
451+
add a search box.
452+
</p>
453+
454+
<h2 id="dropdownParent">
455+
Attached to body
456+
</h2>
457+
458+
<p>
459+
By default, Select2 will attach the dropdown to the end of the body and
460+
will absolutely position it to appear below the selection container.
461+
</p>
462+
463+
<div class="row">
464+
<div class="col-sm-4">
465+
<dl class="dl-horizontal">
466+
<dt>Key</dt>
467+
<dd><code>dropdownParent</code></dd>
468+
469+
<dt>Value</dt>
470+
<dd>jQuery element</dd>
471+
472+
<hr />
473+
474+
<dt>Adapter</dt>
475+
<dd>
476+
<code title="select2/dropdown">DropdownAdapter</code>
477+
</dd>
478+
479+
<dt>Decorator</dt>
480+
<dd>
481+
<code title="select2/dropdown/attachBody">AttachBody</code>
482+
</dd>
483+
</dl>
484+
</div>
485+
486+
<div class="col-sm-8">
487+
<div class="alert alert-warning">
488+
<strong>Heads up!</strong>
489+
This will cause DOM events to be raised outside of the standard
490+
Select2 DOM container. This can cause issues with
491+
third-party components such as modals.
492+
</div>
493+
</div>
494+
</div>
495+
496+
<p>
497+
When the dropdown is attached to the body, you are not limited to just
498+
displaying the dropdown below the container. Select2 will display above
499+
the container if there is not enough space below the container, but there
500+
is enough space above it. You are also not limited to displaying the
501+
drodown within the parent container, which means Select2 will render
502+
correctly inside of modals and other small containers.
503+
</p>
504+
505+
<h2 id="dropdown-attachContainer">
506+
Attached below the container
507+
</h2>
508+
509+
<p>
510+
Select2 can place the dropdown directly after the selection cotainer, so
511+
it will appear in the same location within the DOM as the rest of Select2.
512+
</p>
513+
514+
<dl class="dl-horizontal">
515+
<dt>Adapter</dt>
516+
<dd>
517+
<code title="select2/dropdown">DropdownAdapter</code>
518+
</dd>
519+
520+
<dt>Decorator</dt>
521+
<dd>
522+
<code title="select2/dropdown/attachContainer">AttachContainer</code>
523+
</dd>
524+
</dl>
525+
526+
<div class="alert alert-info">
527+
<strong>
528+
<a href="https://harvesthq.github.io/chosen/">Harvest Chosen</a>
529+
migrators!
530+
</strong>
531+
If you are migrating to Select2 from Chosen, this option will cause
532+
Select2 to position the dropdown in a similar way.
533+
</div>
534+
535+
<h2 id="dropdown-search">
536+
Search
537+
</h2>
538+
539+
<p>
540+
Users can filter down the results by typing a search term into a box that
541+
is displayed at the top of the dropdown.
542+
</p>
543+
544+
<dl class="dl-horizontal">
545+
<dt>Adapter</dt>
546+
<dd>
547+
<code title="select2/dropdown">DropdownAdapter</code>
548+
</dd>
549+
550+
<dt>Decorator</dt>
551+
<dd>
552+
<code title="select2/dropdown/search">DropdownSearch</code>
553+
</dd>
554+
</dl>
555+
556+
<p>
557+
A search box is added to the top of the dropdown automatically for select
558+
boxes where only a single option can be selected.
559+
</p>
560+
</section>
561+
372562
<section id="adapters">
373563
<div class="page-header">
374564
<h1>Adapters</h1>

0 commit comments

Comments
 (0)