commit 05cc3a577aa27daaf68f3f0a9c8e6dde056e98a1 Author: alexweissman Date: Sat Sep 2 20:34:47 2017 -0400 first take diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 00000000..ad9ae2a8 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,17 @@ +# v1.0.2 +## 06/22/2015 + +1. [](#new) + * Added sub-topic pages + +# v1.0.1 +## 06/17/2015 + +1. [](#new) + * Added screenshot + +# v1.0.0 +## 06/17/2015 + +1. [](#new) + * ChangeLog started... diff --git a/LICENSE b/LICENSE new file mode 100644 index 00000000..6c650053 --- /dev/null +++ b/LICENSE @@ -0,0 +1,22 @@ +The MIT License (MIT) + +Copyright (c) 2015 Grav + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + diff --git a/README.md b/README.md new file mode 100644 index 00000000..6b30057d --- /dev/null +++ b/README.md @@ -0,0 +1,59 @@ +# RTFM Skeleton + +![RTFM Screenshot](assets/rtfm-screenshot.png) + +This is a sample skeleton site that mimics the official Grav documentation: http://learn.getgrav.org. This skeleton uses the [learn2 theme](https://github.com/getgrav/grav-theme-learn2) + +# Features + +* Lightweight and minimal for optimal performance +* Fully responsive with off-page mobile navigation +* SCSS based CSS source files for easy customization +* Built specifically for providing easy to read documentation +* [Font Awesome](http://fontawesome.io/) icon support +* Viewed page tracking +* Integrated support for documentation content sourced/maintained via GitHub + +>> If you want more information about using Grav with GitHub, check out [part 1](http://getgrav.org/blog/developing-with-github-part-1) and [part 2](http://getgrav.org/blog/developing-with-github-part-2) of our guide called *Grav Development with Github*. + +# Supported Page Templates + +* "Docs" template +* "Chapter" template +* Error view template + +# Configuration + +``` +top_level_version: false +home_url: +github: + enabled: true + position: top + tree: https://github.com/getgrav/grav-skeleton-rtfm-site/blob/develop/ + commits: https://github.com/getgrav/grav-skeleton-rtfm-site/commits/develop/ +``` + +| Setting | Child Setting | Description | +| :----- | :----- | :----- | +| top_level_version | | When set to `true`, displays level icons and numbered lists. | +| home_url | | Enables you to enter a different URL link from the logo (ex: http://google.com) | +| github | enabled | Can be set to `true` or `false`. When set to `true`, it generates the **Edit this page** link to GitHub for each page. | +| github | position | Sets the position for the GitHub edit link. Can be set to `top` or `bottom`. | +| github | tree | Sets the tree by which your site's content is based. Generally the repo your site's content is pulled from. | +| github | commits | Sets the link to the commits page for the site's content repo. | + +## Basic Setup for a New Grav Site + +The simplest way to install the learn2 theme with RTFM content for Grav is to download and install the RTFM Skeleton package: + +1. [Download RTFM Skeleton](http://getgrav.org/downloads/skeletons#extras) +2. Unzip the package into your web root folder. +3. Point your browser at the folder. +4. Job done! + +**TIP:** Check out the [general Grav Installation Instructions](http://learn.getgrav.org/basics/installation) for more details on this process. + +--- + + diff --git a/accounts/.gitkeep b/accounts/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/assets/rtfm-screenshot.png b/assets/rtfm-screenshot.png new file mode 100644 index 00000000..f5918017 Binary files /dev/null and b/assets/rtfm-screenshot.png differ diff --git a/blueprints.yaml b/blueprints.yaml new file mode 100644 index 00000000..4062ec58 --- /dev/null +++ b/blueprints.yaml @@ -0,0 +1,13 @@ +name: RTFM Site +version: 1.0.2 +description: "RTFM is a sample documentation site using the `learn2` theme. This skeleton is used as the basis for the Grav official documentation: http://learn.getgrav.org" +icon: book +author: + name: Team Grav + email: devs@getgrav.org + url: http://getgrav.org +homepage: https://github.com/getgrav/grav-skeleton-rtfm-site +demo: http://demo.getgrav.org/rtfm-skeleton +keywords: rtfm, skeleton, documentation, docs +bugs: https://github.com/getgrav/grav-skeleton-rtfm-site/issues +license: MIT diff --git a/config/plugins/anchors.yaml b/config/plugins/anchors.yaml new file mode 100644 index 00000000..56003de5 --- /dev/null +++ b/config/plugins/anchors.yaml @@ -0,0 +1 @@ +selectors: '#body h2, #body h3, #body h4, #body h5' diff --git a/config/plugins/highlight.yaml b/config/plugins/highlight.yaml new file mode 100644 index 00000000..235212f5 --- /dev/null +++ b/config/plugins/highlight.yaml @@ -0,0 +1 @@ +theme: learn diff --git a/config/plugins/simplesearch.yaml b/config/plugins/simplesearch.yaml new file mode 100644 index 00000000..29412036 --- /dev/null +++ b/config/plugins/simplesearch.yaml @@ -0,0 +1,6 @@ +enabled: true +built_in_css: false +route: /search +template: simplesearch_results +filters: + category: docs diff --git a/config/site.yaml b/config/site.yaml new file mode 100644 index 00000000..de48656e --- /dev/null +++ b/config/site.yaml @@ -0,0 +1,8 @@ +title: Select2 - The jQuery replacement for select boxes +metadata: + description: Select2 is a jQuery based replacement for select boxes. It supports searching, remote data sets, and pagination (infinite scrolling) of results. + +taxonomies: [category,tag] +summary: + size: 300 + diff --git a/config/system.yaml b/config/system.yaml new file mode 100755 index 00000000..7e890b07 --- /dev/null +++ b/config/system.yaml @@ -0,0 +1,35 @@ +home: + alias: '/getting-started' + +pages: + theme: site + markdown_extra: true + process: + markdown: true + twig: false + +cache: + enabled: true + check: + method: file + driver: auto + prefix: 'g' + +twig: + cache: true + debug: false + auto_reload: true + autoescape: false + +assets: + css_pipeline: true + css_minify: true + css_rewrite: true + js_pipeline: true + js_minify: true + +debugger: + enabled: false + twig: true + shutdown: + close_connection: true diff --git a/data/.gitkeep b/data/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/localhost/config/security.yaml b/localhost/config/security.yaml new file mode 100644 index 00000000..1e631371 --- /dev/null +++ b/localhost/config/security.yaml @@ -0,0 +1 @@ +salt: dc7HfDXRG0WT48 diff --git a/localhost/config/system.yaml b/localhost/config/system.yaml new file mode 100644 index 00000000..1bb055a7 --- /dev/null +++ b/localhost/config/system.yaml @@ -0,0 +1,10 @@ +assets: + css_pipeline: false + js_pipeline: false + +twig: + cache: true + debug: true + +debugger: + enabled: false diff --git a/pages/01.getting-started/01.installation/docs.md b/pages/01.getting-started/01.installation/docs.md new file mode 100644 index 00000000..e0af5612 --- /dev/null +++ b/pages/01.getting-started/01.installation/docs.md @@ -0,0 +1,67 @@ +--- +title: Installation +taxonomy: + category: docs +--- + +In order to use Select2, you must include the JavaScript and CSS file on +your website. You can get these files built for you from many different +locations. + +## Using Select2 from a CDN + +Select2 is hosted on both the +cdnjs and +jsDelivr CDNs, allowing +you to quickly include Select2 on your website. + +### Include the assets + +Include the following lines of code in the <head> +section of your HTML. + +``` + + +``` + +>>> Immediately following a new release, it takes some time for CDNs to + catch up and get the new versions live on the CDN. + +### Initialize Select2 + +Initialize Select2 on the <select> element that you want to make awesome. + +``` + +``` + +### Read the docs + +Check out the examples chapter to start using the additional features of Select2. + +## Downloading the code locally + +In some situations, you can't use Select2 from a CDN and you must include the files through your own static file servers. + +### Download the code + + + Download the code + +from GitHub and copy the `dist` directory to your project. + +### Include the assets + +Include the following lines of code in the `` section of your HTML. + +``` + + +``` + +### Read the docs + +Check out the examples chapter to start using the additional features of Select2. diff --git a/pages/01.getting-started/02.basic-usage/docs.md b/pages/01.getting-started/02.basic-usage/docs.md new file mode 100644 index 00000000..5ee9abc1 --- /dev/null +++ b/pages/01.getting-started/02.basic-usage/docs.md @@ -0,0 +1,95 @@ +--- +title: Basic Usage +taxonomy: + category: docs +process: + twig: true +never_cache_twig: true +--- + +## Single select boxes + +Select2 was designed to be a replacement for the standard ` + +and turn it into this... + +
+ +
+ +``` + +``` + + + +Select2 will register itself as a jQuery function if you use any of the distribution builds, so you can call `.select2()` on any jQuery selector where you would like to initialize Select2. + +``` +$('.js-example-basic-single').select2(); +``` + +## Multi-select boxes (pillbox) + +Select2 also supports multi-value select boxes. The select below is declared with the `multiple` attribute. + +
+

+ +

+
+ +``` + + + +``` + + diff --git a/pages/01.getting-started/03.builds-and-modules/docs.md b/pages/01.getting-started/03.builds-and-modules/docs.md new file mode 100644 index 00000000..bfbf3b01 --- /dev/null +++ b/pages/01.getting-started/03.builds-and-modules/docs.md @@ -0,0 +1,63 @@ +--- +title: Builds and modules +taxonomy: + category: docs +--- + +## The different Select2 builds + +Select2 provides multiple builds that are tailored to different +environments where it is going to be used. If you think you need to use +Select2 in a nonstandard environment, like when you are using AMD, you +should read over the list below. + + + + + + + + + + + + + + + + + + +
Build nameWhen you should use it
+ Standard (select2.js / select2.min.js) + + This is the build that most people should be using for Select2. It + includes the most commonly used features. +
+ Full (select2.full.js / select2.full.min.js) + + You should only use this build if you need the additional features + from Select2, like the + compatibility modules or + recommended includes like + jquery.mousewheel +
+ +## Using Select2 with AMD or CommonJS loaders + +Select2 should work with most AMD- or CommonJS-compliant module loaders, including RequireJS and almond. Select2 ships with a modified version of the UMD jQuery template that supports both CommonJS and AMD environments. + +### Configuration + +For most AMD and CommonJS setups, the location of the data files used by Select2 will be automatically determined and handled without you needing to do anything. + +If you are using Select2 in a build environment where preexisting module names are changed during a build step, Select2 may not be able to find optional dependencies or language files. You can manually set the prefixes to use for these files using the `amdBase` and `amdLanguageBase` options. + +``` +$.fn.select2.defaults.set('amdBase', 'select2/'); +$.fn.select2.defaults.set('amdLanguageBase', 'select2/i18n/'); +``` + +Select2 internally uses AMD and the r.js build tool to build the files located in the `dist` folder. These are built using the files in the `src` folder, so _you can_ just point your modules to the Select2 source and load in `jquery.select2` or `select2/core` when you want to use Select2. The files located in the `dist` folder are also AMD-compatible, so you can point to that file if you want to load in all of the default Select2 modules. + +>>> Due to [a bug in older versions](https://github.com/jrburke/requirejs/issues/1342) of the r.js build tool, Select2 was sometimes placed before jQuery in then compiled build file. Because of this, Select2 will trigger an error because it won't be able to find or load jQuery. By upgrading to version 2.1.18 or higher of the r.js build tool, you will be able to fix the issue. diff --git a/pages/01.getting-started/chapter.md b/pages/01.getting-started/chapter.md new file mode 100644 index 00000000..9df28cd5 --- /dev/null +++ b/pages/01.getting-started/chapter.md @@ -0,0 +1,73 @@ +--- +title: Getting Started +taxonomy: + category: docs +--- + +![Select2 logo](/images/logo.png) + +# Select2 + +The jQuery replacement for select boxes + +Select2 gives you a customizable select box with support for searching, tagging, remote data sets, infinite scrolling, and many other highly used options. + +
+
+
+ +

