jQuery.sampling plugin

jQuery.sampling exposes several functionallities. Main functions are related with template animation / sampling but it also includes templating related capabilities explained in Templating capabilities.

Setup

You can configure the jQuery.sampling() plugin by calling jQuery.sampling() on the jQuery object (on $ for newbies).

jQuery.sampling([options])

Establishes initial options such as the sample class or new flags. See jQuery.sampling() options for further information.

Arguments:

• options (object) –

  a configuring object which defaults to:

  {
      sampleClass: '_s',
      includeClass: '_inc',
      defaultFlags: {
          ensureText:false,
          clearSamples:true,
          sampleSelectMode:'single'
      }
  }
  

jQuery.sampling() options

sampleClass (defaults to _s)

class to mark HTML elements as samples. These elements will be gathered by using gather().

includeClass (defaults to _inc)

class to mark A elements to be used as place holders for client side includes when calling include().

defaultFlags

see Instantiation flags for more information about these options.

Instantiation flags

ensureText (defaults to false)

during instantiation, content is set to each element by using jQuery.text() instead of jQuery.html() as it’s by default.

clearSamples (defaults to true)

this option removes all nested samples inside the sample being instantiated.

sampleSelectMode (defaults to 'single')

the option sets selection mode of samples when instantiating (see Instantiating samples)

Plugin API

Following jQuery Namespacing convenions, all these methods must be called by using:

jQuery.sampling(<method_name>, ...);

I.e, to call option() to set the value of parameter sampleClass to _sample you should do:

jQuery.sampling('option', 'sampleClass', '_sample');

gather()

Applies on jQuery object. Detaches all sample elements marked by the sample class (by default _s) and returns a collection of them.

Returns:sample collection with all collected samples.

select(selector[, noCache=false])

Applies on sample collection returned by gather(). Selects the proper samples inside the sample collection. The method is cached by the selector so succesive calls to this method have improved performance.

Arguments:

• selector – a valid jQuery selector to look for it inside the sample collection.
• noCache (boolean) – if true, avoid caching by the selector and the query is re-runned. Defaults to false.

Returns:

a jQuery sample object with the sample(s). Avoid to modify this object because it’s the sample itself. Use jQuery.clone() or use new() to build a new copy.

Tip

You can select more than one sample. It is specially useful in combination with Sample Select Mode.

option(optName)

Get value of the optName option.

Arguments:

• optName (string) – name of the option to get.

Returns:

value of the option specified by optName parameter.

option(optName, value)

Set the optName option to value.

Arguments:

• optName (string) – name of the option to set.
• value – value to set.

Instantiating samples

Sample instantiation is the most interesting part of the plugin. Instantiate refers to clone the sample and customize it.

The task can be performed by calling to new() in several ways. The most important concept here is customizing item and sample selection mode.

Customizing items

When a sample is instantiated it is customized by a customizing item. This is an ordinary object where keys are valid jQuery selector strings and values are mixed contents.

During customization process, each key of the customizing item is searched inside the sample and its content is set with the value.

In instance, look at this customizing item:

{
    '.id':1,
    '.name':'Tie Fighter',
    '.type':'Starfighter',
    '.affiliation':'Galactic Empire'
}

Now look at this HTML snippet:

<tr class="_s">
    <td class="id">sample_id1</td>
    <td class="name">sample_name1</td>
    <td class="type">sample_type1</td>
    <td class="affiliation">sample_affiliation1</td>
</tr>

Previous tr sample, after instantiating with the previous item should look like:

<tr>
    <td class="id">1</td>
    <td class="name">Tie Fighter</td>
    <td class="type">Starfighter</td>
    <td class="affiliation">Galactic Empire</td>
</tr>

Sample Select Mode

When you select more than one sample by using select() you can specify which specific sample will be selected to be customized by the next customization item. This can be done by setting the instantiaion flag sampleSelectMode.

If the flag is set with a function, then the function’s signature should be as follows:

sampleSelector(index, length)

Inside the function, this is the sample collection. Parameter index is actually the call count for the function (first time, 0; second time, 1; etc) and length is the length of the sample collection. Return value must be an integer representing the index of the specific sample which will be selected. Return null to stop customization process.

