Tag: jQuery

The Metaobjects plugin is going to become a jQuery official plugin, starting from the next jQuery 1.1 release, due out in a week or so. Meanwhile I’ve come up with some improvements that I’m going to share with you, releasing a new version of Metaobjects.

Changes

• Added a new option for selecting the metaobjects to process. The option name is “selector” and its value is a jQuery selector, which defaults to “object.metaobject”, i.e. an OBJECT element with a ‘metaobject’ class (the metaobject definition).

Example: process metaobjects selected by “object.bar”

$.metaobjects({selector: 'object.bar'});

• Added the concept of metaparam for configuring options local to a metaobject. If a PARAM element is given the ‘metaparam’ id, then it is treated as a configuration element, not a metadata element. Either one or none of the PARAM elements can be a metaparam. Its name is needed but not used. A good choice could be ‘options’ or ‘configuration’, anyway the ‘metaparam’ id garantees that it won’t clash with a metadata name you might need.
• Fixed a bug that didn’t allow metaobjects to add metadata to elements without a closing tag, like images (thanks to John Resig for pointing it out). Now this is possible by means of the ‘target’ metaparam option, whose value is a jQuery selector, which defaults to the parent of the metaobject. The selector takes the document as its context.

Example: add this metadata to all the elements selected by “img.foo”

<div><object class="metaobject bar">
	<param name='options' value='{target: "img.foo"}' id='metaparam' />
	<param name='title'   value='"What a Foo!"' />
</object></div>

Code of Metaobjects 1.1

/* 
=============================================================================== 
Metaobjects is a jQuery plugin for setting properties of DOM elements  by means 
of metaobjects (OBJECT elements with a 'metaobject' class) 
...............................................................................                                                
                                               Copyright 2007 / Andrea Ercolino 
------------------------------------------------------------------------------- 
LICENSE: http://www.opensource.org/licenses/mit-license.php UPDATES: 
http://noteslog.com/metaobjects/ 
=============================================================================== 
*/

/** 
 * The metadata is added to the XHTML page by means of metaobjects whose PARAM  
 * elements define name/value pairs. The given 'value' attribute is evaluated and  
 * added to the metaobject's parent as a property with the given 'name' attribute.  
 * Finally the metaobject is removed from the DOM. 
 * 
 * Is possible to configure the target of a metaobject by means of a metaparam, 
 * i.e. a PARAM element with a 'metaparam' id, (one for each metaobject). The name 
 * of the metaparam is required, but currently not used, so it can be anything not 
 * null, like 'options'. The value of the metaparam must be an object like this: 
 * {target: selector}. The selector is a jQuery selector used for finding the 
 * target inside the document. For example this is used for targeting all the 
 * images in the current document
 * 
 * <param id='metaparam' name='options' value='{target: "img"}'>
 *  
 * @signature 
 * |* jQuery *| $.metaobjects(  
 *   |* Object *| options = { 
 *     |* Element *| context: document,  
 *     |* Boolean *|   clean: true,
 *     |* String *| selector: "object.metaobject" 
 *   }  
 * ) 
 * 
 * @type  
 *   jQuery 
 * @name 
 *   $.metaobjects 
 * @param 
 *   Object options = {context: document, clean: true, selector: "object.metaobject"} 
 * @option  
 *     Element context The context where the metaobjects are 
 * @option  
 *     Boolean   clean True means 'remove metaobjects after processing' 
 * @option  
 *     String selector The jQuery selector used for finding metaobjects to process
 * @cat  
 *   Plugins/Metadata 
 * 
 * @example  
 *   $.metaobjects(); 
 * @desc  
 *   load meta data from all of the meta objects in the document and remove them 
 *  
 * @before  
 * <html><head><title>Hi There</title> 
 * ... 
 * <script type="text/javascript"> 
 * $( function() {  
 *   $.metaobjects();  
 *   var p1 = $('#one')[0]; 
 *   $( 'body' ) 
 *     .append(  
 *         '<p>'  
 *       + 'width = ' + p1.meta_size.width 
 *       + '<br />' 
 *       + 'height = ' + p1.meta_size.height 
 *       + '</p>' 
 *     ); 
 * } ); 
 * </script> 
 * </head><body> 
 * <p id="one"> 
 *   <object class="metaobject"> 
 *     <param name  = 'meta_size'  
 *            value = '{ width: 400, height: "auto" }' /> 
 *     <param name  = 'title'  
 *            value = 'document.title' /> 
 *   </object> 
 *   Hello World 
 * </p> 
 * </body></html> 
 *  
 * @after 
 * <html><head><title>Hi There</title> 
 * ... 
 * <script type="text/javascript"> 
 * ... 
 * </script> 
 * </head><body> 
 * <p id="one" title="Hi There"> 
 *   Hello World 
 * </p> 
 * <p> 
 * width = 400 
 * <br/> 
 * height = auto 
 * </p> 
 * </body></html> 
 *  
 * @author Andrea Ercolino (http://noteslog.com/) 
 * @version 1.1  
 */ 

