Posted By

kouphax on 10/25/08

Tagged

Versions (?)

Last Edited at 10/25/08 12:52pm

Statistics

Viewed 1590 times

Favorited by 1 user(s)

Related snippets

Annotations jQuery Plugin

/ Published in: JavaScript

The annotaion framework provides access to client side comment based DOM annotations. The framework does not imply any specific usage and is essentially useless on it's own. It merely provides another way to offer metadata for elements.

An annotated DOM Element is any element in the DOM preceeded by one or many comments of the form below. NB. The payload ({...}) is optional.

Highlighted TextExpand

/*---------------------------------------------------------------------------------
 *
 *  Annotations jQuery Plugin
 *
 *---------------------------------------------------------------------------------
 *
 *  The annotaion framework provides access to client side comment based DOM 
 *  annotations.  The framework does not imply any specific usage and is 
 *  essentially useless on it's own.  It merely provides another way to offer 
 *  metadata for elements.
 *
 *  An annotated DOM Element is any element in the DOM preceeded by one or many 
 *  comments of the form below.  NB. The payload ({...}) is optional.
 *
 *  
 *  <input type="text" value="test" id="textbox"/>
 *
 *  ;
 *  <input type="text" value="test" id="textbox"/>
 *
 *  -------------------------------------------------------------------------------
 *  24/10/2008 - Initial Version
 *  -------------------------------------------------------------------------------
 * 
 *///------------------------------------------------------------------------------ 
 
/*
 *  -------------------------------------------------------------------------------
 *  W A R N I N G   W A R N I N G   W A R N I N G   W A R N I N G   W A R N I N G  
 *  -------------------------------------------------------------------------------
 *
 *  XML Standards dictate that XML parsers are permitted to silently remove HTML
 *  comments before rendering the output.  It cannot be guarenteed that comments
 *  will make it into the final version of the HTML document.  All major browsers
 *  do not exhibit this behaviour.  It is simply a caveat!
 *
 */
(function($) {

/*-----------------------------------------------------------------------------
     *
     *  Annotate Function
     *
     *-----------------------------------------------------------------------------
     *
     *  Adds comment based annotations to the scoped elements.
     *
     *  @param Annotations variable number of annotations to apply
     *
     *///--------------------------------------------------------------------------     
    $.fn.annotate = function(){
        var args = arguments;
        if(args && args.length > 0){
            this.each(function(){

$el = $(this);
                var a = $el.data("annotations") || [];

$.each(args, function(){
                    $el.before("<"+"!-"+"-"+this+"-"+"-"+">");
                    
                    var ann = parse(this, prev($el[0]));                                        
                    $el.trigger("annotation:added", [$el, ann]);
                    
                    a.push(ann);
                });

$el.data("annotations",a);
            });
            return this;
        }
    }
    
    /*-----------------------------------------------------------------------------
     *
     *  Unannotate Function
     *
     *-----------------------------------------------------------------------------
     *
     *  Removes some or all of the elements annotations depending on the input
     *
     *  @param Filter representing the annotaion types to remove. Optional
     *
     *///--------------------------------------------------------------------------     
    $.fn.unannotate = function(){

var $args = arguments;
        var filter = $args && $args.length > 0;
        
        return this.each(function(){

/*-----------------------------------------------------------------------------
     *
     *  Annotations Function
     *
     *-----------------------------------------------------------------------------
     *
     *  Returns a list of annotations for this first object only.  Can be filtered 
     *  by annotation types.
     *
     *  @param Filter representing the annotaion types to collect. Optional
     *
     *///--------------------------------------------------------------------------      
    $.fn.annotations = function(){

if(this.length === 0) return null;
        
        // attempt to load annotations from cache
        var annotations = this.data("annotations");

if(!annotations){
            
            annotations = [];
            var p = prev(this[0]);
            
            while(isAnnotation(p)){
                annotations.push( parse($.trim(p.nodeValue), p) );
                p = prev(p);
            }

this.data("annotations", annotations);
        }

if(arguments.length > 0){
            var args = arguments;
            annotations = $.map(annotations, function(el){
                var found = false;
                $.each(args, function(){
                    return !(found = (el.name==this));
                });
                return found ? el : null;
            });
        }

return annotations;
    }

/*-----------------------------------------------------------------------------
     *
     *  Annotated Utility Function
     *
     *-----------------------------------------------------------------------------
     *
     *  Returns a list of all annotated elements from the root specified or the 
     *  document
     *
     *  @param Filter representing the annotaion types to collect
     *  @param Root element to look for annotations, defaults to document element
     *
     *///--------------------------------------------------------------------------      
    $.annotated = function(filter, root){

var n = $(root || document)[0];
        var v = $.trim(n.nodeValue);

if (isAnnotation(n)){
            if(filter){
                if(filter.constructor == String && (parse(v).name === filter)){
                    return [next(n,true)];
                }else if(filter.constructor == Array){
                    var found = false;
                    $.each(filter, function(){
                        return !(found = (parse(v).name === this));
                    });

return found?[next(n,true)]:[];
                }else{
                    return [];
                }
            }else{
                return [next(n,true)];
            }
        }

var children = [];

for(var m = n.firstChild; m != null; m = m.nextSibling) {
            $.each($.annotated(filter,m), function(){children.push(this)});
        }

return $(jQuery.unique(children));
    }

/*-----------------------------------------------------------------------------
     *
     *  Private Functions
     *
     *-----------------------------------------------------------------------------
     *
     *  Helper functions used through out the public API of the plugins
     *
     *///--------------------------------------------------------------------------

var NODE_COMMENT = 8;
    var NODE_TEXT    = 3;

function prev(root, skipComments){
        var ps = root ? root.previousSibling : null;        
        return (ps && (ps.nodeType === NODE_TEXT || (ps.nodeType === NODE_COMMENT && skipComments)))?prev(ps,skipComments):ps;
    }

})(jQuery);

Report this snippet Tweet

Comments

Subscribe to comments

Comment:

You need to login to post a comment.