ENH: dropdown supports data objects. Fixes #103 @pragnya.reddy

docs/dropdown.md

@@ -26,16 +26,55 @@ This renders a dropdown with 3 options -- Red, Green, Blue.
 
 `key` enables urlfilter for dropdown. If Red option is selected from dropdown, URL is appended with `?colors=Red`
 
+If the labels are different from the values, you can use a list of
+`{value: ..., label: ...}` objects.
+
+```html
+<div class="dropdown-object"></div>
+<script>
+  $('.dropdown-object').dropdown({
+    data: [{ label: 'Red', value: 1 }, { label: 'Green', value: 2 }]
+  ])
+</script>
+```
+
+The data objects need not use `label:` and `value:` as keys. You can pick any
+other key using the `label:` and `value:` options.
+
+```html
+<div class="dropdown-object"></div>
+<script>
+  $('.dropdown-object').dropdown({
+    data: [{ x: 'Red', y: 1 }, { x: 'Green', y: 2 }],
+    label_key: 'x',   // use data[*].x as the label, instead of data[*].label
+    value_key: 'y'    // use data[*].y as the value, instead of data[*].value
+  ])
+</script>
+```
+
+You can set the default value of the dropdown using the `value:` key.
+
+```html
+<div class="dropdown-default"></div>
+<script>
+$('.dropdown-default').dropdown({
+  key: 'colors',
+  data: ['Red', 'Green', 'Blue'],
+  value: $('#color').val(url.searchKey.city)    // Must match data string or .value
+})
+</script>
+```
+
 By default, the selected dropdown values are appended to URL query string. To append to the hash instead, use `target: '#'`.
 
 ```html
 <div class="container3"></div>
 <script>
-  $('.container3').dropdown(
-    { key: 'colors',
-      data: ['Red', 'Green', 'Blue'],
-      target: '#'
-    })
+  $('.container3').dropdown({
+    key: 'colors',
+    data: ['Red', 'Green', 'Blue'],
+    target: '#'
+  })
 </script>
 ```
 
@@ -70,10 +109,15 @@ To use bootstrap-select options, use `options:`
 
 ## $.dropdown options
 
-- `data`: Array of values.
+- `data`: Array of values. Values may be strings, or objects. Objects have keys:
+  - `label`: text to display in the dropdown
+  - `value`: value to submit when item is selected
+- `value`: default selected value. This must match the `value` key in the `data` object
 - `url`: End point that returns the `data`. If `data:` is also given, `data` takes priority.
 - `target`: defines how URL is updated. Can be `''` (Default), `#` or `pushState`
 - `key`: key with which URL is updated.
+- `value_key`: name of the key that defines the value in `data:` objects. Default: `"value"`
+- `label_key`: name of the key that defines the label in `data:` objects. Default: `"label"`
 - `multiple`: To render a dropdown that supports multi-select. Can be `true` or `false` (Default).
 - `options`: Supports same options as [bootstrap-select options](https://developer.snapappointments.com/bootstrap-select/options/)
 
@@ -84,9 +128,9 @@ To use bootstrap-select options, use `options:`
 - `change` is triggered whenever dropdown value is changed
 
 ```html
-<div class="container5"></div>
+<div class="container6"></div>
 <script>
-  $('.container5')
+  $('.container6')
   .on('load', function() {
     // Your code here
   })
@@ -98,5 +142,4 @@ To use bootstrap-select options, use `options:`
     data: ['Red', 'Green', 'Blue']
   })
 </script>
-
 ```

src/dropdown.js

@@ -3,7 +3,9 @@ import deepmerge from 'deepmerge'
 
 var default_options = {
   target: '',
-  multiple: false
+  multiple: false,
+  value_key: 'value',
+  label_key: 'label'
 }
 
 export function dropdown(js_options) {
@@ -14,6 +16,9 @@ export function dropdown(js_options) {
 
   if (options.data) {
     render(options.data)
+    // Set the default
+    if (options.value)
+      self.find('.selectpicker').val(options.value).selectpicker('refresh')
     // trigger 'load' event
     self.trigger({type: 'load'})
   }
@@ -42,9 +47,11 @@ export function dropdown(js_options) {
         remove: true
       })
     }
-    //re-render dropdown template options with fetched data
-    self.find('.selectpicker').html(_.template(default_templates['template_dropdown_options'])(options))
-    self.find('.selectpicker').selectpicker(options.options)
+    // re-render dropdown template options with fetched data
+    var template = typeof data[0] == 'object' ? 'template_dropdown_object' : 'template_dropdown_options'
+    self.find('.selectpicker')
+      .html(_.template(default_templates[template])(options))
+      .selectpicker(options.options)
   }
 
   return this

src/dropdown.template.html

@@ -12,6 +12,12 @@ key = key ? key : '' %>
   <% }) %>
 <!-- end -->
 
+<!-- var template_dropdown_object -->
+  <% _.each(data, function(item) { %>
+    <option value="<%- item[value_key] %>" label="<%- item[label_key] %>"><%- item[label_key] %></option>
+  <% }) %>
+<!-- end -->
+
 <!-- var template_error -->
 <div class="alert alert-warning" role="alert">
   <p class="text-center">

test/test-dropdown.html

@@ -24,6 +24,9 @@
     <div class="multiselect w-25 m-3"></div>
     <div class="container6 w-25 m-3"></div>
     <div class="container7 w-25 m-3"></div>
+    <div class="container8 w-25 m-3"></div>
+    <div class="container9 w-25 m-3"></div>
+    <div class="container10 w-25 m-3"></div>
   </div>
 
   <script>
@@ -136,6 +139,66 @@
       t.end()
     })
 
+    tape('$().dropdown() supports objects in data', function (t) {
+      var data_obj = [
+        { value: 0, label: 'Hyderabad' },
+        { value: 1, label: 'Delhi' },
+        { value: 2, label: 'Mumbai' },
+        { value: 3, label: 'Chennai' }
+      ]
+      $('.container8')
+        .on('load', function () {
+          t.deepEquals($('.container8 option').get()
+            .map(function (item) { return item.text }), data_obj.map(function (row) { return row.label }))
+          t.end()
+        })
+        .dropdown({
+          key: 'city',
+          data: data_obj,
+          target: '#'
+        })
+    })
+
+    tape('$().dropdown() objects key-value names can be customized', function (t) {
+      var data_obj = [
+        { x: 0, y: 'Hyderabad' },
+        { x: 1, y: 'Delhi' },
+        { x: 2, y: 'Mumbai' },
+        { x: 3, y: 'Chennai' }
+      ]
+      $('.container9')
+        .on('load', function () {
+          t.deepEquals($('.container9 option').get()
+            .map(function (item) { return item.text }), data_obj.map(function (row) { return row.y }))
+          t.end()
+        })
+        .dropdown({
+          key: 'city',
+          data: data_obj,
+          target: '#',
+          value_key: 'x',
+          label_key: 'y'
+        })
+    })
+
+    tape('$().dropdown() set value from url', function (t) {
+      $('.container10')
+        .on('load', function () {
+          t.equals($('.container10 select').val(), 'MUM')
+          t.end()
+        })
+        .dropdown({
+          data: [
+            { value: 'HYD', label: 'Hyderabad' },
+            { value: 'DEL', label: 'Delhi' },
+            { value: 'MUM', label: 'Mumbai' },
+            { value: 'CHE', label: 'Chennai' }
+          ],
+          key: 'flag',
+          target: '#',
+          value: 'MUM'
+        })
+    })
   </script>
 
 </body>