jQuery.annotate is a jQuery plugin that makes annotating selections of text a breeze. It is compatible with content housed within iframes and block-level contentEditable elements and is fully customizable to fit the needs of most websites.
- jQuery ≥ 1.6.0
- rangy
- rangy cssClassApplier module
Place the jquery.annotate.js and its dependencies in your javascript directory. Place the jquery.annotate.css in your stylesheets directory.
<head>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
<script src="rangy-core.js"></script>
<script src="rangy-cssclassapplier.js"></script>
<script src="jquery.annotate.js"></script>
<link rel="stylesheet" type="text/css" href="jquery.annotate.css">
</head>Initialize jQuery.annotate on the area to be annotated
options = {
ignore_warnings: false,
dialog: {
"class": "",
tag_name: "div",
offset_amount: 10,
position: "top",
build_on_select: true,
template: dialog_html_string,
beforeCreate: beforeCreateDialog,
create: createDialog,
afterCreate: afterCreateDialog,
beforeCancel: beforeCancelDialog,
afterCancel: afterCancelDialog
},
annotation: {
"class": "",
offset_amount: 10,
position: "top",
tag_name: "div",
template: annotation_html_string,
container: $("body"),
create: createAnnotation,
update: updateAnnotation,
beforeRender: beforeRenderAnnotation,
render: renderAnnotation,
afterRender: afterRenderAnnotation,
"delete": deleteAnnotation,
trigger_type: "click",
onTrigger: displayAnnotation,
offTrigger: hideAnnotation,
existing_data: getAnnotations,
include_time: false,
render_from_marks: true
},
article: {
update: updateArticle
},
mark: {
trigger_type: "click",
onTrigger: highlightMark,
offTrigger: unhighlightMark
}
};
$(article).annotate(options);Note: This element is assumed to include only the article and all changes to this area will be saved.
Build: Mark text and render the dialog to allow user to enter annotation contents:
$(article).annotate('build');Cancel: Remove the dialog and temporary marks from the DOM
$(article).annotate('cancel');Select: Select marks and/or annotations by annotate_id. tag_name is optional
tag_name = 'mark'
$(article).annotate('select', annotate_id, tag_name);Associated: When a mark is passed, select associated annotation and vice versa
$annotation = $(article).annotate('associated', $mark);
$marks = $(article).annotate('associated', $annotation);Remove: Remove annotation and associated mark from DOM by either passing a mark/annotation jQuery object or the annotate_id. Calls annotation.delete() to permanently destroy record
$mark = $('mark:first')
$(article).annotate('remove', $mark);
annotate_id = $mark.data('annotate-id');
$(article).annotate('remove', annotate_id);Removeall: Remove all marks and associated annotations from DOM and call annotation.delete()
$(article).annotate('removeall');Destroy: Unbind all events, hide marks, and remove annotations from the DOM (however, they will remain in the database)
$(article).annotate('destroy');Position: Position an annotation or dialog in relation to its associated mark. settings are optional.
$annotation = $('.annotate-annotation:first');
settings = {
offset_amount: 10,
direction: 'bottom'
};
$(article).annotate('position', $annotation, settings);Revert: Re-render an annotation (to cancel editing) by either passing a mark/annotation jQuery object or the annotate_id
$mark = $('mark:first');
$(article).annotate('revert', $mark);
annotate_id = $mark.data('annotate-id');
$(article).annotate('revert', annotate_id);Type: Boolean
Default: false
Determines whether warnings will be displayed in the console
Type: String
Default: ''
Classes for the dialog element (in addition to .annotate-dialog), separated by spaces
Type: String
Default: 'div'
Specifies which type of tag the dialog template will be wrapped in
Type: Integer
Default: 10
Amount of pixels between text and dialog, or pixels between document edge and dialog depending on the position attribute
Type: String
Options: 'top', 'bottom', 'left', 'right', null
Default: 'top'
float popup left/right, or hover above/below selected text
Type: Boolean
Default: true
Specifies whether .annnotate('build') is triggered when using the mouse to select text exclusively within the annotatable element
Type: String
innerHTML template for annotation dialog, should contain a <form> element
Arguments: none
Called before dialog is rendered. Also acts as validation. If false is returned, then annotation.create() will not be called
Arguments: none
Render dialog into DOM, overrides default functionality. Element should contain a <form> element. Function must return the dialog jQuery object.
Arguments: $dialog
Called after dialog is rendered
Arguments: $dialog
Called before .annotate('cancel')
Arguments: none
Called after .annotate('cancel')
Type: String
Default: ''
Classes for the annotation element (in addition to .annotate-annotation), separated by spaces
Type: String
Default: 'div'
Specifies which type of tag the annotation template will be wrapped in
Type: Integer
Default: 10
Amount of pixels between text and annotation, or pixels between document edge and annotation depending on the position attribute
Type: String
Options: 'top', 'bottom', 'left', 'right', null
Default: 'top'
float popup left/right, or hover above/below selected text
Type: String
innerHTML template for annotation, should contain a <form> element
Type: jQuery object
Default: $('body')
Where to insert rendered annotations when annotation.position is null. Orphaned annotations will always be placed here
Type: String
Options: 'hover', 'click', null
Default: hover
Specifies which type of event triggers the onTrigger and offTrigger callbacks for annotation elements
Type: Boolean
Default: false
Determines whether Date.toString() will be included as part of the annotation JSON object
Type: Boolean
Default: true
Determines whether annotations are also rendered from marks in the article as a fallback on initialization
Type: Array
Default: []
Example:
[
{
annotate_id: "yIqrHKpUTTP7A3Qk",
annotate_context: "In the morning",
content: "First annotation",
annotate_editable: 1,
user: "js_dev"
}, {
annotate_id: "JPsQMk2buw8xuyPA",
annotate_context: "I want to photograph",
content: "Second annotation",
annotate_editable: 1,
user: "js_dev"
}
]Array of annotation data in JSON format
Arguments: { annotation: {} }
Send AJAX request to post annotation to database. Must return JSON object with status == “success” or 200 if successful.
Sample Response:
{
annotation: {
annotate_id: "aX5D3as45xrj44",
annotate_context: "Part of the article.",
content: "This is an annotation.",
user: "js_dev"
},
status: "success"
}Arguments: { annotation: {} }
Send AJAX request to update annotation record in database. Must return JSON object with status equal to "success" or 200 if successful.
Sample Response:
{
annotation: {
annotate_id: "aX5D3as45xrj44",
annotate_context: "Part of the article.",
content: "This is an annotation.",
user: "js_dev"
},
status: "success"
}Arguments: { annotation: { annotate_id: "aX5D3as45xrj44" } }
Called before annotation.render()
Arguments: { annotation: { annotate_id: "aX5D3as45xrj44" } }
Render annotation template, or error message (depending on status), overrides default functionality. Must return a jQuery object containing the annotation DOM element, otherwise the process will halt.
Arguments: $annotation
Called after annotation.render()
Arguments: [first_annotate_id, second_annotate_id]
Send AJAX request to remove annotation(s) from database. Called from .annotate('remove') and .annotate('removeall')
Arguments: $marks, $annotation
Called when user enters an annotation, depending on the trigger
Arguments: $marks, $annotation
Called when user exits an annotation, depending on the trigger
Arguments: article_html (String)
Send AJAX request to update article in database after the element is removed from DOM.
Type: String
Options: 'hover', 'click', null
Default: hover
Specifies which type of event triggers the onTrigger and offTrigger callbacks for mark elements
Arguments: $marks, $annotation
Called when user enters a mark, depending on the trigger
Arguments: $marks, $annotation
Called when user exits a mark, depending on the trigger