If the flag is set with a number, then it is the index that always will be selected. If the number is negative then it counts starting from the end.

Finally, jQuery.sampling() offers some default functions that you can use by using their name as string:

bounce

goes through each specific sample. When reaching the last one, reverts direction and goes to the first. When reaching the first, ir reverts direction again and so on.

clamp

goes through each specific sample until reaching the last one. After, it always return this last until the end of instantiaion.

identity

go to each sample until reaching the last one, then stops instantiation.

none

ends inmediatlly, with no place for instantiaion.

rotation / altern

goes through each specific sample. When reaching the last sample, it starts over again and so on until the end of instantiation.

single

always select index 0

Following, there is the documentation about the different ways of calling new():

new()

Applies on a jQuery sample object returned by select().

Returns:a clone of the current sample without the sample class.

new(map_generator[, flags={}[, ...]])

Applies on a jQuery sample object returned by select(). Successively calls map_generator using the returned value as the customizing item (see Customizing items) to instantiate the sample. Instantiation process ends when null is returned.

Arguments:

• map_generator (callback) –

  the callback signature should be as follows:

  map_generator(index[, ...])
  

  It receives the number of call (first time, 0; second time, 1; third time, 2...) and all other parameters passed to new() method.

  It should return a customizing item to instantiate the sample or null to end the instantiation process.

  Inside the callback, this refers to the sample’s copy being instantiated.

  Note

  Remember passing flags parameter (you can pass an empty object {} if you cannot change any flag) if you want to add parameters to the map_generator.

• flags (object) – flags to customize the sample’s instantiaion. Default flags can be set by using jQuery.sampling() or option(). Flags are explained in Instantiation flags.
• ... (mixed) – parameters for the map_generator.

Throws Returned values of the map generator or objects inside the array should be customizing items:  

if map_generator does not return customizing items.

Returns:

a jQuery object, clone of the current sample, without the sample class.

new(customizing_array[, flags={}[, ...]])

Applies on a jQuery sample object returned by select(). Generates as much instantiations of the sample object as elements in the array.

Arguments:

• customizing_array (array) –

  The array containing the customizing items to instantiate the sample. Items inside the array can be of one of these types:

  • object: the object must be a customizing item (see Customizing items)
  • function: the function is call under same conditions of map_generator in the previous new() method but it must return a customizing item.
  • rest of the cases: the item will be the content of the instance.

  Note

  Remember passing flags parameter (you can pass an empty object {} if you cannot change any flag) if you want to add parameters to the functions inside the array.

• flags (object) – flags to customize the sample’s instantiaion. Default flags can be set by using jQuery.sampling() or option(). Flags are explained in Instantiation flags.
• ... (mixed) – parameters for the map_generator.

Throws Returned values of the map generator or objects inside the array should be customizing items:  

if items in customizing_array are not customizing items.

Returns:

a jQuery object, clone of the current sample, without the sample class.

Templating capabilities

By the moment only CSI (client side includes) are supported but other features are planned to be integrated soon.

Client side includes

jQuery.sampling() includes a mechanism to perform client side includes (CSI). These includes act like traditional server side includes of languages such as PHP but in the client side. In few words, they are elements pointing some URL, jQuery.sampling() is able to replace these elements with the contents of URL they are pointing to.

To perform a client side include, use CSI place holders. These are anchor elements <a> with the include class (by default _inc, see jQuery.sampling() options) and href attribute pointing to an URL, source of the include:

<a class="_inc" href="./menu.html">This will be replaced by contents of menu.html</a>

Use the following code to perform CSI inside the page on document ready:

$(function() { $(document).sampling('include'); });

include([limit=0])

Replaces CSI place holders by the contents referred by them. Note that you can perform CSI replacements contained by a jQuery object by calling include() from that object.

Note how new content can include more CSI place holders. By default, they will be resolved too but the developer can limitate the bahaviour by passing a non-zero value as parameter limit.

Arguments:

• limit – in case of the new content is containing CSI place holders, the parameter indicates how many times the CSI process will be performed. I.e. a value of 1 indicates only one level of CSI is performed so after resolving CSI place holders for the first time, no further replacements will be done. A value of 0 means to resolve all CSI place holders.

Returns:

the total of CSI successfully resolved.