eZ.SelectionFilterView Class
A view allowing to select one or several items amongst a list and to filter the list by typing some text in an input field. It is based on YUI AutoCompleteBase component.
This view is meant to progressively enhance an existing markup:
<div class="container">
<input type="text">
<ul></ul>
</div>
Then, you can instantiate the view with:
new Y.eZ.SelectionFilterView({
container: '.container',
inputNode: '.container input',
listNode: '.container ul',
source: ['Iron Man', 'Hulk', 'Thor', 'Black Widow']
});
Constructor
eZ.SelectionFilterView
()
Item Index
Methods
- _afterSourceTypeChange
- _afterValueChange
- _beforeCreateObjectSource
- _bindUIACBase
- _createArraySource
- _createFunctionSource
- _createIOSource
- _createJSONPSource
- _createObjectSource
- _createSelectSource
- _createStringSource
- _createYQLSource
- _defaultYQLLocator
- _defClearFn
- _defQueryFn
- _defResultsFn
- _functionValidator
- _getListNode
- _getObjectValue
- _getTargetAttributes
- _getXHRUrl
- _isItemSelected
- _itemMouseOout
- _itemMouseOver
- _jsonpFormatter
- _onInputBlur
- _onInputValueChange
- _onResponse
- _parseResponse
- _parseValue
- _select
- _setEnableCache
- _setLocator
- _setRequestTemplate
- _setResultFilters
- _setResultHighlighter
- _setSource
- _sourceSuccess
- _syncBrowserAutocomplete
- _syncUIACBase
- _uiActiveItem
- _uiActiveItem
- _uiAddItemNode
- _uiSelectItem
- _uiSelectItem
- _uiSetDefaultList
- _uiSetList
- _updateValue
- clearCache
- focus
- initializer
- render
- resetFilter
- sendRequest
- unselect
Properties
Attributes
- allowBrowserAutocomplete
- allowTrailingDelimiter
- enableCache
- filter
- inputNode
- isMultiple
- listNode
- maxResults
- minQueryLength
- query
- queryDelay
- queryDelimiter
- requestTemplate
- resultAttributesFormatter
- resultFilters
- resultFormatter
- resultHighlighter
- resultListLocator
- results
- resultTextLocator
- selected
- source
- sourceType
- tokenInput
- value
- yqlEnv
- yqlProtocol
Methods
_afterSourceTypeChange
-
e
source
based on the new sourceType
to ensure that
the two attributes don't get out of sync when they're changed separately.
Parameters:
_afterValueChange
-
e
value
attribute.
Parameters:
_beforeCreateObjectSource
-
source
_createObjectSource()
method and augments
it to support additional object-based source types.
Parameters:
-
source
String
_bindUIACBase
()
protected
_createArraySource
-
source
source
attribute for more details.
Parameters:
-
source
Array
Returns:
_createFunctionSource
-
source
source
attribute for more details.
Parameters:
-
source
FunctionFunction that accepts a query and a callback as parameters, and calls the callback with an array of results.
Returns:
_createIOSource
-
source
Y.io
as a source. See the
source
attribute for more details.
Parameters:
-
source
StringURL.
Returns:
_createJSONPSource
-
source
source
attribute for more details.
Parameters:
-
source
JSONPRequest | StringURL string or JSONPRequest instance.
Returns:
_createObjectSource
-
source
source
attribute for more details.
Parameters:
-
source
Object
Returns:
_createSelectSource
-
source
<select>
node as
a source.
Parameters:
-
source
NodeYUI Node instance wrapping a<select>
node.
Returns:
_createStringSource
-
source
source
attribute for more details.
Parameters:
-
source
StringURL or YQL query.
Returns:
_createYQLSource
-
source
source
attribute for details. If no
resultListLocator
is defined, this method will set a best-guess locator
that might work for many typical YQL queries.
Parameters:
-
source
StringYQL query.
Returns:
_defaultYQLLocator
-
response
Parameters:
-
response
ObjectYQL response object.
Returns:
_defClearFn
()
protected
clear
event handler. Sets the results
attribute to an empty
array and query
to null.
_defQueryFn
-
e
query
event handler. Sets the query
attribute and sends a
request to the source if one is configured.
Parameters:
_defResultsFn
-
e
results
event handler. Sets the results
attribute to the latest
results.
Parameters:
_functionValidator
-
value
true
if _value_ is either a function or null
.
Parameters:
-
value
Function | NullValue to validate.
_getListNode
-
value
Returns the list item node based on a string value
Parameters:
-
value
String
Returns:
_getObjectValue
-
obj
-
path
Y.Object.getValue()
. Doesn't bother
casting the path to an array (since we already know it's an array) and
doesn't throw an error if a value in the middle of the object hierarchy is
neither undefined
nor an object.
Parameters:
-
obj
Object -
path
Array
Returns:
undefined
if the value was
not found at the specified path.
_getTargetAttributes
-
the
Returns the attributes of the selected element. The attributes are the data attribute of the selected element.
Parameters:
-
the
Nodeselected node
Returns:
a hash with the attributes values.
_getXHRUrl
-
url
-
request
Parameters:
-
url
StringBase URL. -
request
ObjectRequest object containingquery
andrequest
properties.
Returns:
_itemMouseOout
-
e
Event handler for the mouseout event on the list items.
Parameters:
-
e
Objectevent facade
_itemMouseOver
-
e
Event handler for the mouseover event on the list items.
Parameters:
-
e
Objectevent facade
_jsonpFormatter
-
url
-
proxy
-
query
JSONPRequest
instances.
Parameters:
-
url
String -
proxy
String -
query
String
Returns:
_onInputValueChange
-
e
valueChange
events on the input node and fires a query
event
when the input value meets the configured criteria.
Parameters:
_onResponse
-
e
results
event.
Parameters:
_parseResponse
-
query
-
response
-
data
results
event.
Parameters:
-
query
StringQuery that generated these results. -
response
ObjectResponse containing results. -
data
ObjectRaw response data.
_parseValue
-
value
null
if there
is no suitable query within the input value.
If a query delimiter is defined, the query will be the last delimited part
of of the string.
Parameters:
-
value
StringInput value from which to extract the query.
Returns:
_select
-
e
Event handler for the tap event happening on the item elements. It selects or unselects the items depending on the current state.
Parameters:
-
e
Objectevent facade
_setEnableCache
-
value
enableCache
attribute.
Parameters:
-
value
Boolean
_setLocator
-
locator
Parameters:
-
locator
Function | String | Null
Returns:
_setRequestTemplate
-
template
requestTemplate
attribute.
Parameters:
-
template
Function | String | Null
Returns:
_setResultFilters
-
filters
resultFilters
attribute.
Parameters:
-
filters
Array | Function | String | Nullnull
, a filter function, an array of filter functions, or a string or array of strings representing the names of methods onY.AutoCompleteFilters
.
Returns:
null
).
_setResultHighlighter
-
highlighter
resultHighlighter
attribute.
Parameters:
-
highlighter
Function | String | Nullnull
, a highlighter function, or a string representing the name of a method onY.AutoCompleteHighlighters
.
Returns:
_setSource
-
source
source
attribute. Returns a DataSource or a DataSource-like
object depending on the type of _source_ and/or the value of the
sourceType
attribute.
Parameters:
-
source
AnyAutoComplete source. See thesource
attribute for details.
Returns:
_sourceSuccess
-
data
-
request
Parameters:
-
data
AnyResponse data. -
request
ObjectRequest object.
_syncBrowserAutocomplete
()
protected
allowBrowserAutocomplete
attribute.
_syncUIACBase
()
protected
inputNode
.
_uiActiveItem
-
item
Sets the item as active by adding the active class
Parameters:
-
item
Node
_uiActiveItem
-
item
Sets the item as inactive by adding the active class
Parameters:
-
item
Node
_uiAddItemNode
-
content
-
attrs
Adds an item in the list of possible choice.
Parameters:
-
content
Stringthe string to display
-
attrs
Stringhash to create data attributes
_uiSelectItem
-
item
Selects the item in the DOM by adding the selected class
Parameters:
-
item
Node
_uiSelectItem
-
item
Unselects the item in the DOM by removing the selected class
Parameters:
-
item
Node
_uiSetDefaultList
()
protected
Adds the unfiltered list of items to the list node
_uiSetList
-
list
Adds some items in the list node based on the list parameter. Each element of the list should be an object with a display and a text entries
Parameters:
-
list
Array
_updateValue
-
newVal
value
attribute.
If a query delimiter is defined, the last delimited portion of the input
value will be replaced with the specified _value_.
Parameters:
-
newVal
StringNew value.
clearCache
()
chainable
focus
()
Focuses the filter input
initializer
()
Initializes the selection filter view. It adds the necessary classes and sets up the event handlers
resetFilter
()
Resets the filter input and the item list
sendRequest
-
[query]
-
[requestTemplate]
query
event to be fired. The only
time you'll need to call this method manually is if you want to force a
request to be sent when no user input has occurred.
Parameters:
-
[query]
String optionalQuery to send. If specified, thequery
attribute will be set to this query. If not specified, the current value of thequery
attribute will be used. -
[requestTemplate]
Function optionalRequest template function. If not specified, the current value of therequestTemplate
attribute will be used.
unselect
-
value
-
[selectedNode]
Unselects an item based on its value
Parameters:
-
value
String -
[selectedNode]
Node optionaloptional selected node for internal use only.
Properties
_YQL_SOURCE_REGEX
RegExp
protected
Attributes
allowBrowserAutocomplete
Boolean
Default: false
allowTrailingDelimiter
Boolean
queryDelimiter
is set, trailing delimiters will automatically be
stripped from the input value by default when the input node loses focus.
Set this to true
to allow trailing delimiters.
Default: false
enableCache
Boolean
Default: true
inputNode
Node | HTMLElement | String
query
events when
appropriate. May be either an <input>
or a <textarea>
.
maxResults
Number
0
or less will allow an
unlimited number of results.
Default: 0
minQueryLength
Number
query
event
will be fired. A value of 0
allows empty queries; a negative value will
effectively disable all query
events.
Default: 1
query
String | Null
readonly
null
if there is no current query.
The query might not be the same as the current value of the input node, both
for timing reasons (due to queryDelay
) and because when one or more
queryDelimiter
separators are in use, only the last portion of the
delimited input string will be used as the query value.
Default: null
queryDelay
Number
query
event. If new input occurs before this delay is over, the previous input
event will be ignored and a new delay will begin.
This can be useful both to throttle queries to a remote data source and to
avoid distracting the user by showing them less relevant results before
they've paused their typing.
Default: 100
queryDelimiter
String | Null
query
attribute is
modified.
Default: null
requestTemplate
Function | String | Null
source
attribute is set to a remote DataSource, JSONP URL, or
XHR URL (it will not be appended to YQL URLs).
While requestTemplate
may be set to either a function or a string, it will
always be returned as a function that accepts a query argument and returns a
string.
Default: null
resultAttributesFormatter
Function
A function to extract the attributes to add for each element in
the source array. The default implementation returns a hash
containing a text
entry holding the toString
return value of
the source element.
resultFilters
Array
results
event for a list
of the properties available on each result object.
Each filter is expected to return a filtered or modified version of the
results array, which will then be passed on to subsequent filters, then the
resultHighlighter
function (if set), then the resultFormatter
function
(if set), and finally to subscribers to the results
event.
If no source
is set, result filters will not be called.
Prepackaged result filters provided by the autocomplete-filters and
autocomplete-filters-accentfold modules can be used by specifying the filter
name as a string, such as 'phraseMatch'
(assuming the necessary filters
module is loaded).
Default: []
resultFormatter
Function | Null
results
event for a list of the properties
available on each result object.
If no source
is set, the formatter will not be called.
resultHighlighter
Function | Null
results
event for a list of the properties
available on each result object.
If no source
is set, the highlighter will not be called.
resultListLocator
Function | String | Null
result.foo.bar.baz
if the response is an object).
While resultListLocator
may be set to either a function or a string, it
will always be returned as a function that accepts a response argument and
returns an array.
resultTextLocator
Function | String | Null
result.foo.bar.baz
if the result is an object).
While resultTextLocator
may be set to either a function or a string, it
will always be returned as a function that accepts a result argument and
returns a string.
source
required
The source for the list of available items. Overrides the source attribute from AutoCompleteBase to only accepts array as source.
sourceType
String
sourceType
values are: 'array', 'datasource', 'function', and
'object'.
If the autocomplete-sources
module is loaded, the following additional
source types are supported: 'io', 'jsonp', 'select', 'string', 'yql'
tokenInput
Plugin.TokenInput
readonly
inputNode
specified at instantiation time has a node-tokeninput
plugin attached to it, this attribute will be a reference to the
Y.Plugin.TokenInput
instance.
Events
clear
Event Payload:
-
prevVal
StringValue of the query before it was cleared. -
src
StringSource of the event.
query
Event Payload:
-
inputValue
StringFull contents of the text input field or textarea that generated the query. -
query
StringAutoComplete query. This is the string that will be used to request completion results. It may or may not be the same asinputValue
. -
src
StringSource of the event.
results
Event Payload:
-
data
Array | ObjectRaw, unfiltered result data (if available). -
query
StringQuery that generated these results. -
results
ObjectArray of filtered, formatted, and highlighted results. Each item in the array is an object with the following properties:-
display
Node | HTMLElement | StringFormatted result HTML suitable for display to the user. If no custom formatter is set, this will be an HTML-escaped version of the string in the
text
property. -
[highlighted]
String optionalHighlighted (but not formatted) result text. This property will only be set if a highlighter is in use.
-
raw
AnyRaw, unformatted result in whatever form it was provided by the source.
-
text
StringPlain text version of the result, suitable for being inserted into the value of a text input field or textarea when the result is selected by a user. This value is not HTML-escaped and should not be inserted into the page using
innerHTML
orNode#setContent()
.
-
select
Fired when a user action selects an item
Event Payload:
-
text
Stringthe value which was selected
-
elementNode
Nodethe node containing the value
-
attributes
Objectthe data attributes on the elementNode. Those attributes are ones returned by the function stored in the resultAttributesFormatter attribute.
unselect
Fired when a user action unselects an item
Event Payload:
-
text
Stringthe value which was unselected