( function($) {
	$.metaobjects = function( options ) {

		function getParam( elem ) {
			var $param = $( elem );
			var pName = $param.attr( 'name' );
			if ( '' == pName) return null;
			var pValue = $param.attr( 'value' );
			var data;
			eval( 'data = ' + pValue + ';' );
			return { name: pName, value: data };
		}

		var global_settings = { 
			  context: document
			, clean: true
			, selector: 'object.metaobject' 
		};
		$.extend( global_settings, options );
		var $metaobjects = $( global_settings.selector, global_settings.context );
		$metaobjects.each( function() {
			var settings = {};
			$( '> param#metaparam', this )
				.each( function() {

					var p = getParam( this );
					if( ! p ) return;
					$.extend( settings, p.value );

				} );
			var $target;
			if( settings.target ) {
				$target = $( settings.target );
				if( 0 == $target.length ) {
					return;
				}
			}
			else {
				$target = $( this.parentNode );
			}
			$( '> param', this )
				.not( '#metaparam' )
				.each( function() {
				
					var p = getParam( this ); 
					if( ! p ) return;
					$.map( $target.get(), function( elem ) {
						elem[ p.name ] = p.value;
						return elem;
					} );

				} );
			if( global_settings.clean ) {
				$( this ).remove();
			}
		} );
		return $metaobjects;
	} 
} ) ( jQuery );

Tests

These tests show what happens when the metaobjects() function is called with different options on the same page. (only the name of the file changes)

• test.hml
• test1.hml
• test2.hml
• test3.hml

XHTML page

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html><head><title>Hi There</title>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<script type="text/javascript" src="jquery-891.pack.js"></script>
<script type="text/javascript" src="metaobjects.js"></script>
<script type="text/javascript" src="setup.js"></script>
<style type="text/css">
p#comment {
	border: 1px dashed silver;
	padding: 10px;
}
</style>
</head><body>

<p id="one">
	<object class="metaobject">
		<param name='meta_size' value='{ width: 400, height: "auto" }' />
		<param name='title'     value='document.title' />
	</object>
	Hello World
</p>

<p><img class="foo" src="jquery-icon.png" alt="jquery icon" /></p>

<p id="two">
	<object class="metaobject bar">
		<param name='meta_size' value='{ width: "auto", height: 300 }' />
		<param name='title'     value='"Goodbye!"' />
	</object>
	See you soon
</p>

<div><object class="metaobject bar">
	<param name='options' value='{target: "img.foo"}' id='metaparam' />
	<param name='title'   value='"What a Foo!"' />
</object></div>

<p id="comment"></p>

<p>
	<a href="http://validator.w3.org/check?uri=referer"><img
		src="http://www.w3.org/Icons/valid-xhtml10"
		alt="Valid XHTML 1.0 Strict" height="31" width="88" /></a>
</p>

</body></html>

setup.js

$( function() { 
	var loc = document.location.href;
	$( '#comment' ).html( "what happens if $.metaobjects() is not called" );

	if( loc.indexOf( "test1.html" ) >= 0 ) {
		$( '#comment' ).html( "what happens after calling: $.metaobjects()" );
		$.metaobjects();
//		$.metaobjects({selector: 'object.bar'});
//		$.metaobjects({clean: false}).hide(); 
		var p1 = $('#one')[0];
		var p2 = $('#two')[0];
		$( 'body' )
			.append( '<p>' + 'width = ' + p1.meta_size.width + '<br />'
				+ 'height = ' + p1.meta_size.height + '</p>'
			)
			.append( '<p>' + 'width = ' + p2.meta_size.width + '<br />'
				+ 'height = ' + p2.meta_size.height + '</p>'
			)
		;
	}

	if( loc.indexOf( "test2.html" ) >= 0 ) {
		$( '#comment' ).html( "what happens after calling: $.metaobjects({selector: 'object.bar'});" );
//		$.metaobjects();
		$.metaobjects({selector: 'object.bar'});
//		$.metaobjects({clean: false}).hide(); 
		var p1 = $('#one')[0];
		var p2 = $('#two')[0];
		$( 'body' )
//			.append( '<p>' + 'width = ' + p1.meta_size.width + '<br />'
//				+ 'height = ' + p1.meta_size.height + '</p>'
//			)
			.append( '<p>' + 'width = ' + p2.meta_size.width + '<br />'
				+ 'height = ' + p2.meta_size.height + '</p>'
			)
		;
	}

	if( loc.indexOf( "test3.html" ) >= 0 ) {
		$( '#comment' ).html( "what happens after calling: $.metaobjects({clean: false}).hide();" );
//		$.metaobjects();
//		$.metaobjects({selector: 'object.bar'});
		$.metaobjects({clean: false}).hide(); 
		var p1 = $('#one')[0];
		var p2 = $('#two')[0];
		$( 'body' )
			.append( '<p>' + 'width = ' + p1.meta_size.width + '<br />'
				+ 'height = ' + p1.meta_size.height + '</p>'
			)
			.append( '<p>' + 'width = ' + p2.meta_size.width + '<br />'
				+ 'height = ' + p2.meta_size.height + '</p>'
			)
		;
	}


} );

