Initial commit

.editorconfig

@@ -0,0 +1,18 @@
+# For more information about the properties used in this file,
+# please see the EditorConfig documentation:
+# http://editorconfig.org/
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 2
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.php]
+indent_size = 4
+indent_style = space

.gitattributes

@@ -0,0 +1,19 @@
+# Docs and tests folders
+/docs export-ignore
+/tests export-ignore
+
+# Continuous integration files
+/.travis.yml export-ignore
+/.scrutinizer.yml export-ignore
+
+# Git files
+/.gitattributes export-ignore
+/.gitignore export-ignore
+
+# Editor files
+/.editorconfig export-ignore
+
+# Markdown files
+/CONTRIBUTING.md export-ignore
+/LICENSE.md export-ignore
+/README.md export-ignore

.gitignore

@@ -0,0 +1,23 @@
+### Thumbnails ###
+._*
+Thumbs.db
+
+### Folder Config ###
+.DS_Store
+Desktop.ini
+
+### Log Files ###
+*.log
+
+### SQL Files ###
+*.sql
+
+### Node.js Packages ###
+/**/node_modules
+
+### Sass Cache ###
+.sass-cache
+
+### Source Maps ###
+/**/*.js.map
+/**/*.css.map

CONTRIBUTING.md

@@ -0,0 +1,104 @@
+# Contributing
+
+When contributing to this repository, please first discuss the change you wish to
+make via issue, email, or any other method with the owners of this repository before
+making a change.
+
+In order to contribute code to this project, please follow the
+[pull request workflow](#pull-request-workflow).
+
+Please note we have a [code of conduct](#code-of-conduct), please follow it in all
+your interactions with the project.
+
+## Pull Request Workflow
+
+1. Create a [fork][forking] of the repository.
+2. Add the original repository as an [upstream remote][upstream] to keep your fork
+   up-to-date.
+3. Create a [new branch][branching] for your changes.
+4. [Commit][committing] one or more well-commented and clean changes to your fork.
+5. [Sync][syncing] your fork with the upstream remote to merge any changes.
+6. [Push][pushing] your changes to GitHub.
+7. Create a [pull request][pullreq] using the GitHub web interface.
+
+## Code of Conduct
+
+### Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+### Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+### Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+### Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+### Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at <github@praxis.net.au>. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+### Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
+
+[forking]: https://help.github.com/articles/fork-a-repo
+[upstream]: https://help.github.com/articles/configuring-a-remote-for-a-fork
+[branching]: https://help.github.com/articles/creating-and-deleting-branches-within-your-repository
+[committing]: https://help.github.com/articles/adding-a-file-to-a-repository-using-the-command-line
+[syncing]: https://help.github.com/articles/syncing-a-fork
+[pushing]: https://help.github.com/articles/pushing-to-a-remote
+[pullreq]: https://help.github.com/articles/creating-a-pull-request
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

LICENSE.md

@@ -0,0 +1,22 @@
+Copyright (c) 2017, Praxis Interactive.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
+following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following
+   disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
+   disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote
+   products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
+INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -0,0 +1,200 @@
+# SilverWare Select2 Module
+
+[![Latest Stable Version](https://poser.pugx.org/silverware/select2/v/stable)](https://packagist.org/packages/silverware/select2)
+[![Latest Unstable Version](https://poser.pugx.org/silverware/select2/v/unstable)](https://packagist.org/packages/silverware/select2)
+[![License](https://poser.pugx.org/silverware/select2/license)](https://packagist.org/packages/silverware/select2)
+
+Provides Select2-powered dropdown and Ajax fields for [SilverStripe v4][silverstripe-framework]. Intended to be used
+with [SilverWare][silverware], however this module can also be installed into a regular SilverStripe v4 project.
+
+## Contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Usage](#usage)
+- [Issues](#issues)
+- [Contribution](#contribution)
+- [Attribution](#attribution)
+- [Maintainers](#maintainers)
+- [License](#license)
+
+## Requirements
+
+- [SilverStripe Framework v4][silverstripe-framework]
+
+## Installation
+
+Installation is via [Composer][composer]:
+
+```
+$ composer require silverware/select2
+```
+
+## Configuration
+
+As with all SilverStripe modules, configuration is via YAML. Extensions to `LeftAndMain` are applied via `config.yml`.
+
+## Usage
+
+### Select2Field
+
+The `Select2Field` class is used exactly the same way as a regular old `DropdownField`:
+
+```php
+use SilverWare\Select2\Forms\Select2Field;
+
+$field = Select2Field::create(
+  'MySelect2Field',
+  'Select2 Field',
+  [
+    1 => 'An',
+    2 => 'Array',
+    3 => 'of',
+    4 => 'Options'
+  ]
+);
+```
+
+#### Select2 Configuration
+
+You can define any of the Select2 configuration settings by using the `setConfig()` method:
+
+```php
+$field->setConfig('maximum-input-length', 20);
+```
+
+Alternatively, you can set the defaults for all `Select2Field` instances in your app by using YAML config:
+
+```yaml
+SilverWare\Select2\Forms\Select2Field:
+  default_config:
+    maximum-input-length: 20
+```
+
+**NOTE:** configuration setting names are defined using HTML attribute style, and not camel case, for example:
+
+```php
+$field->setConfig('maximum-input-length', 20);  // this will work
+$field->setConfig('maximumInputLength', 20);    // this will NOT work
+```
+
+### Select2AjaxField
+
+The `Select2AjaxField` is used to search a `DataList` based on a search term entered by the user. The results are
+retrieved from the server via Ajax and rendered as dropdown options. This is very handy for cases where the number of
+available options in a regular dropdown would be prodigious.
+
+The field is created like any other field:
+
+```php
+use SilverWare\Select2\Forms\Select2AjaxField;
+
+$field = Select2AjaxField::create(
+  'MySelect2AjaxField',
+  'Select2 Ajax Field'
+);
+```
+
+But we do not pass an array of options to choose from to the constructor. Instead, we configure the field to search
+a `DataList` on the server-side. Here are the default settings:
+
+```php
+$field->setDataClass(SiteTree::class);  // by default, the field searches for SiteTree records
+
+$field->setIDField('ID');       // the name of the field which identifies the record
+$field->setTextField('Title');  // the name of the field to use for the option text
+
+$field->setSearchFields([
+  'Title'  // an array of fields to search based on the entered term
+]);
+
+$field->setSortBy([
+  'Title' => 'ASC'  // an array which defines the sort order of the results
+]);
+
+$field->setLimit(256);  // the maximum number of records to return
+```
+
+As mentioned, these are the default settings, and the field will work out-of-the-box for `SiteTree` searches.
+
+#### Exclusions
+
+You can also optionally define a series of exclusion filters, which use the same format for the `exclude` method of
+`DataList`:
+
+```php
+$field->setExclude([
+  'Title:ExactMatch' => 'Hide This Title'
+]);
+```
+
+Any records matching the defined exclusion filters will be excluded from the results.
+
+#### Formatting
+
+By default, the field will render a regular series of dropdown options based on the `$ID` and `$Title` of the matching
+records, however you can apply more advanced formatting for both results and the current selection. For example:
+
+```php
+$field->setFormatResult('<span>Found: <em>$Title</em></span>');
+$field->setFormatSelection('<span>Selected: <strong>$Title</strong></span>');
+```
+
+HTML will be rendered as a jQuery object, so be sure to wrap it in an enclosing element such as a `<span>`.
+
+#### Ajax Configuration
+
+Any of the Select2 Ajax settings can be defined using the `setAjaxConfig()` method:
+
+```php
+$field->setAjaxConfig('cache', false);
+$field->setAjaxConfig('delay', 500);
+```
+
+Alternatively, you can set the defaults for all `Select2AjaxField` instances in your app by using YAML config:
+
+```yaml
+SilverWare\Select2\Forms\Select2AjaxField:
+  default_ajax_config:
+    cache: false
+    delay: 500
+```
+
+**NOTE:** configuration setting names are defined using HTML attribute style, and not camel case, for example:
+
+```php
+$field->setAjaxConfig('data-type', 'json');  // this will work
+$field->setAjaxConfig('dataType', 'json');   // this will NOT work
+```
+
+## Issues
+
+Please use the [GitHub issue tracker][issues] for bug reports and feature requests.
+
+## Contribution
+
+Your contributions are gladly welcomed to help make this project better.
+Please see [contributing](CONTRIBUTING.md) for more information.
+
+## Attribution
+
+- Makes use of [Select2][select2] by [Kevin Brown](https://github.com/kevin-brown),
+  [Igor Vaynberg](https://github.com/ivaynberg) and [others](https://github.com/select2/select2/graphs/contributors).
+
+## Maintainers
+
+[![Colin Tucker](https://avatars3.githubusercontent.com/u/1853705?s=144)](https://github.com/colintucker) | [![Praxis Interactive](https://avatars2.githubusercontent.com/u/1782612?s=144)](http://www.praxis.net.au)
+---|---
+[Colin Tucker](https://github.com/colintucker) | [Praxis Interactive](http://www.praxis.net.au)
+
+## License
+
+[BSD-3-Clause](LICENSE.md) &copy; Praxis Interactive
+
+[silverware]: https://github.com/praxisnetau/silverware
+[silverware-select2]: https://github.com/praxisnetau/silverware-select2
+[composer]: https://getcomposer.org
+[silverstripe-framework]: https://github.com/silverstripe/silverstripe-framework
+[issues]: https://github.com/praxisnetau/silverware-select2/issues
+[select2]: https://github.com/select2/select2