VisualEditor/API/Data Model/Annotations

ve.api.registerAnnotation( key, descriptor )

Register an annotation in VisualEditor.

{String} key

Has to be globally unique for all annotations, tag names etc. No hierarchy is enforced although naming conventions encourage usage of the slash character to group related annotations (for readability only) such as textStyle/bold.

{Object} descriptor

Describes the annotation. Requires the following three properties:

• {Object} match: This object is used to determine whether a given HTMLElement should be represented by this annotation (for more detail on annotation matching, see matchElement()). Must have one or more of the following:
  • {String} tag: A lowercase HTMLElement node name. Omit this property if it can match multiple kinds of elements (including if it may match all html elements), in that case at least one of the next two properties must be included.
  • {String} rdfaType: Filters by one of the (space-separated) values in txhe RDFa attributes of the HTMLElement (usually the rel attributes @TODO: Which else, when? See Parsoid/RDFa vocabulary.)
  • {Function( HTMLElement )} test Should return Boolean true or false.
• {Object|Function( HTMLElement )} annotationData [optional]: Object (or function returning an object) with annotation data to be kept about this annotation in the linear model. Any information that is needed to understand or manipulate the annotation must be extracted at this point as no access to the HTML element will be given during the editing process.
• {Object|Function( annotationData)} html: When converting the linear model back to HTML, this object (or the object returned by this function) is used to create an HTML element from the annotation. If the annotation was originally created from an HTML element, the attributes will be based on the original element's attributes, and any attributes specified in 'attributes' below will override these. To explicitly remove an attribute, set it to undefined.
  • {String} tag: Lowercase HTML element node name.
  • {Object} attributes [optional]: Object with attributes and their values.
• {Object|Function( annotationData, text)} renderHtml [optional] If the HTML rendering in the editor should be different from the HTML output, this property can be used to override it. This object (or object returned by this function) has the same behavior and properties as 'html' above. If it's omitted, the rules in 'html' will be used.

Examples

Adding support for bold

ve.api.registerAnnotation( 'textStyle/bold', {
    match: {
        tag: 'b',
    },
    html: {
        tag: 'b'
    }
} );

Adding support for mailto links

ve.api.registerAnnotation( 'link/mailto', {
    match: {
        tag: 'a',
        test: function ( element ) {
            return element.getAttribute( 'href' ).match( /^mailto:/ );
        }
    },
    annotationData: function ( element ) {
        return {
            email: decodeURLComponent( element.getAttribute( 'href' ).substr( 7 ) )
        };
    },
    html: function ( annotationData ) {
        return {
            tag: 'a',
            attributes: {
                href: 'mailto:' + encodeURLComponent( annotationData.email ),
                title: annotationData.email
            }
        };
    }
} );