The Picker
widget provides a common interface for searching
for a match in a large collection, and selecting one of the matches. It
also provides a way to add additional input fields on the picker overlay.
The widget will search against the entries appearing in this text
area. Each line contains one entry with fields separated by
semi-colons, using the format:
value;title;css_class;image;description
<script type="text/javascript" src="../../build/yui/yui.js"></script> <script type="text/javascript" src="../../build/lazr/lazr.js"></script> <script type="text/javascript" src="../../build/overlay/overlay.js"></script> <script type="text/javascript" src="../../build/picker/picker.js"></script>
<link rel="stylesheet" href="../../build/overlay/assets/pretty-overlay-core.css" /> <link rel="stylesheet" href="../../build/overlay/assets/skins/sam/pretty-overlay-skin.css" /> <link rel="stylesheet" href="../../build/formoverlay/assets/formoverlay.css" />
The Picker takes all the arguments that the PrettyOverlay takes, as well as several additional optional arguments.
clear_on_save
(default true
) - Whether
or not the picker should be cleared when the save event is fired.
clear_on_cancel
(default false
) - Whether
or not the picker should be cleared when the cancel event is fired.
picker_activator
(no default) - When set this should
be the CSS selector for the page element that activates the Picker.
A click
event handler is added to this element so that
when it's clicked, the Picker will be displayed.
min_search_chars
(default 3
) - The minimum
number of characters that need to be entered in search input text box
before a search event will be fired. The search string will be
trimmed of whitespace before testing the length.
search_slot
(default null
) - An additional
Node
to insert on the Picker below the search field.
footer_slot
(default null
) - An additional
Node
to insert at the bottom of the Picker. When there
are no search results, the search_slot
and footer_slot
are displayed next to each other.
Here's some sample code that creates a Picker. Note that it's usually a good idea for you to create one Picker, showing and hiding it as needed, rather than creating a new Picker every time you want to display it.
var picker = new Picker({ progressbar: true, progress: 100, headerContent: '<h2>Picker example</h2>', steptitle: 'Enter search terms', picker_activator: '#picker-button' }); picker.render();
In order to provide the search results, you need to implement a handler
that is subscribed to the search
, typically using
an after
handler. The event your handler receives will
contain useful details that can be used to determine search batching.
In order to communicate back to the Picker what should be done as a
result of the search, you'll set two attributes on the Picker:
results
and batches
. Both are required.
results
must be an
Array
of items where each item has the following
attributes:
value
(required) - The value for this
result item. This will be returned to your application
if the item is selected.
title
(required) - The text displayed for this
item in the picker's results list.
description
(optional) - A smaller bit of text
displayed for this item under the title
.
This is displayed in a lighter gray color.
css
(optional) - The CSS class to apply to
this item in the picker's results list.
image
(optional) - An <img> to display
to the left of the title for this item in the results list.
batches
is also an Array
. If all the
search results fit in one batch, then batches
should be
set to []
. If the search results are split into N
batches, then batches
should contain N items, where
each item has the following attributes:
value
(required) - The value returned in the
event details when this page of results is displayed. This
is always the batch number starting from 0.
name
(required) - The text displayed for this
page of results. This is always the batch number + 1 (since
humans count from 1, not 0).
In this example, the application defines a function called
my_perform_search
which takes as an argument the search
text entered in the Picker, and returns the full results array, already
split into batches with items as defined for the results
Picker attribute above. The batch size is therefore defined by the
application.
picker.after('search', function(e) { var search_text = e.details[Picker.SEARCH_STRING]; var selected_batch = e.details[Picker.SELECTED_BATCH_VALUE]; var result_batches = my_perform_search(search_text); if (selected_batch === undefined) { // On a new search, there will be no selected batch. Update the // batches so that the Picker can page through them. var batches = []; Y.Array.each(result_batches, function(batch, i) { var roman = roman_numeral(i + 1); batches.push({ value: i, name: roman }); }); // If there was only one batch of results, then `batches` will // be of length zero, and the picker will know to not display // the page arrows. picker.set('batches', batches); selected_batch = 0; } // Tell the picker what the results are. picker.set('results', results[selected_batch]); });
In order to process the results of the Picker, you will want to subscribe to the save event, which fires when a match result is selected. In the save event, the selected results are available as a detail on the event.
Remember that in the example above we defined the
Picker results
as an array
of items, where each item had up to 5 attributes. The required
value
attribute is what will be returned in the event
details when that item is selected.
picker.subscribe('save', function(e) { var result = e.details[Picker.SAVE_RESULT]; Y.log('Got save event with result: ' + result); });
The cancel event fires when the Escape key is pressed or the close button is clicked. When the Picker is canceled, there are no results available in the event details.
picker.subscribe('cancel', function(e) { Y.log('Got cancel event'); });
Sometimes it's desirable to have a picker associated to a text input so that the value selected from the picker's search results is copied back to that text input when the save event is fired. The TextFieldPickerPlugin does that and also extends the picker to take the initial value of its search input from the associated text input.
picker.plug( Y.lazr.TextFieldPickerPlugin, {input_element: '#initval'});