mediawiki-extensions-Visual.../modules/ve/dm/ve.dm.Annotation.js
Trevor Parscal 8d33a3de0d Major Documentation Cleanup
* Made method descriptions imperative: "Do this" rather than "Does this"
* Changed use of "this object" to "the object" in method documentation
* Added missing documentation
* Fixed incorrect documentation
* Fixed incorrect debug method names (as in those VeDmClassName tags we add to functions so they make sense when dumped into in the console)
* Normalized use of package names throughout
* Normalized class descriptions
* Removed incorrect @abstract tags
* Added missing @method tags
* Lots of other minor cleanup

Change-Id: I4ea66a2dd107613e2ea3a5f56ff54d675d72957e
2013-01-16 15:37:59 -08:00

177 lines
5.4 KiB
JavaScript

/*!
* VisualEditor DataModel Annotation class.
*
* @copyright 2011-2012 VisualEditor Team and others; see AUTHORS.txt
* @license The MIT License (MIT); see LICENSE.txt
*/
/**
* Generic DataModel annotation.
*
* This is an abstract class, annotations should extend this and call this constructor from their
* constructor. You should not instantiate this class directly.
*
* Annotations in the linear model are instances of subclasses of this class. Subclasses are
* required to have a constructor with the same signature.
*
* this.htmlTagName and this.htmlAttributes are private to the base class, subclasses must not
* use them. Any information from the HTML element that is needed later should be extracted into
* this.data by overriding getAnnotationData(). Subclasses can read from this.data but must not
* write to it directly.
*
* TODO: Make this constructor optionally accept a data object instead of an element.
*
* @class
* @constructor
* @param {HTMLElement} [element] HTML element the annotation was converted from, if any
*/
ve.dm.Annotation = function VeDmAnnotation( element ) {
this.name = this.constructor.static.name; // Needed for proper hashing
this.data = {};
if ( element ) {
this.htmlTagName = element.nodeName.toLowerCase();
this.htmlAttributes = ve.getDomAttributes( element );
this.data = this.getAnnotationData( element );
}
};
/* Static properties */
/**
* Object containing static properties.
*
* ve#inheritClass contains special logic to make sure these properties are inherited by subclasses.
* @static
* @property
* @inheritable
*/
ve.dm.Annotation.static = {};
/**
* Symbolic name for the annotation class.
*
* Must be set to a unique string by every subclass.
*
* @static
* @property {string} [static.name=null]
* @inheritable
*/
ve.dm.Annotation.static.name = null;
/**
* Array of HTML tag names that the annotation should be a match candidate for.
*
* Empty array means none, null means any.
*
* @see ve#dm#AnnotationFactory
*
* @static
* @property {Array} static.matchTagNames
* @inheritable
*/
ve.dm.Annotation.static.matchTagNames = null;
/**
* Array of RDFa types that the annotation should be a match candidate for.
*
* Empty array means none, null means any.
*
* @see ve#dm#AnnotationFactory
*
* @static
* @property {Array} static.matchRdfaType
* @inheritable
*/
ve.dm.Annotation.static.matchRdfaTypes = null;
/**
* Optional function to determine whether the annotation should match a given element.
*
* Takes an HTMLElement and returns true or false.
*
* This function is only called if this annotation has a chance of "winning"; see
* ve.dm.AnnotationFactory for more information about annotation matching.
* If set to null, this property is ignored. Setting this to null is not the same as unconditionally
* returning true, because the presence or absence of a matchFunction affects the annotation's
* specificity.
*
* NOTE: This function is NOT a method, within this function "this" will not refer to an instance
* of this class (or to anything reasonable, for that matter).
* @static
* @property {Function} static.matchFunction
* @inheritable
*/
ve.dm.Annotation.static.matchFunction = null;
/* Methods */
/**
* Get annotation data for the linear model.
*
* Called when building a new annotation from an HTML element.
*
* This annotation data object is completely free-form. It's stored in the linear model, it can be
* manipulated by UI widgets, and you access it as this.data in toHTML() on the way out and in
* renderHTML() for rendering. It is also the ONLY data you can reliably use in those contexts, so
* any information from the HTML element that you'll need later should be extracted into the data
* object here.
*
* @method
* @param {HTMLElement} element HTML element the annotation will represent
* @returns {Object} Annotation data
*/
ve.dm.Annotation.prototype.getAnnotationData = function () {
return {};
};
/**
* Convert the annotation back to HTML for output purposes.
*
* You should only use this.data here, you cannot reliably use any of the other properties.
* The default action is to restore the original HTML element's tag name and attributes (if this
* annotation was created based on an element). If a subclass wants to do this too (this is common),
* it should call its parent's implementation first, then manipulate the return value.
*
* @method
* @returns {Object} Object with 'tag' (tag name) and 'attributes' (object with attribute key/values)
*/
ve.dm.Annotation.prototype.toHTML = function () {
return {
'tag': this.htmlTagName || '',
'attributes': this.htmlAttributes || {}
};
};
/**
* Convert the annotation to HTML for rendering purposes.
*
* By default, this just calls #toHTML, but it may be customized if the rendering should be
* different from the output.
*
* @see #toHTML
*
* @method
* @returns {Object} Object with 'tag' (tag name) and 'attributes' (object with attribute key/values)
*/
ve.dm.Annotation.prototype.renderHTML = function () {
return this.toHTML();
};
/**
* Get a hash of the annotation.
*
* This is a custom hash function for ve#getHash and should not be overridden by subclasses.
*
* @method
* @returns {string} Hash string
*/
ve.dm.Annotation.prototype.getHash = function () {
var keys = [ 'name', 'data' ], obj = {}, i;
for ( i = 0; i < keys.length; i++ ) {
if ( this[keys[i]] !== undefined ) {
obj[keys[i]] = this[keys[i]];
}
}
return ve.getHash( obj );
};