buzzfeed/annotator

Adds interactive annotations to images

annotator

Got an image you want to point details out on? annotator creates embeddable HTML to help users dive in to details on a document. Here's an example.

It consists of a builder and an engine. The builder creates embeds, the engine renders embeds on to the page.

get started in 30 seconds

I wish to annotate an image and generate an embed

The builder is located at ./builder/index.html.

Please note: You will need to host dist/annotator.min.js yourself before putting an embed live. Read on for how to do that...

I wish to get the annotator engine working for our organisation

Get the latest version of yarn (0.21+): https://yarnpkg.com/en/

Then just run yarn in the repository folder.

This will grab the packages it needs, then use grunt to build the distributable engine. Once that's done, it'll watch for changes in engine/, rebuilding when it sees them.

The two main files to modify are engine/js/annotator.js and engine/sass/annotator.scss. It will build to the single file dist/annotator.min.js, which you can then upload to your own infrastructure.

We would recommend at minimum changing the following to your requirements:

• builder/builder-config.js to point to your distributable
• engine/sass/annotator.sass to meet your own styling requirements
• engine/js/plugins/ to match your environment - analytics, image hosting, etc
• We use the <!-- UKNF --> tag to mark our embeds as special in the BuzzFeed CMS. You probably won't need this tag, so feel free to remove it.

Be aware: annotator will add the following to the global scope of your page.

• Styling which is applied to page objects with a parent class of .annotated_media
• window.annotate_media and window.annotate_tools are new JS globals which may be called

annotator is powered primarily by a cut-down version of jQuery.

annotator's Issues

Ability to edit the input image to highlight sections before adding annotation markers

Multi-page builder sessions

For when a set of documents, or one large document, all lands at once

It's currently difficult to determine which version is being served

Add a header with the last build date/time on it?

Add line width (thickness) as a configurable item

In both the engine and the builder.

Support for an image hosting step

Ideally as a plugin of some kind.

BuzzFeed supports image upload as a service, and others will too; do it in as unopinionated way as possible.

Add "appear at top" and "appear at bottom" support, so not all annotations have to appear below

In both the engine and the builder.

Ability to edit an entire existing embed

Paste in the builder, edit it, re-publish it.

Ability to export all text from an embed, for sub-editing purposes

Which could then be pasted in to Google Docs, Word, etc.

Multi-embed problems

On slow networks, loading out-of-order occurs. Going to check for .last() and similar suspects not being bounded by their parent container

Basic simple HTML support in the "content" box

In the builder. Much like this issue submission screen, we could do it via markdown or HTML.

Extra annotation styles

• Squares/rectangles
• Highlighter
• etc.

Line Width should probably be percentage-based with a pixel minimum, like all other measurements