Support for custom option templates using partials

Damian Dulisz · Damian Dulisz · commit 3e631fdf9637 · 2016-08-08T23:27:49.000+02:00
diff --git a/README.md b/README.md
@@ -1,11 +1,14 @@
 # vue-multiselect ![Build Status](https://circleci.com/gh/monterail/vue-multiselect/tree/master.svg?style=shield&circle-token=5c931ff28fd12587610f835472becdd514d09cef)
 Probably the most complete *selecting* solution for Vue.js, without jQuery.
 
+#### Current version: v1.1.0
+
 ### Features & characteristics:
 * NO dependencies
 * Single select
 * Multiple select
 * Tagging
+* Custom option templates (1.1.0+)
 * Dropdowns
 * Filtering
 * Search with suggestions
@@ -74,7 +77,6 @@ export default {
 ## Roadmap:
 
 * Grouping
-* Support for partials
 * Examples of custom components / templates ready to use in project
 
 ## Examples
@@ -110,7 +112,7 @@ multiselect(
 ```
 
 ### Multiple select with search
-``` jade
+```jade
 multiselect(
   :options="source",
   :selected="multiValue",
@@ -125,7 +127,7 @@ multiselect(
 
 ### Tagging
 with `@tag` event
-``` jade
+```jade
 multiselect(
   :options="taggingOptions",
   :selected="taggingSelected",
@@ -140,8 +142,7 @@ multiselect(
 )
 ```
 
-``` javascript
-
+```javascript
 addTag (newTag) {
   const tag = {
     name: newTag,
@@ -152,6 +153,50 @@ addTag (newTag) {
 },
 ```
 
+### Custom option template
+Using partial API
+```jade
+multiselect(
+  :options="styleList",
+  :selected="selectedStyle",
+  :option-height="130",
+  :custom-label="styleLabel",
+  @update="updateSelectedStyle",
+  option-partial="customOptionPartial"
+  placeholder="Fav No Man’s Sky path"
+  label="title"
+  key="title"
+)
+```
+
+``` javascript
+import customOptionPartial from './partials/customOptionPartial.html'
+Vue.partial('customOptionPartial', customOptionPartial)
+
+// ...Inside Vue component
+methods: {
+  styleLabel ({ title, desc }) {
+    return `${title} – ${desc}`
+  },
+  updateSelectedStyle (style) {
+    this.selectedStyle = style
+  }
+}
+```
+
+``` html
+<div>
+  <img class="option__image" :src="option.img" alt="No Man’s Sky" />
+  <div class="option__desc">
+    <span class="option__title">{{ option.title }}</span>
+    <span class="option__small">
+      {{ option.desc }}
+    </span>
+  </div>
+</div>
+
+```
+
 ### Asynchronous dropdown
 ``` jade
 multiselect(
@@ -168,7 +213,7 @@ multiselect(
     Oops! No elements found. Consider changing the search query.
 ```
 
-``` javascript
+```javascript
 methods: {
   asyncFind (query) {
     this.countries = findService(query)
diff --git a/docs/assets/base/_typo.sass b/docs/assets/base/_typo.sass
@@ -191,3 +191,5 @@ kbd
   padding: 3px 5px
   border-radius: 4px
   background: $tertiary-color
+  font-weight: 300
+  font-size: rem(16px)
diff --git a/docs/docs.scss b/docs/docs.scss
@@ -107,3 +107,30 @@ body {
   color: $secondary-color;
   transform: translateX(-100%);
 }
+
+.option__image {
+  max-height: 100px;
+  display: inline-block;
+  vertical-align: middle;
+}
+
+.option__desc {
+  display: inline-block;
+  vertical-align: middle;
+  padding: rem(10px);
+}
+
+.option__title {
+  font-size: rem(24px);
+}
+
+.option__small {
+  margin-top: rem(10px);
+  display: block;
+}
+
+.version--changed {
+  margin-right: rem(10px);
+  font-size: rem(20px);
+  color: $primary-color;
+}
diff --git a/docs/index.jade b/docs/index.jade
@@ -44,6 +44,9 @@ html(lang="en")
         hr.typo__hr
         include ./partials/examples/_tagging
 
+        hr.typo__hr
+        include ./partials/examples/_partials
+
         hr.typo__hr
         include ./partials/examples/_action
 
diff --git a/docs/main.js b/docs/main.js
@@ -2,6 +2,9 @@ import Vue from 'vue'
 
 import Multiselect from '../src/Multiselect'
 import countries from './data/countries.json'
+import customOptionPartial from './partials/customOptionPartial.html'
+
+Vue.partial('customOptionPartial', customOptionPartial)
 
 function throttle (callback, limit) {
   var wait = false
@@ -54,7 +57,14 @@ new Vue({
       isLoading: false,
       isNavSticky: false,
       firstColor: Math.floor(Math.random() * 255),
-      secondColor: Math.floor(Math.random() * 255)
+      secondColor: Math.floor(Math.random() * 255),
+      styleList: [
+        { title: 'Space Pirate', desc: 'More space battles!', img: '/static/posters/fleet.png' },
+        { title: 'Merchant', desc: 'PROFIT!', img: '/static/posters/trading_post.png' },
+        { title: 'Explorer', desc: 'Discovering new species!', img: '/static/posters/creatures.png' },
+        { title: 'Miner', desc: 'We need to go deeper!', img: '/static/posters/resource_lab.png' }
+      ],
+      selectedStyle: { title: 'Explorer', desc: 'Discovering new species!', img: '/static/posters/creatures.png' }
     }
   },
   computed: {
@@ -138,9 +148,15 @@ new Vue({
       console.log('@update: ', value)
       this.valuePrimitive = value
     },
+    updateSelectedStyle (style) {
+      this.selectedStyle = style
+    },
     nameWithLang ({ name, language }) {
       return `${name} — [${language}]`
     },
+    styleLabel ({ title, desc }) {
+      return `${title} – ${desc}`
+    },
     onSelect (option) {
       console.log('@select: ', option)
     },
diff --git a/docs/partials/_nav.jade b/docs/partials/_nav.jade
@@ -15,6 +15,7 @@ ul.list(
   +nav-element('Multiselect with search', 'multiselect-search')
   +nav-element('Asynchronous select', 'ajax')
   +nav-element('Tagging', 'tagging')
+  +nav-element('Custom option templates', 'partials')
   +nav-element('Action select', 'action')
   +nav-element('Custom configuration', 'custom')
 
diff --git a/docs/partials/_start.jade b/docs/partials/_start.jade
@@ -5,7 +5,7 @@ section.start(
     h1.typo__h1
       img.logo(src="./static/vue-logo.png")
       | Vue-multiselect
-      small.version (v1.0.1)
+      small.version (v1.1.0)
     h3.typo__h3 The most complete selecting solution for
       = ' '
       a.typo__link(href="http://vuejs.org" target="_BLANK") Vue.js
@@ -32,9 +32,9 @@ section.start(
             .grid__column.grid__unit--md-6.list
               ul.list__ul
                 li.typo__li Single / multi select
-                li.typo__li Dropdowns
                 li.typo__li: a.typo__link(href="#search") Searchable
                 li.typo__li: a.typo__link(href="#tagging") Tagging
+                li.typo__li: a.typo__link(href="#partials") Custom option templates (1.1.0+)
                 li.typo__li: a.typo__link(href="#action") Action dispatcher
             .grid__column.grid__unit--md-6.list
               ul.list__ul
diff --git a/docs/partials/api/_props.jade b/docs/partials/api/_props.jade
@@ -183,6 +183,12 @@ h2.typo__h2#props Props
           td.table__td: kbd false
           td.table__td
             | Enable/disable the multiselect.
+        tr.table__tr
+          td.table__td: strong OptionPartial
+          td.table__td String
+          td.table__td: kbd multiselectBasicOptionPartial
+          td.table__td
+            | Name of the registered custom option partial.
 
         tr.table__tr
           td.table__td.utils--center(colspan="4"): strong pointerMixin.js
@@ -193,3 +199,9 @@ h2.typo__h2#props Props
           td.table__td: kbd true
           td.table__td
             | Enable/disable highlighting of the pointed value.
+        tr.table__tr
+          td.table__td: strong OptionHeight
+          td.table__td Number
+          td.table__td: kbd 40
+          td.table__td
+            | Set the height of the option. Used for scroll calculations.
diff --git a/docs/partials/customOptionPartial.html b/docs/partials/customOptionPartial.html
@@ -0,0 +1,9 @@
+<div>
+  <img class="option__image" :src="option.img" alt="No Man’s Sky" />
+  <div class="option__desc">
+    <span class="option__title">{{ option.title }}</span>
+    <span class="option__small">
+      {{ option.desc }}
+    </span>
+  </div>
+</div>
diff --git a/docs/partials/examples/_partials.jade b/docs/partials/examples/_partials.jade
@@ -0,0 +1,70 @@
+h2.typo__h2#partials
+  small.version--changed v1.1.0+
+  | Custom option templates
+p.typo__p
+  | You can provide the name of a registered custom partial to use as a template for elements in the option list.
+p.typo__p
+  | If no partial is provided it will use the default one: <kbd>&lt;span v-text="getOptionLabel(option)"&gt;&lt;/span&gt;</kbd>
+p.typo__p
+  | To ensure the keyboard navigation works properly, remember to set the <kbd>:option-height</kbd> to equal the height of the option template. By default, the component assumes an option height of 40px.
+.grid__row
+  .grid__column.grid__unit--md-5
+    label.typo__label Fav No Man’s Sky path
+    multiselect(
+      :options="styleList",
+      :selected="selectedStyle",
+      :option-height="130",
+      :custom-label="styleLabel",
+      @update="updateSelectedStyle",
+      option-partial="customOptionPartial"
+      placeholder="Fav No Man’s Sky path"
+      label="title"
+      key="title"
+    )
+    pre.language-json
+      code.
+        {{ selectedStyle | json }}
+
+  .grid__column.grid__unit--md-7
+    label.typo__label Code sample
+    pre.language-jade
+      code.
+        multiselect(
+          :options="styleList",
+          :selected="selectedStyle",
+          :option-height="130",
+          :custom-label="styleLabel",
+          @update="updateSelectedStyle",
+          option-partial="customOptionPartial"
+          placeholder="Fav No Man’s Sky path"
+          label="title"
+          key="title"
+        )
+
+    pre.language-javascript
+      code.
+        import customOptionPartial from './partials/customOptionPartial.html'
+        Vue.partial('customOptionPartial', customOptionPartial)
+
+        // ...Inside Vue component
+        methods: {
+          styleLabel ({ title, desc }) {
+            return `${title} – ${desc}`
+          },
+          updateSelectedStyle (style) {
+            this.selectedStyle = style
+          }
+        }
+
+    pre.language-html
+      code.
+        &lt;!-- customOptionPartial.html --&gt;
+        &lt;div&gt;
+          &lt;img class="option__image" :src="option.img" alt="Poster" /&gt;
+          &lt;div class="option__desc"&gt;
+            &lt;span class="option__title"&gt;{&zwnj;{ option.title }}&lt;/span&gt;
+            &lt;span class="option__small"&gt;
+              {&zwnj;{ option.desc }}
+            &lt;/span&gt;
+          &lt;/div&gt;
+        &lt;/div&gt;
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "vue-multiselect",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Multiselect component for vue.js",
   "author": "Damian Dulisz <damian.dulisz@monterail.com>",
   "private": false,
diff --git a/src/Multiselect.vue b/src/Multiselect.vue
@@ -66,18 +66,15 @@
           </span>
         </li>
         <template v-if="!max || value.length < max">
-          <li v-for="option in filteredOptions" track-by="$index">
-            <span
-              tabindex="0"
-              :class="{ 'multiselect__option--highlight': $index === pointer && this.showPointer, 'multiselect__option--selected': !isNotSelected(option) }"
-              @mousedown.prevent="select(option)"
-              @mouseenter="pointerSet($index)"
-              :data-select="option.isTag ? tagPlaceholder : selectLabel"
-              :data-selected="selectedLabel"
-              :data-deselect="deselectLabel"
-              class="multiselect__option"
-              v-text="getOptionLabel(option)">
-            </span>
+          <li
+            v-for="option in filteredOptions"
+            track-by="$index"
+            tabindex="0"
+            :class="{ 'multiselect__option--highlight': $index === pointer && this.showPointer, 'multiselect__option--selected': !isNotSelected(option) }"
+            @mousedown.prevent="select(option)"
+            @mouseenter="pointerSet($index)"
+            class="multiselect__option">
+            <partial :name="optionPartial"></partial>
           </li>
         </template>
         <li v-show="filteredOptions.length === 0 && search">
@@ -93,10 +90,23 @@
 <script>
   import multiselectMixin from './multiselectMixin'
   import pointerMixin from './pointerMixin'
+  import optionPartial from './optionPartial.html'
+  import Vue from 'vue'
+
+  Vue.partial('multiselectBasicOptionPartial', optionPartial)
 
   export default {
     mixins: [multiselectMixin, pointerMixin],
     props: {
+      /**
+       * Name of the registered custom option partial
+       * @default 'multiselectBasicOptionPartial'
+       * @type {String}
+       */
+      optionPartial: {
+        type: String,
+        default: 'multiselectBasicOptionPartial'
+      },
       /**
        * String to show when pointing to an option
        * @default 'Press enter to select'
diff --git a/src/optionPartial.html b/src/optionPartial.html
@@ -0,0 +1 @@
+<span v-text="getOptionLabel(option)"></span>
diff --git a/src/pointerMixin.js b/src/pointerMixin.js
diff --git a/static/posters/creatures.png b/static/posters/creatures.png
diff --git a/static/posters/fleet.png b/static/posters/fleet.png
diff --git a/static/posters/resource_lab.png b/static/posters/resource_lab.png
diff --git a/static/posters/trading_post.png b/static/posters/trading_post.png
diff --git a/test/unit/specs/Multiselect.spec.js b/test/unit/specs/Multiselect.spec.js