Metaobjects is a jQuery plugin for setting properties of DOM elements by means of metaobjects (OBJECT elements with a ‘metaobject’ class).

Metadata plugin

There is an official Metadata plugin which lets you add metadata to elements by means of three alternative methods, always providing a JSON object to plug the data in:

Class attribute

<p id="one" class="some_class {width: 400, height: 'auto'}">
	Hello World
</p>

Custom attribute

<p id="one" class="some_class" data="{width: 400, height: 'auto'}">
	Hello World
</p>

Element content

<p id="one" class="some_class">
	<script>
		{width: 400, height: 'auto'}
	</script>
	Hello World
</p>

Access

To access a piece of metadata, you write something like this

$( function() { 
	var p1 = $('#one')[0];
	$( 'body' )
		.append( 
			  '<p>' 
			+ 'width = ' + p1.width
			+ '<br />'
			+ 'height = ' + p1.height
			+ '</p>'
		);
} );

Drawbacks

Each method available in the Metadata plugin has a drawback.

1. The ‘class attribute’ method may generate a conflict with an existing class declaration. In fact any word in any position inside the JSON object (be it the name or value of a JSON property it doesn’t matter) is treated by the browser as a class name. A careful wording mitigates the problem, though. Instead of { a : “b” }, which could clash with an ‘a’ class, you write { a: “b” }. But if you need { a: “b is a char” }, this method is not safe, because it can clash with an ‘a’ and an ‘is’ classes.
2. The ‘custom attribute’ method generates markup which is not valid XHTML, unless you use an attribute which is defined for the element, but in that case you are exposed to any sort of clashes.
3. The ‘element content’ method is easily used with a SCRIPT element, because its content stays automatically hidden, but it can clash with your regular scripts. So it should be used with an element like a SPAN whose style be ‘display:none’, but you must remember to add a class or an inline style to each. Another problem is the DOM pollution: if you use this feature frequently then your meta element is like spam for your DOM, you simply cannot take care of all of them.

Metaobjects plugin

My metaobjects.js plugin tries to solve all those problems introducing metaobjects, i.e. OBJECT elements with a ‘metaobject’ class.

The metadata is added to the XHTML page by means of metaobjects whose PARAM elements define name/value pairs. The given ‘value’ attribute is evaluated and added to the metaobject’s parent as a property with the given ‘name’ attribute. Finally the metaobject is removed from the DOM.

One of the best positions to place the call to the metaobjects() function is inside the jQuery “document ready” setup, possibly before any use of a clean DOM.

Exampe 1

Here is how you make jQuery load metadata and clean the DOM afterwards

$( function() { 
	$.metaobjects(); 
... 
} );

Before executing $.metaobjects()

<html><head><title>Hi There</title>
...
</head><body>
<p id="one">
	<object class="metaobject">
	<param   name='meta_size' 
		value='{ width: 400, height: "auto" }' />
	<param   name='title' 
		value='document.title' />
	</object>
	Hello World
</p>
</body></html>

After executing $.metaobjects()

<html><head><title>Hi There</title>
...
</head><body>
<p id="one" title="Hi There">
	Hello World
</p>
</body></html>

Access

To access a piece of metadata, you write something like this

$( function() { 
	var p1 = $('#one')[0];
	$( 'body' )
		.append( 
			  '<p>' 
			+ 'width = ' + p1.meta_size.width
			+ '<br />'
			+ 'height = ' + p1.meta_size.height
			+ '</p>'
		);
} );

Signature

/* jQuery */ $.metaobjects( 
	/* Object */ options = {
		/* Element */ context: document, 
		/* Boolean */ clean: true
	} 
)

The metaobjects() function gets a JSON options argument, with members context and clean. context is a DOM element whose metaobjects you want to process. clean is a boolean which tells wether the metaobjects are to be removed (true) or not (false). options is an optional argument and it defaults to { context: document, clean: true }

The metaobjects() function returns an array containing processed metaobjects (DOM elements) belonging to context. If clean was true, then the metaobjects returned have been removed from the DOM. Else if clean was false, you have a chance to hide() them (e.g. if you didn’t add a CSS definition like “.metaobject {display: none;}”)

Example 2

Here is how you make jQuery load metadata without cleaning the DOM afterwards. In this case you also hide() the objects (in IE you need to, but in FF they’re already hidden)

$( function() { 
	$.metaobjects( {clean: false} ).hide(); 
... 
} );

Code of Metaobjects 1.0

There is a bug (#750) in jQuery 1.0.4 (Rev 696) that makes this plugin not usable. I’ve found a simple fix, though.

Find the following snippet in the source (lines 49-56)

// See if an extra function was provided
	var fn = arguments[ arguments.length - 1 ];

	// If so, execute it in context
	if ( fn && typeof fn == "function" )
		this.each(fn);

	return this;

and make it like this one

// See if an extra function was provided
	var fn = arguments[ arguments.length - 1 ];

	// If so, execute it in context
	if ( fn && typeof fn == "function" && fn.nodeType == undefined )
		this.each(fn);

	return this;