From 47fbea1290bb122d74a3bbf06d6fa72be99e686c Mon Sep 17 00:00:00 2001 From: Ivan Vilanculo Date: Thu, 3 Sep 2020 12:46:20 +0200 Subject: [PATCH] update documentation (#29) * Update Remote Source Github * add rotten tomatoes example #25 * Update github example #25 * smal improvements * Update CHANGELOG.md * document every component pops * explicity show selectize dependency * add slots docs template * update docs --- CHANGELOG.md | 1 + docs/.vuepress/components/ItemSlot.vue | 16 +++ docs/.vuepress/components/OptionSlot.vue | 17 +++ docs/.vuepress/components/RemoteGitHub.vue | 43 +++++-- .../components/RemoteRottenTomatoes.vue | 64 +++++++++ docs/.vuepress/components/Tip.vue | 13 ++ docs/.vuepress/config.js | 15 ++- docs/README.md | 7 +- docs/api/props.md | 121 ++++++++++++++++++ docs/api/slots.md | 35 +++++ docs/guide/README.md | 6 +- docs/guide/api/README.md | 3 - docs/guide/examples/README.md | 5 +- src/components/VSelectize.vue | 9 +- 14 files changed, 331 insertions(+), 24 deletions(-) create mode 100644 docs/.vuepress/components/ItemSlot.vue create mode 100644 docs/.vuepress/components/OptionSlot.vue create mode 100644 docs/.vuepress/components/RemoteRottenTomatoes.vue create mode 100644 docs/.vuepress/components/Tip.vue create mode 100644 docs/api/props.md create mode 100644 docs/api/slots.md delete mode 100644 docs/guide/api/README.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 5540de6..829daf5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - prettier ### Changed - Updated dependencies (vue-cli v4) +- Updated documentation and examples ## [0.5.0] ### Added diff --git a/docs/.vuepress/components/ItemSlot.vue b/docs/.vuepress/components/ItemSlot.vue new file mode 100644 index 0000000..3193554 --- /dev/null +++ b/docs/.vuepress/components/ItemSlot.vue @@ -0,0 +1,16 @@ + + diff --git a/docs/.vuepress/components/OptionSlot.vue b/docs/.vuepress/components/OptionSlot.vue new file mode 100644 index 0000000..33dc7bb --- /dev/null +++ b/docs/.vuepress/components/OptionSlot.vue @@ -0,0 +1,17 @@ + + diff --git a/docs/.vuepress/components/RemoteGitHub.vue b/docs/.vuepress/components/RemoteGitHub.vue index 1a29314..5770310 100644 --- a/docs/.vuepress/components/RemoteGitHub.vue +++ b/docs/.vuepress/components/RemoteGitHub.vue @@ -1,10 +1,22 @@ @@ -14,20 +26,35 @@ import debounce from 'lodash.debounce' export default { name: 'remote-git-hub', data: () => ({ - options: [], + options: [ + { + "name": "vue-selectize", + "owner": "isneezy", + "description": "Vanila Vue.js component that mimics Selectize behaviour (no need jquery dependency)", + "language": "Vue", + "watchers": 30, + "forks": 5, + "url": "https://github.com/isneezy/vue-selectize" + } + ], selected: null }), + computed: { + url() { + return this.selected ? this.selected.url : null + } + }, methods: { search: debounce (function (text, done) { if (text.length < 3) done() fetch(`https://api.github.com/legacy/repos/search/${text}`).then(response => { return response.json() }).then(data => { - this.options = data['repositories'] || [] + this.options = data.repositories || [] done() - }) - }, 300) + }).catch(done) + }, 500) }, components: {VSelectize} } - \ No newline at end of file + diff --git a/docs/.vuepress/components/RemoteRottenTomatoes.vue b/docs/.vuepress/components/RemoteRottenTomatoes.vue new file mode 100644 index 0000000..a6722a0 --- /dev/null +++ b/docs/.vuepress/components/RemoteRottenTomatoes.vue @@ -0,0 +1,64 @@ + + + + + diff --git a/docs/.vuepress/components/Tip.vue b/docs/.vuepress/components/Tip.vue new file mode 100644 index 0000000..934d9e4 --- /dev/null +++ b/docs/.vuepress/components/Tip.vue @@ -0,0 +1,13 @@ + + diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 8ad5383..9521366 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -5,7 +5,9 @@ module.exports = { // base: '/vue-selectize/', ga: 'UA-105706124-2', head: [ - ['link', { rel: 'stylesheet', type: 'text/css', href: 'https://cdn.jsdelivr.net/npm/selectize@0.12.6/dist/css/selectize.default.css' }] + ['link', { rel: 'stylesheet', type: 'text/css', href: 'https://cdn.jsdelivr.net/npm/selectize@0.12.6/dist/css/selectize.default.css' }], + ['link', { rel: 'stylesheet', type: 'text/css', href: 'https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css' }], + ['link', { rel: 'stylesheet', type: 'text/css', href: 'https://unpkg.com/tailwindcss@^1.0/dist/tailwind.min.css' }] ], themeConfig: { repo: 'isneezy/vue-selectize', @@ -23,8 +25,15 @@ module.exports = { collapsable: false, children: [ '/guide/', - '/guide/examples/', - '/guide/api/', + '/guide/examples/' + ] + }, + { + title: 'API', + collapsable: false, + children: [ + '/api/props', + '/api/slots' ] } ] diff --git a/docs/README.md b/docs/README.md index 26ce36e..14d790d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,7 +12,8 @@ actionLink: /guide/ Installation ```bash -npm install @isneezy/vue-selectize --save -# OR +# With npm package manager +npm install selectize @isneezy/vue-selectize --save +# OR with yarn package manager yarn add selectize @isneezy/vue-selectize -``` \ No newline at end of file +``` diff --git a/docs/api/props.md b/docs/api/props.md new file mode 100644 index 0000000..54fc897 --- /dev/null +++ b/docs/api/props.md @@ -0,0 +1,121 @@ +--- +title: Props +--- + +## multiple + +Equivalent to the multiple attribute on a `` input. + +```js +placeholder: { default: '', type: String }, +``` + +## options + +An array of strings or objects to be used as dropdown choices. +If you are using an array of objects, vue-selectize will look for a `id` and `label` key +Ex. `[{id: 'MZ', label: 'Mozambique'}]` +A custom label key can be set with the [label](#label) prop. + +```js +options: { default: () => [], type: Array }, +``` + +## keyBy + +Selectable option unique identifier key, each option must have a unique identifier. +Use this prop to change the default behavior + +```js +keyBy: { default: 'id', type: String }, +``` + +## label + +Tells vue-selectize what key to use when generating option labels when each option +is an object. + +```js +label: { default: 'label', type: String }, +``` + +## keys + +vue-selectize internaly uses fuse.js to perform its search capabilities, this props tells +witch keys to use for searching. + +```js +keys: { default: () => ['label'] }, +``` + +## value + +Contains the currently selected value. Very similar to a value attribute on an ``. You can listen for changes +using `input` event using v-on + +```js +value: { default: null, type: [Array, Object, String, Number] }, +``` + +## limit + +The limits the number of options that are visible in the dropdown + +```js +limit: { default: 0, type: [Number] }, +``` + +## disabled + +Disable the entire component. + +```js +disabled: { default: false, type: Boolean }, +``` + +## disableSearch + +Disable the built in search engine + +```js +disableSearch: { default: false, type: Boolean }, +``` + +## createItem + +User defined function for adding Options. Set to false to disable adding option + +```js +createItem: { + default: function(text) { + return Promise.resolve(text) + }, + type: [Function, Boolean] +}, +``` + +## searchFn + +User defined function for searching + +```js +searchFn: { default: false, type: [Boolean, Function] }, +``` + +## theme + +Selectize.js theme + +```js +theme: { default: '', type: String } +``` + + diff --git a/docs/api/slots.md b/docs/api/slots.md new file mode 100644 index 0000000..b235b55 --- /dev/null +++ b/docs/api/slots.md @@ -0,0 +1,35 @@ +--- +title: Slots +--- + + +WARN +This content is under revision and it is incomplete. + + + +VueSelectize leverages scoped slots to allow for total customization of the presentation layer. +Slots can be used to change the look and feel of the UI, or to simply swap out text. + + +## item + +The text displayed to represent each selected item. +- `item {Object|String}` - A selected option + + + +<<< @/docs/.vuepress/components/ItemSlot.vue + +## option + +The option within the dropdown. +- `option {Object}` - The currently isolated option from `filteredOptions` + + + +<<< @/docs/.vuepress/components/OptionSlot.vue + + +## create-item +## spinner diff --git a/docs/guide/README.md b/docs/guide/README.md index 4f9f9f9..2e09eb7 100644 --- a/docs/guide/README.md +++ b/docs/guide/README.md @@ -9,7 +9,7 @@ Package installation ```bash # With npm package manager -npm install @isneezy/vue-selectize --save +npm install selectize @isneezy/vue-selectize --save # OR with yarn package manager yarn add selectize @isneezy/vue-selectize ``` @@ -21,6 +21,7 @@ component globally available ```js import Vue from 'vue' +import 'selectize/dist/css/selectize.default.css' // This is required, we use the same css as selectize.js import VSelectize from '@isneezy/vue-selectize' Vue.component('v-selectize', VSelectize) ``` @@ -31,6 +32,7 @@ in which it will be used ```js // Vue SFC Example // MyComponent.vue +import 'selectize/dist/css/selectize.default.css' // This is required, we use the same css as selectize.js import VSelectize from '@isneezy/vue-selectize' export default { data: () => ({ @@ -47,4 +49,4 @@ And finally at your component markup -``` \ No newline at end of file +``` diff --git a/docs/guide/api/README.md b/docs/guide/api/README.md deleted file mode 100644 index 3845448..0000000 --- a/docs/guide/api/README.md +++ /dev/null @@ -1,3 +0,0 @@ ---- -title: API ---- \ No newline at end of file diff --git a/docs/guide/examples/README.md b/docs/guide/examples/README.md index 22adec7..a73afb9 100644 --- a/docs/guide/examples/README.md +++ b/docs/guide/examples/README.md @@ -46,11 +46,14 @@ This example shows how to integrate third-party data from the GitHub API. <<< @/docs/.vuepress/components/RemoteGitHub.vue ## Remote Source — Rotten Tomatoes + This demo shows how to integrate third-party data from the Rotten Tomatoes API. Try searching for "Iron Man". Note: if this doesn't work, it's because the API limit has been reached... try again later :smile: +<<< @/docs/.vuepress/components/RemoteRottenTomatoes.vue +