My favorites | Sign in
Project Home Downloads Wiki Issues Source
READ-ONLY: This project has been archived. For more information see this post.
Search
for
PopulateFunctions  
The mechanisms used to construct the contents of Pinwheel's choices.
Updated Mar 12, 2008 by dan.dor...@gmail.com

Introduction

A Pinwheel's populate function provides the mechanism for setting up the contents of each of a Pinwheel's choices.

As with the MouseoverAndMouseout functions, Pinwheel provides some ready-made populate functions.

Details

A Pinwheel populate function is passed three arguments: the first corresponds to the value of the related OPTION element, the second to the OPTION text, and the third to the OPTION's position in the list.

For example, HTML like this...

<select id="im-gonna-be-a-pinwheel">
  <option value="1">foo</option>
</select>

...generates a call to the populate function vaguely like this:

Pinwheel.populate(1, 'foo', 0);

Pinwheel.Populate

nothing

If for some reason nothing seems like the proper contents for a Pinwheel's choices, this is the way to go.

Frankly, I'm not sure why this function is in here; it seems like something ought to go into each Pinwheel. I think I was considering the possibility that each choice might somehow get styled via CSS (i.e., assigned its own id or class), but there is no good mechanism for doing that in place yet. Soon?

optionText

Inserts the text of the corresponding OPTION element into the choice's DIV.

optionValue

Inserts the text of the corresponding OPTION string into the choice's DIV.

image

Sticks an IMG element into the choice's DIV.

If this populate function is used, it needs to be initialized by passing it a lookup object (described below); that is, calling this function returns the actual function that's going to be used when the Pinwheel calls its populate function. Clear as mud?

So what is this lookup object that image wants? The simplest thing to pass in is a Prototype Hash (as of version 1.6). Each key in the Hash corresponds to the value of the OPTION element it's going to replace; each value in the Hash corresponds to the URL for the src attribute of the IMG element. (As an added bonus, the alt and title attributes are set to the inner text of the OPTION.)

For example, let's say you're using a Pinwheel for shoe brands:

The HTML:

<select id="shoe-brands">
  <option value="adidas">Adidas</option>
  <option value="nike">Nike</option>
  <option value="reebok">Reebok</option>
</select>

The Javascript:

var shoes = $H({
  adidas: '/images/adidas.png',
  nike: '/images/nike.png',
  reebok: '/images/reebok.png'
});

new Pinwheel('shoe-brands', {
  // options
  populate: Pinwheel.Populate.image(shoes)
  // options
});

Now, while a Hash is perhaps the most straightforward thing to use, if you're feeling clever you can instead pass in an object that has simply has a method named "get". That way you can algorithmically specify which images to load. As an example, the images in the last example were all basically the same; only the brand name varied. So instead of explicitly stating each URL, we could have done this:

new Pinwheel('shoe-brands', {
  // options
  populate: Pinwheel.Populate.image({
    get: function(value) {
      return '/images/#{brand}.png'.interpolate({ brand: value });
    }
  })
  // options
});

cssSprite

Sorta like Pinwheel.Populate.image, but sets the choice's DIV background-image CSS property to a location in an image sprite (which are all the rage these days).

The initial call to cssSprite expects the URL of the sprite, a lookup object (a Hash or your own custom object--see Pinwheel.Populate.image for details). You can also specify whether to use the OPTION's value to reference the lookup object (the default), or the OPTION's index instead. Each key of the lookup object is expected to reference an object containing x and y properties, corresponding to the horizontal and vertical offsets (in pixels) on the sprite.

Perhaps an example?

We'll use the shoe brands from Pinwheel.Populate.image again, but this time, we've got a spiffy CSS sprite containing all of the brand logos in one image with, say, each logo being 50 pixels square. The HTML stays the same, but the Javascript looks a little something like this:

var shoes = $H(
  adidas: { x: 0,    y: 0 },
  nike:   { x: -50,  y: 0 },
  reebok: { x: -100, y: 0 }
});

new Pinwheel('shoe-brands', {
  // options
  populate: Pinwheel.Populate.cssSprite('/images/logos.png', shoes)
  // options
});

Now how about a more programmatic approach, using a custom lookup object? If we structured the sprite such that the order in which the brands appeared was the same order the OPTION elements were listed in the SELECT, we wouldn't even need to reference the brand name, we could just use the index of the OPTION.

Maybe like this?

new Pinwheel('shoe-brands', {
  // options
  populate: Pinwheel.Populate.cssSprite('/images/logos.png', {
    get: function(index) {
      return { x: -50 * index };
    }
  }, true)  // the true means we want the OPTION's index, not its value!
  // options
});

Note that we didn't even need to specify a y-offset; Pinwheel can get by without it. Actually, that's true if you pass a Hash to cssSprite, too.

Powered by Google Project Hosting