uber_select_rails 0.1.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 877c716db7b58ef210bf6c74e61a3eb3bbeb487c
-  data.tar.gz: 723d3273bedb197b867abcddefa2965468dd030a
+SHA256:
+  metadata.gz: 4c4e02c23ba5d8d6ba50707be770694a60f4abc20cbff88c2fbe9baa7ed63619
+  data.tar.gz: fbcbd8c7ab7ff3910e2161fd980e78eb215bda8942f71d64c2332d874817a622
 SHA512:
-  metadata.gz: 4e64e8e34bee05dd83f5c0334078e7930757d1c31f00ca4321f88740ebefcb246e9e84c55eb6b95d9b4d9df6534b2322c2ac9067fda376ccc0b711dd4cc25642
-  data.tar.gz: f2c06a3bddb62d8fe4f98c0ca43f8422c79b88db92c7a9b9fff54d77e2bcea35b04cb5cfd16d074872cbe32a4aac629352569edbf7b1f6c1805be09d4aae6d9c
+  metadata.gz: 5d8afa5bdfdb0b4a50df1dc5fc9154d32f7d2b9823fb63075ce6f9cd26edf11bc274ac73a2f91a75fac64c58dc023dc3ab8c54aa80a38385493ff411d9a0d648
+  data.tar.gz: b8d8f1986c48ee1b2c502a16932fcc0809a10abaa8a4bc577423d1931361d55a79e3e1b4484c9a145761fa6aba9accb9a286a86c51c69c6f91d87cfcec09b179

data/lib/uber_select_rails/version.rb

@@ -1,3 +1,3 @@
 module UberSelectRails
-  VERSION = "0.1.2"
+  VERSION = "0.4.0"
 end

data/uber_select.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   spec.summary       = %q{A Rails gem containing a javascript plugin that adds a layer of UI goodness overtop of basic HTML select elements}
   spec.homepage      = "https://github.com/culturecode/uber_select_rails"
 
-  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.files         = `git ls-files -z --recurse-submodules`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]

data/vendor/assets/javascript/uber_select/.gitignore

@@ -0,0 +1,18 @@
+# See https://help.github.com/articles/ignoring-files for more about ignoring files.
+#
+# If you find yourself ignoring temporary files generated by your text editor
+# or operating system, you probably want to add a global ignore instead:
+#   git config --global core.excludesfile '~/.gitignore_global'
+
+# Ignore bundler config.
+/.bundle
+
+# Ignore the default SQLite database.
+/db/*.sqlite3
+/db/*.sqlite3-journal
+
+# Ignore all logfiles and tempfiles.
+/log/*
+!/log/.keep
+/tmp
+.DS_Store

data/vendor/assets/javascript/uber_select/README.md

@@ -0,0 +1,264 @@
+# UberSelect
+
+UberSelect is a fancy UI on top of a regular `<select>` element.
+
+## Requirements
+Tested on jQuery 1.11.x to 3.3.x
+
+## Parts
+UberSelect is composed of two main parts, an UberSearch that does all the of searching and UI, and an UberSelect which
+is used to connect an UberSearch to a `<select>` element.
+
+### UberSelect
+This is the object that allows an UberSearch and a `<select>` element to work together. The select element can be used
+to control the state of the UberSearch, and vice-versa. This means you can programmatically change the state of the
+select, and UberSearch will update. Users can interact with the UberSearch, and the select will update. This also means
+you can use UberSelect to gussy up forms, without changing any of the underlying inputs.
+
+#### Usage
+
+```JS
+$('.my_selects').uberSelect(options);
+```
+
+#### Options
+Options can be specified by setting the `data-uber-options` attribute on the `<select>` element. Values should be passed
+as a JSON string. All options on the are passed to the underlying UberSearch, see [UberSearch options](#UberSearchOptions).
+
+- ##### prepopulateSearchOnOpen
+  Determines whether the search input starts with the selected value in it when the pane is opened.
+
+  Default: `false`
+
+- ##### clearSearchClearsSelect
+  Determines whether the select value should be cleared when the search is cleared.
+
+  Default: `false`
+
+- ##### placeholder
+  Placeholder to show in the selected text area.
+
+  Default: `<select>` element attributes `<select placeholder="my placeholder" data-placeholder="my placeholder">`
+
+- ##### dataUrl
+  A url to pre-fetch select options from. JSON response should be of the form
+  `[{text:'option with explicit value', value: 'some value'}, {text:'option with implicit value'}]`. For a custom JSON response, use in conjunction with optionFromDatum.
+
+  Default: `null`
+
+- ##### optionFromDatum
+  A function that is used to customize the options value and text built from a JSON response. `datum` is a single result returned from the JSON response.
+
+  The function signature is as follows:
+  ```js
+    function(datum) {
+      return // a <option> element to represent the select
+    }
+  ```
+
+   Default: `datum.value` populates the `<option>` value, `datum.text` populates the `<option>` text.
+
+- ##### value
+  Initialize the UberSearch with this selected value
+
+  Default: `<select>` element `value` property
+
+#### Events Triggered
+- ##### uber-select:ready
+  This fires when the UberSelect has initialized and is ready for user interaction
+
+#### Events Observed
+The `<select>` element observes the following events:
+
+- ##### uber-select:refreshOptions
+  The UberSearch options list will be updated to match the `<select>` element's `<option>` list.
+
+- ##### uber-select:refresh
+  The UberSearch will update its selected value to match the `<select>` element's. This handler also runs when the
+  `<select>` element triggers a `change` event.
+
+### UberSearch
+The UberSearch performs all of the heavy lifting. It creates the UI views, maintains state, and performs the searching.
+It can be instantiated without the use of an UberSelect, which can be useful for situations where the selected value is
+being used in purely in JS, and not being linked to a `<select>` element in a form.
+
+#### Usage
+
+```JS
+new UberSearch(data, options);
+```
+
+#### Data
+Data is an array of objects. Each object may have the following properties:
+
+- ##### text
+  String shown to the user in the list of results. This value is required if *value* is not provided.
+
+- ##### selectedText
+  String shown to the user in the output container when this option is selected. *optional*
+
+- ##### title
+  Title text shown to the user when hovering over the result. *optional*
+
+- ##### value
+  This is matched against the *value* option passed UberSearch and will appear selected if it matches. It is also used to match against search input text when the user searches. This value is required if *text* is not provided.
+
+- ##### matchValue
+  This overrides the value used to match against search input text when the user searches. *optional*
+
+- ##### visibility
+  This is used to determine whether the option appears only when searching or only when not searching. Values accepted: `query`, `no-query`. *optional*
+
+- ##### disabled
+  This is used to determine whether the option appears disabled. *optional*
+
+- ##### group
+  This is used to visually group options. All options with the same group will appear together. *optional*
+
+#### Methods
+
+- ##### setData(data)
+  Sets the data. `data` should be an Array conforming to the specifications described in <a href="#data">Data</a>
+
+
+#### Options <a name="UberSearch options"></a>
+Options can be specified by setting the `data-uber-options` attribute on the `<select>` element. Values should be passed
+as a JSON string.
+
+- ##### value
+  Sets the initially selected value of the UberSearch. This value should match the `value` property of the desired
+  option data.
+
+  Default: `null`
+
+- ##### search
+  Determines whether the search input be shown.
+
+  Default: `true`
+
+- ##### clearSearchButton
+  Sets the text content of clear search button.
+
+  Default: `✕`
+
+- ##### selectCaret
+  Sets the text content of clear select caret.
+
+  Default: `⌄`
+
+- ##### hideBlankOption
+  Sets whether blank options should be hidden automatically.
+
+  Default: `false`
+
+- ##### treatBlankOptionAsPlaceholder
+  Determines whether the `text` property of an option with a blank `value` property should be used as the placeholder
+  text if no placeholder is specified.
+
+  Default: `false`
+
+- ##### highlightByDefault
+  Determines whether the first search result be auto-highlighted.
+
+  Default: `true`
+
+- ##### minQueryLength
+  Sets minimum number of characters the user must type before a search will be performed.
+
+  Default: `0`
+
+- ##### minQueryMessage
+  Sets the message shown to the user when the query doesn't exceed the minimum length. `true` for a default message,
+  `false` for none, or provide a string to set a custom message.
+
+  Default: `true`
+
+- ##### placeholder
+  Sets the placeholder shown in the selected text area.
+
+  Default: `null`
+
+- ##### searchPlaceholder
+  Sets the placeholder shown in the search input.
+
+  Default: `'Type to search'`
+
+- ##### noResultsText
+  Sets the message shown when there are no results.
+
+  Default: `'No Matches Found'`
+
+- ##### noDataText
+  Sets the text to show when the results list is empty and no search is in progress
+
+  Default: `'No options'`
+
+- ##### buildResult
+  A function that is used to build result elements.
+
+  The function signature is as follows:
+  ```js
+    function(listOptionData) {
+      return // HTML/element to insert into the the results list
+    }
+  ```
+
+- ##### resultPostprocessor
+  A function that is run after a result is built and can be used to decorate it. This can be useful when extending the
+  functionality of an existing UberSearch implementation.
+
+  The function signature is as follows:
+  ```js
+    function(resultsListElement, listOptionData) { }
+  ```
+
+  Default: No-op
+
+- ##### onRender
+  A function to run when the results container is rendered. If the result returns false, the default `select` event
+  handler is not run and the event is cancelled.
+
+  The function signature is as follows:
+  ```js
+  function(resultsContainer, searchResultsHTML) { }
+  ```
+
+- ##### onSelect
+  A function to run when a result is selected. If the result returns false, the default `select` event handler is not
+  run and the event is cancelled.
+
+  The function signature is as follows:
+  ```js
+  function(listOptionData, resultsListElement, clickEvent) { }
+  ```
+
+- ##### onNoHighlightSubmit
+  A function to run when a user presses enter without selecting a result.
+  Should be used in combination with `highlightByDefault: false`.
+
+  The function signature is as follows:
+  ```js
+  function(value) { }
+  ```
+
+- ##### outputContainer (Deprecated)
+  An object that receives the output once a result is selected. Must respond to `setValue(value)` and `view()`. This object serves to
+  attach the result list to the DOM at the desired location.
+
+#### Events Triggered
+- ##### shown
+  This fires when the UberSearch pane is opened.
+
+- ##### renderedResults
+  This fires each time the list of results is updated.
+
+- ##### clear
+  This fires when the user clicks the clear search button.
+
+- ##### select
+  This fires when the user selects a result.
+
+  The handler function signature is as follows:
+  ```js
+  function(event, [listOptionData, resultsContainer, originalEvent]) { }
+  ```

data/vendor/assets/javascript/uber_select/javascript/jquery.uber-select.js

@@ -0,0 +1,182 @@
+(function( $ ) {
+  var eventsTriggered = {
+    ready: 'uber-select:ready'
+  }
+  var eventsObserved = {
+    refreshOptions: 'uber-select:refreshOptions',
+    refresh: 'uber-select:refresh change',
+  }
+
+  $.fn.uberSelect = function(opts) {
+    this.each(function(){
+      if (this.uberSearch) { return } // Prevent multiple initializations on the same element
+      var select = this
+      var options = $.extend({
+        prepopulateSearchOnOpen: false,                                                   // Should the search input start with the selected value in it when the pane is opened?
+        clearSearchClearsSelect: false,                                                   // Should the select value be cleared When the search is cleared?
+        disabled: $(select).is(':disabled'),                                              // Whether the select is currently disabled
+        placeholder: $(select).attr('placeholder') || $(select).attr('data-placeholder'), // Placeholder to show in the selected text area
+        dataUrl: null,                                                                    // A url to pre-fetch select options from, see optionsFromData for data format
+        optionFromDatum: optionFromDatum,                                                 // A function to create select options
+        value: $(select).val()                                                            // Initialize the UberSearch with this selected value
+      }, opts, $(select).data('uber-options'))
+
+      var uberSearch = this.uberSearch = new UberSearch(dataFromSelect(select), options)
+
+
+      // BEHAVIOUR
+
+      // When the UberSearch pane is opened
+      $(uberSearch).on('shown', function(){
+        if (options.prepopulateSearchOnOpen){
+          updateSearchValueFromSelect()
+        }
+      })
+
+      // When the clear search button is clicked
+      $(uberSearch).on('clear', function(){
+        if (options.clearSearchClearsSelect){
+          clearSelect()
+        }
+      })
+
+      // When the list values change
+      $(select).on(eventsObserved.refreshOptions, refreshOptionsList)
+
+      // When the select value changes
+      $(select).on(eventsObserved.refresh, updateSelectedValue)
+
+      // When a result is selected
+      $(uberSearch).on('select', function(_, datum){
+        updateSelectValue(datum.value)
+      })
+
+      // INITIALIZATION
+
+      uberSearch.view.insertBefore(select).append(select)
+      hideSelect()
+      if (options.dataUrl) {
+        $.getJSON(options.dataUrl).done(function(data){
+          $(select).append(optionsFromData(data))
+          uberSearch.setData(dataFromSelect(select))
+          $(select).trigger(eventsTriggered.ready)
+        })
+      } else {
+        $(select).trigger(eventsTriggered.ready)
+      }
+
+
+      // HELPER FUNCTIONS
+
+      // Given a select element
+      // Returns an array of data to match against
+      function dataFromSelect(select){
+        var opts = $(select).find('option')
+        var datum;
+        var parent;
+
+        return $.map(opts, function(option){
+          // This is optimized for performance and does not use jQuery convenience methods. Seems to be about 30% faster loading during non-scientific tests.
+          datum = {
+            text: option.textContent,
+            selectedText: getAttribute(option, 'data-selected-text'),
+            value: getAttribute(option, 'value'),
+            title: getAttribute(option, 'title'),
+            disabled: getAttribute(option, 'disabled'),
+            matchValue: getAttribute(option, 'data-match-value'),
+            visibility: getAttribute(option, 'data-visibility'),
+            element: option
+          }
+
+          parent = option.parentElement
+          if (parent.nodeName == 'OPTGROUP') {
+            datum.group = getAttribute(parent, 'label')
+            datum.visibility = datum.visibility || getAttribute(parent, 'data-visibility')
+          }
+
+          return datum
+        })
+      }
+
+      // Generates select options from data
+      function optionsFromData(data){
+        var elements = []
+        var groups = {}
+         $.each(data, function(_, datum){
+          if (datum.group) {
+            groups[datum.group] || elements.push(groups[datum.group] = groupFromDatum(datum))
+            groups[datum.group].append(options.optionFromDatum(datum))
+          } else {
+            elements.push(options.optionFromDatum(datum))
+          }
+        })
+
+        return elements
+      }
+
+      function getAttribute(element, attribute) {
+        var value = element.getAttribute(attribute)
+        return value === null ? undefined : value // Allow $.extend to overwrite missing attributes by setting them to undefined
+      }
+
+      function groupFromDatum(datum){
+        return $('<optgroup>').attr('label', datum.group)
+      }
+
+      function optionFromDatum(datum){
+        return $('<option>').attr('value', datum.value || datum.text).text(datum.text || datum.value)
+      }
+
+      // Copies the value of the select into the search input
+      function updateSearchValueFromSelect(){
+        uberSearch.searchField.input.val($(select).find('option:selected').text())
+        uberSearch.searchField.refresh()
+      }
+
+      function refreshOptionsList(){
+        uberSearch.setDisabled($(select).is(':disabled'))
+        uberSearch.setData(dataFromSelect(select))
+        updateSelectedValue()
+      }
+
+      // Updates the UberSearch's selected value from the select element's value
+      function updateSelectedValue(){
+        uberSearch.setValue($(select).val())
+      }
+
+      function updateSelectValue(value){
+        $(select).val(value).trigger('change')
+      }
+
+      // Selects the option with an emptystring value, or the first option if there is no blank option
+      function clearSelect(){
+        var selectValue = $(select).val()
+
+        // If the select is already cleared, avoid firing a change event
+        if (!selectValue) { return }
+
+        // Clear the value
+        $(select).val('').trigger('change')
+
+        // If that cleared it then we're done, otherwise, select the first option
+        if ($(select).find('option:selected').length){ return }
+
+        var firstOptionValue = $(select).find('option').prop('value')
+
+        // If the first option is already set then we're done, otherwise, select the first option
+        if (firstOptionValue == selectValue) { return }
+
+        // Select the first option
+        $(select).val(firstOptionValue).trigger('change')
+      }
+
+      // Hide the select, but keep its width to allow it to set the min width of the uber select
+      // NOTE: IE doesn't like 0 height, so give it 1px height and then offset
+      function hideSelect(){
+        $(select).wrap($('<div>').css({visibility: 'hidden', height: '1px', marginTop: '-1px', pointerEvents: 'none'}).addClass('select_width_spacer'))
+      }
+    })
+
+    return this
+  }
+}( jQuery ));