@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 events object, which is responsible for all interactions with the markupViewer.

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
rect	trigger	activate-rect-tool
rect	subscribe	finish-rect-tool

Example

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

const options = {
  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.events.subscribe('finish-rect-tool', rectCB);

// Activate the rect tool
// Can take an options object as an optional second parameter
markupViewer.events.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 following events:

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

Example: setting color of shape

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

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

const markupViewer = new MarkupViewer(options);

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

// --------

// Alternatively, properties can be set after a tool is activated
markupViewer.events.trigger('activate-rect-tool');
markupViewer.events.trigger('update-attributes', {
  color: '#00FF00',
  opacity: 0.5,
  width: 4,
});