In your language

+

+ Select2 comes with support for + RTL environments, + searching with diacritics and + over 40 languages built-in. +

+
+ +
+ +

Remote data support

+

+ Using AJAX you can efficiently + search large lists of items. +

+
+ +
+ +

Theming

+

+ Fully skinnable, CSS built with Sass and an + optional theme for Bootstrap 3. +

+
+
+ +
+
+ +

Fully extensible

+

+ The plugin system + allows you to easily customize Select2 to work exactly how you want it + to. +

+
+ +
+ +

Dynamic item creation

+

+ Allow users to type in a new option and + add it on the fly. +

+
+ +
+ +

Full browser support

+

Support for both modern and legacy browsers is built-in, even including Internet Explorer 8.

+
+
+
diff --git a/pages/02.configuration/01.initializing/01.data-attributes/docs.md b/pages/02.configuration/01.initializing/01.data-attributes/docs.md new file mode 100644 index 00000000..539af56e --- /dev/null +++ b/pages/02.configuration/01.initializing/01.data-attributes/docs.md @@ -0,0 +1,61 @@ +--- +title: Via data-* attributes +taxonomy: + category: docs +--- + +It is recommended that you declare your configuration options by [passing in an object](/options/initializing) when initializing Select2. However, you may also define your configuration options by using the HTML5 `data-*` attributes, which will override any options set when initializing Select2 and any [defaults](/options/initializing/defaults). + +``` + +``` + +## Nested (subkey) options + +Sometimes, you have options that are nested under a top-level option. For example, the options under the `ajax` option: + +``` +$(".js-example-data-ajax").select2({ + ajax: { + url: "http://example.org/api/test", + cache: false + } +}); +``` + +To write these options as `data-*` attributes, each level of nesting should be separated by two dashes (`--`): + +``` + +``` + +The value of the option is subject to jQuery's parsing rules for HTML5 data attributes. + +>>> Due to a jQuery bug, nested options using data-* attributes do not work in jQuery 1.x. + +## `camelCase` options + +HTML data attributes are case-insensitive, so any options which contain capital letters will be parsed as if they were all lowercase. Because Select2 has many options which are camelCase, where words are separated by uppercase letters, you must write these options out with dashes instead. So an option that would normally be called allowClear should instead be defined as `allow-clear`. + +This means that if you declare your <select> tag as... +``` + +``` + +Will be interpreted the same as initializing Select2 as... + +``` +$("select").select2({ + tags: "true", + placeholder: "Select an option", + allowClear: true +}); +``` diff --git a/pages/02.configuration/01.initializing/02.defaults/docs.md b/pages/02.configuration/01.initializing/02.defaults/docs.md new file mode 100644 index 00000000..c166835a --- /dev/null +++ b/pages/02.configuration/01.initializing/02.defaults/docs.md @@ -0,0 +1,31 @@ +--- +title: Global defaults +taxonomy: + category: docs +--- + +In some cases, you need to set the default options for all instances of Select2 in your web application. This is especially useful when you are migrating from past versions of Select2, or you are using non-standard options like custom AMD builds. Select2 exposes the default options through $.fn.select2.defaults, which allows you to set them globally. + +When setting options globally, any past defaults that have been set will be overridden. Default options are only used when an option is requested that has not been set during initialization. + +You can set default options by calling `$.fn.select2.defaults.set("key", "value")`. For example: + +``` +$.fn.select2.defaults.set("theme", "classic"); +``` + +## Nested options + +To set a default values for cache, use the same notation used for HTML data-* attributes. Two dashes (`--`) will be replaced by a level of nesting, and a single dash (`-`) will convert the key to a camelCase string: + +``` +$.fn.select2.defaults.set("ajax--cache", false); +``` + +## Resetting default options + +You can reset the default options to their initial values by calling + +``` +$.fn.select2.defaults.reset(); +``` diff --git a/pages/02.configuration/01.initializing/docs.md b/pages/02.configuration/01.initializing/docs.md new file mode 100644 index 00000000..2c1595b5 --- /dev/null +++ b/pages/02.configuration/01.initializing/docs.md @@ -0,0 +1,14 @@ +--- +title: Initializing +taxonomy: + category: docs +--- + + +To configure custom options, simply pass an object containing all of the options with which you would like to initialize Select2, in your call to `.select2()`: + +``` +$('.js-example-basic-single').select2({ + placeholder: 'Select an option' +}); +``` diff --git a/pages/02.configuration/02.deprecated/docs.md b/pages/02.configuration/02.deprecated/docs.md new file mode 100644 index 00000000..83c7c7e6 --- /dev/null +++ b/pages/02.configuration/02.deprecated/docs.md @@ -0,0 +1,210 @@ +--- +title: Deprecated options +taxonomy: + category: docs +--- + +
+

