Using the LAZR picker widget

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.

Demonstration

Search items

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

Last item selected: None
Minimum search characters:
Batch size:
Page labels:
Numbers
Letters

Page setup

The following Javascript and CSS files will need to be included on your page:

Javascript

      <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>
    

CSS

      <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" />
    

Widget setup

The Picker takes all the arguments that the PrettyOverlay takes, as well as several additional optional arguments.

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 Y.Picker({
         progressbar: true,
         progress: 100,
         headerContent: '<h2>Picker example</h2>',
         steptitle: 'Enter search terms',
         picker_activator: '#picker-button'
         });
     picker.render();
  

Implementing search

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:

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:

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[Y.Picker.SEARCH_STRING];
          var selected_batch = e.details[Y.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]);
      });
    

Handling save

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[Y.Picker.SAVE_RESULT];
           Y.log('Got save event with result: ' + result);
       });
    

Handling cancel

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');
       });