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
allowMulti :boolean
Whether to allow users to select more than one value
Type:
- boolean
className :string
The HTML class names for this view element
Type:
- string
clearable :boolean
Whether the dropdown value can be cleared by the user after being
selected.
Type:
- boolean
dropdownCSS :string
The path to the semanticUI dropdown CSS (required for this view to work)
Type:
- string
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
imageHeight :number
The maximum height of images used for each option, in pixels
Type:
- number
imageWidth :number
The maximum width of images used for each option, in pixels
Type:
- number
inputLabel :string
Label for the input element
Type:
- string
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) |
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
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>
submenuStyle :string
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
transitionCSS :string
The path to the semanticUI transition CSS (required for this view to work)
Type:
- string
type :string
The type of View this is
Type:
- string
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 |
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 |
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 |
convertToAccordion()
convertToAccordion - Re-arrange the HTML to display category items
with expandable sections, similar to an accordion element.
convertToList()
convertToList - Re-arrange HTML to display the full list of options
in one static menu
convertToPopout()
convertToPopout - Re-arrange the HTML to display category contents
as sub-menus that popout to the left or right of category titles
disable()
disable - Add the class the makes the select UI appear disabled
enable()
enable - Remove the class the makes the select UI appear disabled
hideEmptyCategories()
hideEmptyCategories - In the searchable select interface, hide
category headers that are empty, if any
hideLoading()
hideLoading - Remove the loading spinner set by the showLoading
initialize(options)
Creates a new SearchableSelectView
Parameters:
Name | Type | Description |
---|---|---|
options |
Object | A literal object with options to pass to the view |
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 |
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
removeMessages()
removeMessages - Remove all messages and classes set by the
showMessage function.
render() → {SeachableSelect}
Render the view
Returns:
Returns the view
- Type
- SeachableSelect
showAllCategories()
showAllCategories - In the searchable select interface, show all
category headers that were previously empty
showLoading()
showLoading - Indicate that dropdown options are loading by showing
a spinner in the select interface
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 |
updateMenu()
updateMenu - Re-render the menu of options. Useful after changing
the options that are set on the view.