+ Select2 offers limited backwards compatibility with the previously 3.5.x + release line, allowing people more efficiently transfer across releases + and get the latest features. For many of the larger changes, such as the + change in how custom data adapters work, compatibility modules were + created that will be used to assist in the upgrade process. It is not + recommended to rely on these compatibility modules, as they will not + always exist, but they make upgrading easier for major changes. +

+ +

+ The compatibility modules are only included in the + full builds of + Select2. These files end in .full.js, and the + compatibility modules are prefixed with select2/compat. +

+
+ +
+

+ Simplified function for matching data objects +

+ +

+ Added in Select2 4.0.0. + This method was added to make upgrading easier from earlier versions of + Select2. +

+ +

+ During the Select2 4.0.0 release, the + matcher function was changed to allow for more complex + matching of nested objects. +

+ +
+
+
+
Key
+
+ matcher +
+ +
Value
+
+ A function taking a search term and the data object + text. +
+
+
+ +
+
+
Adapter
+
+ oldMatcher +
+
+
+
+ +

+ The custom matcher example provides a + guide for how to use this in your own application. For those upgrading + from older versions of Select2, you just need to wrap your old + matcher with this function to maintain compatibility. +

+
+ +
+

+ Old initial selections with initSelection +

+ +

+ Deprecated in Select2 4.0. + This has been replaced by another option and is only available in the + full builds of + Select2. +

+ +

+ In the past, Select2 required an option called initSelection + that was defined whenever a custom data source was being used, allowing + for the initial selection for the component to be determined. This has + been replaced by the current method on the + data adapter. +

+ +
+
+
+
Key
+
+ initSelection +
+ +
Value
+
+ A function taking a callback +
+
+
+ +
+
+
Adapter
+
+ DataAdapter +
+ +
Decorator
+
+ InitSelection +
+
+
+
+
+ +
+

+ Querying old data with query +

+ +

+ Deprecated in Select2 4.0. + This has been replaced by another option and is only available in the + full builds of + Select2. +

+ +

+ In the past, Select2 supported an option called query that + allowed for a custom data source to be used. This option has been replaced + by the query method on the + data adapter and takes a very similar set of + parameters. +

+ +
+
+
+
Key
+
+ query +
+ +
Value
+
+ A function taking params (including a callback) +
+
+
+ +
+
+
Adapter
+
+ DataAdapter +
+ +
Decorator
+
+ Query +
+
+
+
+
+ +
+

+ Compatibility with <input type="text" /> +

+ +

+ Deprecated in Select2 4.0. + It is now encouraged to use the <select> tag instead. +

+ +

+ In past versions of Select2, a <select> element could + only be used with a limited subset of options. An + <input type="hidden" /> was required instead, which did + not allow for a graceful fallback for users who did not have JavaScript + enabled. Select2 now supports the <select> element for + all options, so it is no longer required to use <input /> + elements with Select2. +

+ +
+
Adapter
+
+ DataAdapter +
+ +
Decorator
+
+ InputData +
+
+
diff --git a/pages/02.configuration/docs.md b/pages/02.configuration/docs.md new file mode 100644 index 00000000..b66ec422 --- /dev/null +++ b/pages/02.configuration/docs.md @@ -0,0 +1,298 @@ +--- +title: Configuration +taxonomy: + category: docs +--- + +Select2 has the following configuration options available. Note that this page is a work +in progress. The previous +release's documentation should cover the gaps here for the time being. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OptionTypeDescription
adaptContainerCssClass
adaptDropdownCssClass
ajax
allowClearboolean +

When set to true, causes a clear button to appear on the select box + when a value is selected. Clicking the clear button will clear the selected value, + effectively resetting the select box back to its placeholder value.

+ +

Default value: false

+
amdBasestring +

The base AMD loader path to be used for select2 dependency resolution. This option + typically doesn't need to be changed, but is available for situations where module names + may change as a result of certain build environments.

+ +

Default value: "./"

+
amdLanguageBasestring +

The base AMD loader language path to be used for select2 language file resolution. This + option typically doesn't need to be changed, but is available for situations where module + names may change as a result of certain build environments.

+ +

Default value: "./i18n/"

+
closeOnSelectboolean +

When set to false, keeps the dropdown open upon selecting an option, + making it easy to quickly select multiple items. Note that this option is only + applicable to multi-select controls.

+ +

Default value: true

+
containerCss
containerCssClass
dataAdapter
debugboolean
dir
disabledboolean +

When set to true, the select control will be disabled.

+ +

Default value: false

+
escapeMarkup
initSelection
language
matcher
maximumInputLengthinteger +

Maximum number of characters that may be provided for a search term.

+ +

Default value: 0

+
maximumSelectionLengthinteger +

The maximum number of items that may be selected in a multi-select control. If the + value of this option is less than 1, the number of selected items will not be limited.

+ +

Default value: 0

+
minimumInputLengthinteger +

Minimum number of characters required to start a search. This options is primarily + useful in cases where data is loaded via the ajax option.

+ +

Default value: 0

+
minimumResultsForSearchinteger +

The minimum number of results required in the initial population of the dropdown to + keep the search box. This option is useful for cases where local data is used with a small + result set, and the search box would simply be a waste of screen real estate. Set this + value to -1 to permanently hide the search box.

+ +

Default value: 0

+
multiple + This option enables multi-select (pillbox) mode. Select2 will automatically map the value of the `multiple` HTML attribute to this option during initialization. +
placeholder
query
resultsAdapter
selectionAdapter
selectOnCloseboolean +

Default value: false

+
sorterfunction
tags
templateResultfunction
templateSelectionfunction
themestring +

Default value: default

+
tokenizer
tokenSeparators
widthstring +

Specifies the width style attribute of the select2 container. The + following values are supported:

+ +
+
element
+
Uses the computed element width from any applicable CSS rules.
+ +
resolve
+
Uses the style attribute value if available, falling + back to the computed element width as necessary.
+ +
style
+
Width is determined from the select element's style + attribute. If no style attribute is found, null is returned as the + width.
+ +
{width_value}
+
Valid CSS values can be passed as a string (i.e. 80%).
+
+ +

Default value: resolve

+
diff --git a/pages/03.appearance/01.markup/docs.md b/pages/03.appearance/01.markup/docs.md new file mode 100644 index 00000000..2ea41f5e --- /dev/null +++ b/pages/03.appearance/01.markup/docs.md @@ -0,0 +1,115 @@ +--- +title: Basic markup +taxonomy: + category: docs +process: + twig: true +never_cache_twig: true +--- + +A standard `` element that contains `` element: + +``` + +``` + +Select2 will automatically pick these up and render them appropriately in the dropdown. + +### Hierarchical options + +Only a single level of nesting is allowed per the HTML specification. If you nest an `` within another ``, Select2 will not be able to detect the extra level of nesting and errors may be triggered as a result. + +Furthermore, `` elements **cannot** be made selectable. This is a limitation of the HTML specification and is not a limitation that Select2 can overcome. + +If you wish to create a true hierarchy of selectable options, use an `` and change the style with CSS. Please note that this approach may be considered "less accessible" as it relies on CSS styling, rather than the semantic meaning of ``, to generate the effect. diff --git a/pages/06.selections/docs.md b/pages/06.selections/docs.md new file mode 100644 index 00000000..109d9527 --- /dev/null +++ b/pages/06.selections/docs.md @@ -0,0 +1,92 @@ +--- +title: Selections +taxonomy: + category: docs +process: + twig: true +never_cache_twig: true +--- + +When a selection is made by the user, Select2 will convert the selected `` elements will be converted into data objects using the following rules: + +``` +{ + "text": "label attribute", + "children": [ option data object, ... ], + "element": HTMLOptGroupElement +} +``` + +By default, Select2 will then display the `text` property of the selected result. + +## Templating + +The appearance of selected results can be customized by using the `templateSelection` configuration option. This takes a callback that transforms the selection data object into a string representation or jQuery object: + +
+ +
+ +

