@procore/markup-viewer

Markup Viewer

Getting Started

Installation

npm i -S @procore/markup-viewer

Importing

// index.js
import MarkupViewer, { tools } from '@procore/markup-viewer';

Usage

const markupViewer = new MarkupViewer(options);

Creating a new instance of MarkupViewer adds all of the DOM elements needed to display the viewer on the page.

Options[Object]:

Keys:

• tools[object] - pass in the tools that should be available to in the markupViewer
• initialHtmlTextt[string] - A valid HTML string, representing the page to be shown

Events

An instance of MarkupViewer exposes the following methods, which ar responsible for all interactions with the markupViewer.

• on(eventKey, callback)

• off(eventKey, callback)

• trigger(eventKey, callbackArg)

By default, a set of events are automatically created for each tool that is passed in, allowing the tools to be activated/deactivated by triggering those events.

For tools, the event-names follow the following pattern:

original-key	action	event-key	example usage
rect	trigger	activate-rect-tool	markupViewer.trigger('activate-rect-tool', options)
rect	subscribe	draw-rect-complete	markupViewer.on('draw-rect-complete', callback)
rect	subscribe	draw-complete	markupViewer.on('draw-complete', callback)

Example

// index.js
import MarkupViewer, { tools } from '@procore/markup-viewer';

const options = {
  tools: {
    rect: tools.rect,
  },
};

const markupViewer = new MarkupViewer(options);

// Function to be called after the shape is drawn
//  Payload contains: { e: last mouseEvent, svg: string representing the shape }
const rectCB = payload => console.log(payload);

// Subscribe to the rect tool
markupViewer.on('draw-complete', rectCB);

// Activate the rect tool
// Can take an options object as an optional second parameter
markupViewer.trigger('activate-rect-tool');

Tools

The following tools are included to be used out of the box:

• rect
• freehand
• selection

You can also create your own tools, either by extending ClickDrag, or by using ClickDrag as a template for your own use case.

When activated, a new instance of a tool is constructed with the following arguments:

• viewer
• events
• options (user-defined)

Attributes

When activated, rect and freehand will respond to the update-attributes event:

markupViewer.trigger('update-attributes', {
  fill: '#00FF00',
  stroke: '#00FF00',
  'fill-opacity': 0.5,
  'stroke-width': 4,
});

Example: setting color of shape

import MarkupViewer, { tools } from '@procore/markup-viewer';

const options = {
  tools: {
    rect: tools.rect,
  },
};

const markupViewer = new MarkupViewer(options);

// Properties can be passed in when the tool is activated
markupViewer.trigger('activate-rect-tool', {
  fill: '#00FF00',
  stroke: '#00FF00',
  'fill-opacity': 0.5,
  'stroke-width': 4,
}));

// --------

// Alternatively, properties can be set after a tool is activated
markupViewer.trigger('activate-rect-tool');
markupViewer.trigger('update-attributes', {
  fill: '#FF0000',
  stroke: '#FF0000',
}));