diff --git a/docs/gitbook/Advanced/AJAX.md b/docs/gitbook/Advanced/AJAX.md index e69de29..522945c 100644 --- a/docs/gitbook/Advanced/AJAX.md +++ b/docs/gitbook/Advanced/AJAX.md @@ -0,0 +1,60 @@ +## AJAX Remote Option Loading + +[](codepen://sagalbot/POMeOX?height=400) + +The `onSearch` prop allows you to load options via ajax in a parent component +when the search text is updated. It is invoked with two parameters, `search` & `loading`. + +```js +/** +* Accepts a callback function that will be run +* when the search text changes. The callback +* will be invoked with these parameters: +* +* @param {search} String Current search text +* @param {loading} Function Toggle loading class +*/ +onSearch: { + type: Function, + default: false +}, +``` + +The `loading` function accepts a boolean parameter that will be assigned +to the vue-select internal `loading` property. Call `loading(true)` to set the +`loading` property to `true` - toggling the loading spinner. After your +asynchronous operation completes, call `loading(false)` to toggle it off. + +#### Disabling Filtering + +When loading server side options, it can be useful to disable the +client side filtering. Use the `filterable` prop to disable filtering. + +```js +/** + * When true, existing options will be filtered + * by the search text. Should not be used in + * conjunction with taggable. + * + * @type {Boolean} + */ +filterable: { + type: Boolean, + default: true +}, +``` + +#### Loading Spinner + +Vue Select includes a default loading spinner that appears when the loading class is present. The `spinner` slot allows you to implement your own spinner. + +```html + +``` + +#### Library Agnostic + +Since Vue.js does not ship with ajax functionality as part of the core library, it's up to you to process the ajax requests in your parent component. + +I recommend using [axios](https://github.com/axios/axios) for creating your applications HTTP layer, +or [`fetch()`](https://github.com/github/fetch) for simple requests. diff --git a/docs/gitbook/Advanced/Templating.md b/docs/gitbook/Advanced/Templating.md index e69de29..03d18fa 100644 --- a/docs/gitbook/Advanced/Templating.md +++ b/docs/gitbook/Advanced/Templating.md @@ -0,0 +1,17 @@ +#### Scoped Slot `option` + +vue-select provides the scoped `option` slot in order to create custom dropdown templates. + +```html + + + +``` + +Using the `option` slot with `slot-scope="option"` gives the +provides the current option variable to the template. + +[](codepen://sagalbot/NXBwYG?height=500) \ No newline at end of file diff --git a/docs/gitbook/Advanced/Validation.md b/docs/gitbook/Advanced/Validation.md new file mode 100644 index 0000000..220a5a4 --- /dev/null +++ b/docs/gitbook/Advanced/Validation.md @@ -0,0 +1 @@ +[](codepen://sagalbot/zZQJKW?height=600) \ No newline at end of file diff --git a/docs/gitbook/Advanced/Vuex.md b/docs/gitbook/Advanced/Vuex.md index c638457..73c1156 100644 --- a/docs/gitbook/Advanced/Vuex.md +++ b/docs/gitbook/Advanced/Vuex.md @@ -1,18 +1,16 @@ -### Change Event Vuex Compatibility - -`vue-select` provides a `change` event. This function is passed the currently selected value(s) as it's only parameter. - -This is very useful when integrating with Vuex, as it will allow your to trigger an action to update your vuex state object. Choose a callback and see it in action. +### Using the `input` Event with Vuex +`vue-select` emits the `input` event any time the internal `value` is changed. +This is the same event that allow the for the `v-model` syntax. When using +Vuex for state management, you can use the `input` event to dispatch an +action, or trigger a mutation. ```html - -``` + +``` -```js -methods: { - consoleCallback(val) { - console.dir(JSON.stringify(val)) - }, -} -``` +[](codepen://sagalbot/aJQJyp?height=500) \ No newline at end of file diff --git a/docs/gitbook/Ajax/Ajax.md b/docs/gitbook/Ajax/Ajax.md index 0cef7f5..e69de29 100644 --- a/docs/gitbook/Ajax/Ajax.md +++ b/docs/gitbook/Ajax/Ajax.md @@ -1,31 +0,0 @@ -## AJAX Remote Option Loading - - -The `onSearch` prop allows you to load options via ajax in a parent component when the search text is updated. It is invoked with two parameters, `search` & `loading`. - -#### onSearch Callback Parameters search, loading - -`search` is a string containing the current search text. `loading` is a function that accepts a boolean value, and is used to toggle the 'loading' class on the top-level vue-select wrapper. - -#### Loading Spinner - -Vue Select includes a default loading spinner that appears when the loading class is present. The `spinner` slot allows you to implement your own spinner. - -
- - - -#### Debounce Input - -Vue Select also accepts a `debounce` prop that can be used to prevent `onSearch` from being called until input has completed. - -#### Library Agnostic - -Since Vue.js does not ship with ajax functionality as part of the core library, it's up to you to process the ajax requests in your parent component. - - -#### Example GitHub API - -In this example, [Vue Resource](https://github.com/vuejs/vue-resource) is used to access the [GitHub API](https://developer.github.com/v3/). - -
diff --git a/docs/gitbook/Ajax/AjaxExample.md b/docs/gitbook/Ajax/AjaxExample.md deleted file mode 100644 index 27ceaab..0000000 --- a/docs/gitbook/Ajax/AjaxExample.md +++ /dev/null @@ -1,28 +0,0 @@ -```html - - -``` -```js -data() { - return { - options: null - } -}, -methods: { - getOptions(search, loading) { - loading(true) - this.$http.get('https://api.github.com/search/repositories', { - q: search - }).then(resp => { - this.options = resp.data.items - loading(false) - }) - } -} -``` diff --git a/docs/gitbook/Ajax/AjaxProps.md b/docs/gitbook/Ajax/AjaxProps.md index 7e1aa61..e69de29 100644 --- a/docs/gitbook/Ajax/AjaxProps.md +++ b/docs/gitbook/Ajax/AjaxProps.md @@ -1,24 +0,0 @@ -```js -/** -* Accept a callback function that will be run -* when the search text changes. The callback -* will be invoked with these parameters: - -* @param {search} String Current search text -* @param {loading} Function(bool) Toggle loading class -*/ -onSearch: { - type: Function, - default: false -}, - -/** -* Milliseconds to wait before invoking this.onSearch(). -* Used to prevent sending an AJAX request until input -* has completed. -*/ -debounce: { - type: Number, - default: 0 -} -``` diff --git a/docs/gitbook/Api/Props.md b/docs/gitbook/Api/Props.md index 0c5ca26..740d04d 100644 --- a/docs/gitbook/Api/Props.md +++ b/docs/gitbook/Api/Props.md @@ -1,6 +1,290 @@ -{% - includeCsv - src="./props.csv", - linkSrc="false", - useHeader="true" - %}{% endincludeCsv %} \ No newline at end of file +## Select + +```js +/** + * Contains the currently selected value. Very similar to a + * `value` attribute on an . You can listen for changes + * using 'change' event using v-on + * @type {Object||String||null} + */ +value: { + default: null +}, + +/** + * An array of strings or objects to be used as dropdown choices. + * If you are using an array of objects, vue-select will look for + * a `label` key (ex. [{label: 'This is Foo', value: 'foo'}]). A + * custom label key can be set with the `label` prop. + * @type {Array} + */ +options: { + type: Array, + default() { + return [] + }, +}, + +/** + * Disable the entire component. + * @type {Boolean} + */ +disabled: { + type: Boolean, + default: false +}, + +/** + * Sets the max-height property on the dropdown list. + * @deprecated + * @type {String} + */ +maxHeight: { + type: String, + default: '400px' +}, + +/** + * Enable/disable filtering the options. + * @type {Boolean} + */ +searchable: { + type: Boolean, + default: true +}, + +/** + * Equivalent to the `multiple` attribute on a ``. + * @type {String} + */ +placeholder: { + type: String, + default: '' +}, + +/** + * Sets a Vue transition property on the `.dropdown-menu`. vue-select + * does not include CSS for transitions, you'll need to add them yourself. + * @type {String} + */ +transition: { + type: String, + default: 'fade' +}, + +/** + * Enables/disables clearing the search text when an option is selected. + * @type {Boolean} + */ +clearSearchOnSelect: { + type: Boolean, + default: true +}, + +/** + * Close a dropdown when an option is chosen. Set to false to keep the dropdown + * open (useful when combined with multi-select, for example) + * @type {Boolean} + */ +closeOnSelect: { + type: Boolean, + default: true +}, + +/** + * Tells vue-select what key to use when generating option + * labels when each `option` is an object. + * @type {String} + */ +label: { + type: String, + default: 'label' +}, + +/** + * Callback to generate the label text. If {option} + * is an object, returns option[this.label] by default. + * @type {Function} + * @param {Object || String} option + * @return {String} + */ +getOptionLabel: { + type: Function, + default(option) { + if (typeof option === 'object') { + if (!option.hasOwnProperty(this.label)) { + return console.warn( + `[vue-select warn]: Label key "option.${this.label}" does not` + + ` exist in options object ${JSON.stringify(option)}.\n` + + 'http://sagalbot.github.io/vue-select/#ex-labels' + ) + } + if (this.label && option[this.label]) { + return option[this.label] + } + } + return option; + } +}, + +/** + * Callback to filter the search result the label text. + * @type {Function} + * @param {Object || String} option + * @param {String} label + * @param {String} search + * @return {Boolean} + */ +filterFunction: { + type: Function, + default(option, label, search) { + return (label || '').toLowerCase().indexOf(search.toLowerCase()) > -1 + } +}, + +/** + * An optional callback function that is called each time the selected + * value(s) change. When integrating with Vuex, use this callback to trigger + * an action, rather than using :value.sync to retreive the selected value. + * @type {Function} + * @param {Object || String} val + */ +onChange: { + type: Function, + default: function (val) { + this.$emit('input', val) + } +}, + +/** + * Enable/disable creating options from searchInput. + * @type {Boolean} + */ +taggable: { + type: Boolean, + default: false +}, + +/** + * Set the tabindex for the input field. + * @type {Number} + */ +tabindex: { + type: Number, + default: null +}, + +/** + * When true, newly created tags will be added to + * the options list. + * @type {Boolean} + */ +pushTags: { + type: Boolean, + default: false +}, + +/** + * When true, existing options will be filtered + * by the search text. Should not be used in conjunction + * with taggable. + * @type {Boolean} + */ +filterable: { + type: Boolean, + default: true +}, + +/** + * User defined function for adding Options + * @type {Function} + */ +createOption: { + type: Function, + default(newOption) { + if (typeof this.mutableOptions[0] === 'object') { + newOption = {[this.label]: newOption} + } + this.$emit('option:created', newOption) + return newOption + } +}, + +/** + * When false, updating the options will not reset the select value + * @type {Boolean} + */ +resetOnOptionsChange: { + type: Boolean, + default: false +}, + +/** + * Disable the dropdown entirely. + * @type {Boolean} + */ +noDrop: { + type: Boolean, + default: false +}, + +/** + * Sets the id of the input element. + * @type {String} + * @default {null} + */ +inputId: { + type: String +}, + +/** + * Sets RTL support. Accepts 'ltr', 'rtl', 'auto'. + * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir + * @type {String} + * @default 'auto' + */ +dir: { + type: String, + default: 'auto' +}, +``` + +## AJAX + +```js +/** + * Toggles the adding of a 'loading' class to the main + * .v-select wrapper. Useful to control UI state when + * results are being processed through AJAX. + */ +loading: { + type: Boolean, + default: false +}, + +/** + * Accept a callback function that will be + * run when the search text changes. + * + * loading() accepts a boolean value, and can + * be used to toggle a loading class from + * the onSearch callback. + * + * @param {search} String Current search text + * @param {loading} Function(bool) Toggle loading class + */ +onSearch: { + type: Function, + default: function(search, loading){} +} +``` + diff --git a/docs/gitbook/Api/props.csv b/docs/gitbook/Api/props.csv index 24acc81..b995634 100644 --- a/docs/gitbook/Api/props.csv +++ b/docs/gitbook/Api/props.csv @@ -1,25 +1,25 @@ -name,type,default -value,Object || String || null, -options,Array, -disabled,Boolean, -maxHeight,String, -searchable,Boolean, -multiple,Boolean, -placeholder,String, -transition,String, -clearSearchOnSelect,Boolean, -closeOnSelect,Boolean, -label,String, -getOptionLabel,Function, -filterFunction,Function, -filter,Function, -onChange,Function, -taggable,Boolean, -tabindex,Number, -pushTags,Boolean, -filterable,Boolean, -createOption,Function, -resetOnOptionsChange,Boolean, -noDrop,Boolean, -inputId,String, -dir,String, \ No newline at end of file +name,type +value,Object||String||null +options,Array +disabled,Boolean +maxHeight,String +searchable,Boolean +multiple,Boolean +placeholder,String +transition,String +clearSearchOnSelect,Boolean +closeOnSelect,Boolean +label,String +getOptionLabel,Function +filterFunction,Function +filter,Function +onChange,Function +taggable,Boolean +tabindex,Number +pushTags,Boolean +filterable,Boolean +createOption,Function +resetOnOptionsChange,Boolean +noDrop,Boolean +inputId,String +dir,String \ No newline at end of file diff --git a/docs/gitbook/Basics/Localization.md b/docs/gitbook/Basics/Localization.md index 3e8efce..fff6f56 100644 --- a/docs/gitbook/Basics/Localization.md +++ b/docs/gitbook/Basics/Localization.md @@ -1,6 +1,19 @@ +### RTL + +vue-select supports RTL using the standard HTML API using the `dir` attribute. + +```html + +``` + +The `dir` attribute accepts the same values as the [HTML spec](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir): `rtl`,`ltr`, and `auto`. + +### Component Text + All of the text within the component has been wrapped within [slots](https://vuejs.org/v2/guide/components.html#Content-Distribution-with-Slots) and can be replaced in your app. -#### Loading Spinner + +##### Loading Spinner ```html @@ -8,10 +21,11 @@ All of the text within the component has been wrapped within [slots](https://vue ``` -#### No Options Text +##### No Options Text ```html Sorry, no matching options. ``` +For a full list of component slots, view the [slots API docs](Api/Slots.md). -For a full list of component slots, view the [slots API docs](Api/Slots.md). \ No newline at end of file +[](codepen://sagalbot/oZmLVN?height=250) \ No newline at end of file diff --git a/docs/gitbook/Examples.md b/docs/gitbook/Examples.md index ba42bbf..c8c4ab8 100644 --- a/docs/gitbook/Examples.md +++ b/docs/gitbook/Examples.md @@ -1,19 +1,4 @@ -- [HTML5 Validation](#validation) -- [Vuex](#vuex) -- [AJAX](#ajax) -- [Dependent vSelects](#dependent) -- [Custom Component with Mixins](#customComponent) +### Codepen Collection -## HTML5 Validation {#validation} - - - -## Vuex {#vuex} - -[](codepen://sagalbot/aJQJyp?height=500) - -## AJAX {#ajax} - -## Dependent vSelects {#dependent} - -## Custom Component with Mixins {#customComponent} +I've put together a collection of examples, including all the examples +from this documentation site on [Codepen](https://codepen.io/collection/nrkgxV/#). \ No newline at end of file diff --git a/docs/gitbook/SUMMARY.md b/docs/gitbook/SUMMARY.md index d4d6bf5..5e8bcb1 100644 --- a/docs/gitbook/SUMMARY.md +++ b/docs/gitbook/SUMMARY.md @@ -12,10 +12,9 @@ - Digging Deeper - [Templating](Advanced/Templating.md) -- [Vuex](Basics.md#options) -- [AJAX](Basics.md#options) -- [Mixins](Basics.md#options) -- [Validation](Basics.md#options) +- [Vuex](Advanced/Vuex.md) +- [AJAX](Advanced/Ajax.md) +- [Validation](Advanced/Validation.md) - [Examples](Examples.md) - API