The Replicator Plugin allows users to replicate HTML, and manage the cloned children. In addition to merely creating and managing these nodes, Replicator also comes with a basic templating language, which allows for selector based DOM manipulation.
The Replicator was built around the concept of creating once, then recycling. The idea is to never destroy and recreate templates, but to recycle their content as needed.
First, we must declare a replication template. In this case, the option for a select element. The best practice is to use an identifier for the replication template for quickly locating it in the DOM. The Identifier is removed from the template when it is cloned.
<body>
<label>Choose Your Favorite Single-Digit Prime Number!</label>
<select id="choose-option">
<option id="choice-template"><span class="index"></span> Prime Number (<span class="special"></span>)</option>
</select>
</body>
Next, we need to set up any replacement rules, declare the replication target and template, and create a callback to seed our data.
jQuery(function(){
// Let's assume the variable ajaxResponse contains a JSON array from the server, like this:
ajaxResponse = [
{valueKey: 1, actual: 1, index: '1st', color: 'red'},
{valueKey: 2, actual: 3, index: '2nd', color: 'green'},
{valueKey: 3, actual: 5, index: '3rd', color: 'blue'},
{valueKey: 4, actual: 7, index: '4th', color: 'black'}
];
// The following function is our callback, which will be triggered when we finish replicating.
function startReplicating(){
var self = this; // Contains the reference to the replicator object
$.each(ajaxResponse, function(i){
self.update(i, this); // while in the .each loop, "this" is the ajaxResponse value.
}
}
// First, we declare our replicator's group, replacement rules, and target
var replicator = jQuery('#choice-template').replicator('some_identifier', {
value: {func: 'val', value: 'valueKey'},
special: {selector: '.special', func: 'html', value: 'actual'},
index: {selector: '.index', func: 'html', value: 'index'},
extra: {func: 'css', type: 'color', value: 'optionColor'}
}, '#choose-option');
// Next, we need to declare the number of replicated templates we'll need, and declare our callback
replicator.setReplications( ajaxResponse.length, startReplicating);
Replicator provides four convenient interfaces from jQuery, and a namespaced storage object:
jQuery('#template-selector').replicator('arbitrary_group_name', {rules: {}}, '#container-selector');
jQuery('#container-selector').replicatorContainer('arbitrary_group_name', '#template-selector', {rules: {}});
new jQuery.Replicator('arbitrary_group_name', '#template-selector', '#container-selector', {rules: {}});
jQuery('#template-selector').replicate('arbitrary_group_name', '#optional-container');
// Invoke Through:
Replicator.template.replicate('some_group', '#some-selector');
This method allows the user to invoke a replication, but set the container or replacement group to any other element. See the Replacements section for more info.
[NOTE] This method only works on an established replicator, as seen in the Invoke Through example.
jQuery.replication = {
replacements: {groupName: {rules: {}}},
engines: {groupName: ReplicatorObject}
}
Users can access the replicator for a specific group using the "engines" key from the storage object
Replicator contains NO user-configurable properties.
These properties should be treated as Read-Only. If you attempt to manually set any of these, you could render Replicator inoperable.
Replicator.[VARIABLE_NAME]
Replicator.setReplications( number, [callback] )Declares how many replications should exist in the system, with an optional callback to fire when the replications are created.
[NOTE] Number is the maximum replicated children you need in the system. If you have already created 25 replications, and pass "2" in for number, no additional replications will be created, and the callback will be triggered instantly.
[NOTE] Within the callback, "this" is a reference to the Replicator instance.
Replicator.replicate( number, [callback] )Replicates the current template as many times as specified by number, triggering an optional callback upon completion.
[NOTE] Unlike the setReplications() method, if you already have 25 replications, and pass in "2" for number, 2 additional replications will be created.
Replicator.hide( )Hides all replicator clones currently being managed.
Replicator.each( callback )Loops through all replicator clone, firing the callback. Just like calling jQuery('#selector').each( function )
Replicator.get( index )A method used for fetching a specific replicator by its index in the zero-based array.
[NOTE] If you attempt to get a replicator clone that does not exist, Replicator will trigger a REPLICATOR_INVALID_INDEX_[N] exception, where [N] is the index you attempted to retrieve.
Replicator.update( index, replacements )A method used for updating the content of a specific replicator by its index in the zero-based array.
[NOTE] If you attempt to update a replicator clone that does not exist, Replicator will trigger a REPLICATOR_INVALID_INDEX_[N] exception, where [N] is the index you attempted to retrieve.
[NOTE] See the Replacements section for more info.
The replacements system allows you to define selector-based references to internal objects in a template, and specify how those internal objects should be update.
When Replicator.update() is invoked, the values passed in as the second argument will be seeded into the clone as defined by the replacement rules defined at initialization.
| Parameter Name | Parameter Type | Example | Description |
|---|---|---|---|
| selector | String or NULL or FALSE | selector: '.some-selector' | If "selector" is excluded from a definition, or marked as null or false, then the Root Level template element will be used. Otherwise, it will select $('.selector', templateRoot) |
| func | String | func: 'css' | Declares the name of the jQuery method to chain off the selected element. |
| type | String or NULL or FALSE | type: 'backgroundColor' | For methods that take flat key/value objects as their argument, type is the key. ex: .css({ *type*: *value* }); |
| value | String | value: 'someArbitraryKey' | When invoking the "update" method, the second argument passed in must be a hash of key/value pairs. Whatever is put in "value" during ruleset should correspond to a key entered in the replacement array. |
| apply | Boolean | apply: true | If apply is true, then the value passed in with your replacement object during an "update" MUST be an array containing the list of parameters you wish to call the function with. Ex: bind('click', {id: '7'}, someHandler) would be passed in as: ['click', {id: '7'}, someHandler] when apply is true. |
<body>
<div id="replicator-template">
<h4 class="content"></h4>
<a><span class="ui-icon"></span> <img/></a>
</div>
</body>
Given this example template, we want to create a set of rules to allow the following:
{ // Assign some CSS properties to the root of the template (the containing div)
positioning: {func: 'css', value: 'positioning'},
// Assign some text to the h4 tag
title: {selector: 'h4', func: 'text', value: 'title'},
// Assign a custom event to the internal anchor tag
event: {selector: 'a', func: 'blind', value: 'event', apply: true},
// Assign a href to the internal anchor tag
href: {selector: 'a', func: 'attr', type: 'href', value: 'href'},
// Assign a class to the internal span which contains a jQuery-UI-ThemeRoller Icon
icon: {selector: '.ui-icon', func: 'addClass', value: 'icon'},
// Assign an image source and alt to the image tag
img: {selector: 'img', func: 'attr', value: 'img'}
}
Replicator.update(0, {
// Assign some CSS properties to the root of the template (the containing div)
positioning: {position: absolute, left: 10, top: 50},
// Assign some text to the h4 tag
title: 'My Element',
// Assign a custom event to the internal anchor tag
event: ['mycustomevent.namespaced', {reference: someElement}, myCustomEventHandler],
// Assign a href to the internal anchor tag
href: 'somepage.php',
// Assign a class to the internal span which contains a jQuery-UI-ThemeRoller Icon
icon: 'ui-icon-extlink',
// Assign an image source and alt to the image tag
img: {src: 'someimg.jpg', alt: 'A Link Description Image'}
}
Please visit: http://eric.garside.name/demo.html?p=replicator
The current version of Replicator can be downloaded from Google Code
You can also checkout the subversion repository for Replicator with the following command:
svn checkout http://jquery-curator.googlecode.com/svn/trunk/ jquery-curator-read-only