+
+
+
+If your selection template contains HTML, you must wrap your rendered result in a jQuery object. Otherwise, Select2 will assume that your template only returns text and will escape it.  You may find it helpful to use a client-side templating engine like [Handlebars](http://handlebarsjs.com/) to define your templates.
+
+## Limiting the number of selections
+
+Select2 multi-value select boxes can set restrictions regarding the maximum number of options that can be selected. The select below is declared with the `multiple` attribute with `maximumSelectionLength` in the select2 options.
+
+

+    

+      
+    

+

+
+

+
+
+
+## Clearable selections
+
+You can allow users to clear their current selections with the `allowClear` option when initializing Select2. Setting this option to `true` will enable an "x" icon that will reset the selection to the placeholder.
+
+```
+$('select').select2({
+  placeholder: 'This is my placeholder',
+  allowClear: true
+});
+```
diff --git a/pages/07.placeholders/docs.md b/pages/07.placeholders/docs.md
new file mode 100644
index 00000000..5ac4c2b6
--- /dev/null
+++ b/pages/07.placeholders/docs.md
@@ -0,0 +1,81 @@
+---
+title: Placeholders
+taxonomy:
+    category: docs
+process:
+    twig: true
+never_cache_twig: true
+---
+
+Select2 supports displaying a placeholder value using the `placeholder` configuration option. The placeholder value will be displayed until a selection is made.
+
+## Text placeholders
+
+The most common situation is to use a string of text as your placeholder value.
+
+**In order for a string placeholder value to appear**, you must have a blank `
+    
+  

+  

+    
+  

+
+
+

+
+
+
+>>> Select2 uses the `placeholder` attribute on multiple select boxes, which requires IE 10+. You can support it in older versions with the Placeholders.js polyfill.
+
+## Default selection placeholders
+
+Alternatively, the value of the `placeholder` option can be a data object representing a default selection (`` sections, options should be nested under the `children` key of each group object.  The label for the group should be specified as the `text` property on the group's corresponding data object.
+
+```
+{
+  "results": [
+    { 
+      "text": "Group 1", 
+      "children" : [
+        {
+            "id": 1,
+            "text": "Option 1.1"
+        }
+        {
+            "id": 2,
+            "text": "Option 1.2"
+        }
+      ]
+    },
+    { 
+      "text": "Group 2", 
+      "children" : [
+        {
+            "id": 3,
+            "text": "Option 2.1"
+        }
+        {
+            "id": 4,
+            "text": "Option 2.2"
+        }
+      ]
+    }
+  ],
+  "paginate": {
+    "more": true
+  }
+}
+```
+
+>>>> Because Select2 generates an `` when creating nested options, only [a single level of nesting is supported](/dropdown/option-groups). Any additional levels of nesting is not guaranteed to be displayed properly across all browsers and devices.
diff --git a/pages/09.data-sources/02.ajax/docs.md b/pages/09.data-sources/02.ajax/docs.md
new file mode 100644
index 00000000..e47147c7
--- /dev/null
+++ b/pages/09.data-sources/02.ajax/docs.md
@@ -0,0 +1,180 @@
+---
+title: Ajax (remote data)
+taxonomy:
+    category: docs
+process:
+    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.
+
+
+
+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.
+
+```
+
+```
+
+You can configure how Select2 searches for remote data using the `ajax` option. More information on the individual options
+that Select2 handles can be found in the [options documentation for `ajax`](/configuration).
+
+

+
+
+
+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 support for data arrays 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 use the ajax.processResults option to transform the data returned by your API into the format expected by Select2:
+
+```
+$('select').select2({
+  ajax: {
+    url: '/example/api',
+    processResults: function (data) {
+      return {
+        results: data.items
+      };
+    }
+  }
+});
+```
+
+## Default values
+
+You may wish to set a pre-selected default value for a Select2 control that receives its data from an AJAX request.
+
+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).
+
+## 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:
+
+```
+$('select').select2({
+  ajax: {
+    data: function (params) {
+      var query = {
+        search: params.term,
+        page: params.page
+      }
+
+      // Query parameters will be ?search=[term]&page=[page]
+      return query;
+    }
+  }
+});
+```
+
+## 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:
+
+```
+$('select').select2({
+  ajax: {
+    url: function (params) {
+      return '/some/url/' + params.term;
+    }
+  }
+});
+```
+
+## Alternative transport methods
+
+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({
+  ajax: {
+    transport: function (params, success, failure) {
+      var request = new AjaxRequest(params.url, params);
+      request.on('success', success);
+      request.on('failure', failure);
+    }
+  }
+});
+```
diff --git a/pages/09.data-sources/03.arrays/docs.md b/pages/09.data-sources/03.arrays/docs.md
new file mode 100644
index 00000000..db4cd225
--- /dev/null
+++ b/pages/09.data-sources/03.arrays/docs.md
@@ -0,0 +1,61 @@
+---
+title: Arrays
+taxonomy:
+    category: docs
+process:
+    twig: true
+never_cache_twig: true
+---
+
+## Loading array data
+
+You may use the `data` configuration option to load dropdown options from a local array.
+
+You can provide initial selections with array data by providing the option tag for the selected values, similar to how it would be done for a standard select.
+
+

+  

+    
+  

+  

+    
+  

+

+
+

+
+
diff --git a/pages/09.data-sources/chapter.md b/pages/09.data-sources/chapter.md
new file mode 100644
index 00000000..7d866b36
--- /dev/null
+++ b/pages/09.data-sources/chapter.md
@@ -0,0 +1,11 @@
+---
+title: Data sources
+taxonomy:
+    category: docs
+---
+
+### Chapter 3
+
+# Data sources
+
+In addition to handling `