Class: Picklet

Container for all the information required to allow the user to search a data source and pick a result.

Author: Aaron Newton

Note

This script contains no Picklets. This means that it isn't very useful unless you write your own or include some (such as CNETProductPicker or NewsStoryPicker);

Implements

Options, Events

Syntax

new Picklet(className, options);

Arguments

className - (string, required) the className associated with the Picklet
options - (object, required) a key/value object of options for the Picklet

Options:

NOTE: all options are required unless otherwise noted.

url - (string) the base url for the data source, defaults to the CNET API (http://api.cnet.com/restApi/v1.0/techProductSearch)
baseHref - (string) the base url for images for the picker
descriptiveName - (string) the name to show in the select list of Picklets available for an input
callBackKey - (string) the wrapper for JsonP (see it for details); defaults to 'callback'
data - (object) an object of key/value pairs to pass along with the request in the url
getQuery - (function) returns a Request or JsonP object that has not yet been executed. Will be passed the data input into the search form by the user
inputs - (object) an object of key/value pairs for inputs for the form. (see below)
previewHtml - (function) a function that is passed a data result from the ajax/json results that will return the HTML for the preview using that data object
resultsList - (function) a function that is passed the response from the ajax/json object above that will turn that response into a list of items (array) to be chosen from
listItemName - (function) a function that is passed a single item from the resultsList and returns the name (string) to be displayed in the list
listItemValue - (function) a function that is passed a single item from the resultsList and returns the value that will be set to the value of the input for the picker
updateInput - (function) a function that is passed the input and the data item that the user selected that then does something with that selection (typically updating the input)

Inputs

The inputs for the search form in the picker can be anything. Each input is described in the inputs object that is an option of the Picklet. See inputs in the options section (above).

Each item in the inputs must be defined thus:

First, the key of the object will be used for the name of the input (i.e. inputs: {query: ....} will result in <input name="query".../>). The values for the object will be translated into the input and its descriptors and properties.

tagName - (string) the name of the tag ('input', 'select', etc.)
type - (string) the type of the input ('text', 'hidden', etc')
instructions - (string) text that will be displayed to the left of the input
tip - (string) tool-tip info that is displayed on hover. Format: CAPTION::TIP DEFINITION
value - (string) the value of the input by default. If type is 'select', this should be an array of values
optionNames - (string) if the type is 'select', an array text values for the option elements (what the user sees)
style - (string) an object of style properties for the input (e.g. style: {width: "100%"})

Example

Here is an example Picklet in it's entirety:

var CNETProductPicker = new Picklet('CNETProductPicker',{
    url: 'http://api.cnet.com/restApi/v1.0/techProductSearch',
    descriptiveName: 'CNET Product Picker Sortable',
    callBackKey: 'callback', //see <JsonP> options
    data: {
        partKey: 'YOUR PARTNER KEY FROM API.CNET.COM',
        iod: 'hlPrice',
        viewType: 'json',
        sortDesc: 'true'
    }, //static data
    getQuery: function(data){ //return Request or JsonP
        return new JsonP(this.options.url, {
            callBackKey: this.options.callBackKey,
            data: $merge(this.options.data, data)
        });
    },
    inputs: {
        query: {
            tagName: 'input',
            type: 'text',
            instructions: 'search for: ',
            tip: 'cnet product search::input a product name and hit &lt;enter&gt; to get results',
            value: '',
            style: {
                width: '100%'
            }
        },
        orderBy: {
            tagName: 'select',
            instructions: 'order by: ',
            style: {
                width: '100%'
            },
            value: ['pop9%2Bdesc', 'edRating7'],
            optionNames: ['most popular', 'editor\'s rating']
        },
        submit: {
            tagName: 'input',
            type: 'submit',
            style: {
                cssFloat: 'right'
            },
            instructions: '',
            value: 'submit'
        }
    }, //form builder
    previewHtml: function(data){
        var editors = "";
        var html = '<div class="dataId" style="color: #999; font-weight:bold; margin: 0px; padding: 0px;">' +
            id: ' + data['@id'] + '</div>'+
            '<div class="dataDetails" style="font-size: 10px;">' +
            <img height="45" width="' + data.ImageURL[0]["@width"] + '" style="margin-left: 10px" src="' +
            data.ImageURL[1].$ + '"/><br /><b>' + data.Name.$ + '</b>';
        if(data.EditorsRating && data.EditorsRating.$) 
            html += "<br/>editors' rating: " + data.EditorsRating.$;
        html += "<div>";
        if(data.LowPrice && data.LowPrice.$) html += 
            "<span class='productPickerPrices'>" + data.LowPrice.$ + "</span>";
        if(data.HighPrice && data.HighPrice.$ && (data.LowPrice.$ != data.HighPrice.$))
                html += " to <span class='productPickerPrices'>" + data.HighPrice.$ + "</span>";
        html += "</div></div>";
        html += "<div>";
        if(data.Offers && data.Offers['@numFound'] > 0) 
            html += "resellers: " + data.Offers["@numFound"];
        html += "</div>";
        return html;
    }, //html template for returned json data
    resultsList: function(results){
        if(results.CNETResponse.TechProducts && results.CNETResponse.TechProducts["@numFound"] > 0)
            return results.CNETResponse.TechProducts.TechProduct;
        return false;
    },
    listItemName: function(data){
        return data.Name.$
    }, //line item name for the selection list
    listItemValue: function(data){
        return data['@id'];
    },
    //handle the click event; user chooses an item, and this function updates the input 
    //(or does something else)
    updateInput: function(input, data) {
        input.value = data['@id'];
    }
});

Class: ProductPicker

Handles the UI for picking products; requires at least one Picklet.

Implements

Options, Events, StyleWriter

Syntax

new ProductPicker(inputs, picklets[, options]);

Arguments

input - (mixed) A string of the id for an Element or an Element reference that the ProductPicker references
picklets - (array) an array of Picklets
options - (object) a key/value set of options

Options

title - (string) caption for the StickyWin popup; defaults to "Product picker"
showOnFocus - (boolean) whether the product picker shoule show when the user focuses the input; default to true
additionalShowLinks - (array) array of DOM elements or ids that show the picker when clicked
stickyWinToUse - (class) a reference to a StickyWin class to use for the popup; default is StickyWinFx
stickyWinOptions - (object) a key/value set of options to pass along to the StickyWin; defaults to {fadeDuration: 200, draggable: true}
moveIntoView - (boolean) moves the picker to be on screen if it is partially obscured; defaults to true

Events

onShow - (function) callback to execute when the ProductPicker is displayed
onPick - (function) callback to execute when the user clicks an entry

ProductPicker Method: show

Shows the ProductPicker

Syntax

myProductPicker.show();

Returns

object - This instance of ProductPicker

ProductPicker method: hide

Hides the ProductPicker.

Syntax

myProductPicker.hide();

Returns

(object) - This instance of ProductPicker

ProductPicker global functions

These functions are available to the ProductPicker namespace itself, not instances of it. Use these functions to add Picklets to the ProductPicker object, which will be available to all instances of the ProductPicker class.

ProductPicker Namespace Method: add

Adds a Picklet to the list of Picklets available to the ProductPicker class.

Syntax

ProductPicker.add(picklet);

Arguments

picklet - (class) a Picklet

Returns

nothing

ProductPicker Namespace Method: addAllThese

Adds several Picklets to the list of Picklets available to the ProductPicker class.

Syntax

ProductPicker.addAllThese([picklet, picklet, etc.]);

Arguments

picklets - an array of Picklets

Returns

nothing

ProductPicker Namespace Method: getPicklet

Returns a Picklet that matches the given className (or false, if none was found).

Syntax

ProductPicker.getPicklet(className);

Arguments

className - (string) the css className for the Picklet

Returns

nothing

Class: FormPickers

Adds the appropriate ProductPickers to all the inputs in a form as defined in the classNames assigned to each input.

Implements

Options

Syntax

new FormPickers(form[, options]);

Arguments

form - (mixed) A string of the id for an Element or an Element reference to the form
options - (object) a key/value set of options

Options

inputs - (string) selector of input types to parse; defaults to 'input' (but could include textarea, select, etc.)
additionalShowLinkClass - (string) className for links that should show the ProductPicker when clicked. Each input in the form will be checked to see if its next sibling (i.e. the DOM element right after the input) has this class and, if so, the element will have an event attached so that the picker is shown when it is clicked.
pickletOptions - (object) options passed along to each ProductPicker created.

This documentation is released under a Attribution-NonCommercial-ShareAlike 3.0 License.

CNET JS Code Documentation

Core

Browser

Native

Element

Fx

Request

UI

Layout

Forms

iPhone

CNET

3rdParty

Note

Implements

Syntax

Arguments

Options:

Inputs

Example

Implements

Syntax

Arguments

Options

Events

Syntax

Returns

Syntax

Returns

Syntax

Arguments

Returns

Syntax

Arguments

Returns

Syntax

Arguments

Returns

Implements

Syntax

Arguments

Options