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.

Screenshot

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:

apiSettings :Object|booealn

Can be set to an object to specify API settings for retrieving remote selection menu content from an API endpoint. Details of what can be set here are specified by the Semantic-UI / Fomantic-UI package. Set to false if not retrieving remote content.
Type:
  • Object | booealn
Since:
  • 2.15.0
Default Value:
  • false
Source:
See:

changeableSeparatorClass :string

An additional HTML class to add to separator elements on hover when a user can click that element to switch the text.
Type:
  • string
Since:
  • 2.17.0
Source:

changeableSeparatorTooltip :string

For separators that are changeable (see SearchableSelectView#separatorTextOptions), optional tooltip text to show when a user hovers over a separator element.
Type:
  • string
Since:
  • 2.17.0
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:

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 un-categorized 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:

separatorClass :string

The HTML class name to add to the separator elements that are created for this view.
Type:
  • string
Since:
  • 2.15.0
Source:

separatorText :string

For select inputs where multiple values are allowed (SearchableSelectView#allowMulti is true), optional text to insert between labels. Separator text is useful for indicating operators in filter fields or values.
Type:
  • string
Since:
  • 2.15.0
Source:

separatorTextOptions :Array.<string>

For select inputs where multiple values are allowed (SearchableSelectView#allowMulti is true), a list of SearchableSelectView#separatorText options. If a list is provided here (AND a value is provided for the SearchableSelectView#separatorText option), then a user can click on the separator text between two values to change the text to the next string in this list. If separatorTextOptions is false (or if there is no separatorText value), then changing the separator text is not possible. This view will trigger a "separatorChanged" event when the separator is updated.
Type:
  • Array.<string>
Since:
  • 2.17.0
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:

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:

changeSeparator()

Changes the separator text for all separator elements to the next value that's set in the SearchableSelectView#separatorTextOptions. Triggers a "separatorChanged" event that passes on the new separator value.
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:

createSeparator() → {JQuery}

Create the HTML for a separator element to insert between two labels. The view.separatorClass is added to the separator element.
Since:
  • 2.15.0
Source:
Returns:
Returns the separator as a jQuery element
Type
JQuery

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() → {SearchableSelect}

Render the view
Source:
Returns:
Returns the view
Type
SearchableSelect

separatorRequired() → {boolean}

Checks whether a separator should be created for the label that was just created, but not yet attached to the DOM
Since:
  • 2.15.0
Source:
Returns:
- Returns true if a separator should be created, false otherwise.
Type
boolean

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 any message text.
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:

updateOptions(options)

Change the options available in the dropdown menu and re-render.
Parameters:
Name Type Description
options SearchableSelectView#options The new options
Since:
  • 2.24.0
Source: