Class: SearchableSelectView

SearchableSelectView()

A select interface that allows the user to search from within the options, and optionally select multiple items. Also allows the items to be grouped, and to display an icon or image for each item.

Constructor

new SearchableSelectView()

Since:
  • 2.14.0
Source:

Extends

  • Backbone.View

Members

allowAdditions :boolean

Setting to true gives users the ability to add their own options that are not listed in this.options. This can work with either single or multiple search select dropdowns
Type:
  • boolean
Source:

allowMulti :boolean

Whether to allow users to select more than one value
Type:
  • boolean
Source:

className :string

The HTML class names for this view element
Type:
  • string
Source:

clearable :boolean

Whether the dropdown value can be cleared by the user after being selected.
Type:
  • boolean
Source:
The path to the semanticUI dropdown CSS (required for this view to work)
Type:
  • string
Source:

hideEmptyCategoriesOnSearch :boolean

Set to false to always display category headers in the dropdown, even if there are no results in that category when a user is searching.
Type:
  • boolean
Source:

imageHeight :number

The maximum height of images used for each option, in pixels
Type:
  • number
Source:

imageWidth :number

The maximum width of images used for each option, in pixels
Type:
  • number
Source:

inputLabel :string

Label for the input element
Type:
  • string
Source:

options :Array.<Object>|Object

The list of options that a user can select from in the dropdown menu. For uncategorized options, provide an array of objects, where each object is a single option. To create category headings, provide an object containing named objects, where the key for each object is the category title to display, and the value of each object comprises the option properties.
Type:
  • Array.<Object> | Object
Properties:
Name Type Description
icon string The name of a Font Awesome 3.2.1 icon to display to the left of the label (e.g. "lemon", "heart")
image string The complete path to an image to use instead of an icon. If both icon and image are provided, the icon will be used.
label string The label to show for the option
description string A description of the option, displayed as a tooltip when the user hovers over the label
value string If the value differs from the label, the value to return when this option is selected (otherwise label is returned)
Source:
Examples
[
  {
    icon: "",
    image: "https://www.dataone.org/uploads/member_node_logos/bcodmo_hu707c109c683d6da57b432522b4add783_33081_300x0_resize_box_2.png",
    label: "BCO",
    description: "The The Biological and Chemical Oceanography Data Management Office (BCO-DMO) serve data from research projects funded by the Biological and Chemical Oceanography Sections and the Division of Polar Programs Antarctic Organisms & Ecosystems Program at the U.S. National Science Foundation.",
    value: "urn:node:BCODMO"
  },
  {
    icon: "",
    image: "https://www.dataone.org/uploads/member_node_logos/arctic.png",
    label: "ADC",
    description: "The US National Science Foundation Arctic Data Center operates as the primary repository supporting the NSF Arctic community for data preservation and access.",
    value: "urn:node:ARCTIC"
  },
]
{
  "category A": [
    {
      icon: "flag",
      label: "Flag",
      description: "This is a flag"
    },
    {
      icon: "gift",
      label: "Gift",
      description: "This is a gift"
    }
  ],
  "category B": [
    {
      icon: "pencil",
      label: "Pencil",
      description: "This is a pencil"
    },
    {
      icon: "hospital",
      label: "Hospital",
      description: "This is a hospital"
    }
  ]
}

placeholderText :string

Text to show in the input field before any value has been entered
Type:
  • string
Source:

selected :Array.<string>

The values that a user has selected. If provided to the view upon initialization, the values will be pre-selected. Selected values must exist as a label in the options SearchableSelect#options
Type:
  • Array.<string>
Source:
When items are grouped within categories, this attribute determines how to display the items within each category.
Type:
  • string
Default Value:
  • "list"
Source:
Examples
// display the items in a traditional, non-interactive list below category titles
"list"
// initially show only a list of category titles, and popout
// a submenu on the left or right when the user hovers over
// or touches a category (can lead to the sub-menu being hidden
// on mobile devices if the element is wide)
"popout"
// initially show only a list of category titles, and expand
// the list of items below each category when a user clicks
// on the category title, much like an "accordion" element.
"accordion"

template :Underscore.template

The primary HTML template for this view. The template follows the structure specified for the semanticUI dropdown module, see: https://semantic-ui.com/modules/dropdown.html#/definition
Type:
  • Underscore.template
Source:

transitionCSS :string

The path to the semanticUI transition CSS (required for this view to work)
Type:
  • string
Source:

type :string

The type of View this is
Type:
  • string
Source:

Methods

addTooltip(element, position) → {jQuery}

addTooltip - Add a tooltip to a given element using the description in the options object that's set on the view.
Parameters:
Name Type Description
element HTMLElement The HTML element a tooltip should be added
position string how to position the tooltip - top | bottom | left | right
Source:
Returns:
The element with a tooltip wrapped by jQuery
Type
jQuery

changeSelection(newValues)

changeSelection - Set selected values in the interface
Parameters:
Name Type Description
newValues Array.<string> An array of strings to select
Source:

checkIfReady(callback)

checkIfReady - Check if the searchable select field is ready to use. If the transition UI CSS file isn't loaded in time, search fields might give error when selecting (or pre-selecting) values.
Parameters:
Name Type Description
callback function The function to call when the UI is ready
Source:

convertToAccordion()

convertToAccordion - Re-arrange the HTML to display category items with expandable sections, similar to an accordion element.
Source:

convertToList()

convertToList - Re-arrange HTML to display the full list of options in one static menu
Source:

convertToPopout()

convertToPopout - Re-arrange the HTML to display category contents as sub-menus that popout to the left or right of category titles
Source:

disable()

disable - Add the class the makes the select UI appear disabled
Source:

enable()

enable - Remove the class the makes the select UI appear disabled
Source:

hideEmptyCategories()

hideEmptyCategories - In the searchable select interface, hide category headers that are empty, if any
Source:

hideLoading()

hideLoading - Remove the loading spinner set by the showLoading
Source:

initialize(options)

Creates a new SearchableSelectView
Parameters:
Name Type Description
options Object A literal object with options to pass to the view
Source:

isValidOption(value) → {boolean}

isValidOption - Checks if a value is one of the values given in view.options
Parameters:
Name Type Description
value string The value to check
Source:
Returns:
returns true if the value is one of the values given in view.options
Type
boolean

postRender()

postRender - Updates to the view once the dropdown UI has loaded
Source:

removeMessages()

removeMessages - Remove all messages and classes set by the showMessage function.
Source:

render() → {SeachableSelect}

Render the view
Source:
Returns:
Returns the view
Type
SeachableSelect

showAllCategories()

showAllCategories - In the searchable select interface, show all category headers that were previously empty
Source:

showLoading()

showLoading - Indicate that dropdown options are loading by showing a spinner in the select interface
Source:

showMessage(message, type, removeOnChange)

showMessage - Show an error, warning, or informational message, and highlight the select interface in an appropriate colour.
Parameters:
Name Type Description
message string The message to display. Use an empty string to only highlight the select interface without showing a messsage.
type string one of "error", "warning", or "info"
removeOnChange boolean set to true to remove the message as soon as the user changes the selection
Source:

updateMenu()

updateMenu - Re-render the menu of options. Useful after changing the options that are set on the view.
Source: