@procore/markup-viewer

Markup Viewer

Getting Started

Installation

npm i -S @procore/markup-viewer

Importing

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

Usage

const options = { tools, htmlText: '<div></div>' };
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 keys are exported as constants from MarkupViewer.

• TRIGGER_CONSTANTS
  • Use these when to tell markupViewer what to do.
• EVENT_CONSTANTS
  • Use these for listening for information from markupViewer

Every constant in TRIGGER_CONSTANTS has a pair in EVENT_CONSTANTS to be used as an acknowledgement or to respond to updated data.

Example

// index.js
import MarkupViewer, {
  tools,
  EVENT_CONSTANTS,
  TRIGGER_CONSTANTS,
} 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(EVENT_CONSTANTS.DRAW_COMPLETE, rectCB);

// Activate the rect tool
// Can take an options object as an optional second parameter
markupViewer.trigger(TRIGGER_CONSTANTS.SET_ACTIVE_TOOL, { toolKey: 'rect' });

Later:

// Clean up subscription if you are done with it
markupViewer.off(EVENT_CONSTANTS.DRAW_COMPLETE, rectCB);

Working with Redux

For convenience, EVENT_CONSTANTS contains a super-listener for subscribing to all markupViewer events. When markupViewer is triggered, two events will be broadcast. EVENT_CONSTANTS.MARKUP_VIEWER_EVENTS will pass an object formatted like a Redux action to the provided callback. The type will be the specific event, and the payload will be the same payload that would be received for the individual event.

Subscriptions/listeners need to be set up before an event is triggered. When using Redux, it is typically easier to set up a single listener to EVENT_CONSTANTS.MARKUP_VIEWER_EVENT right when an app starts.

The following is an example of two different options for listening to events:

// Subscribe just to individual event
markupViewer.on(EVENT_CONSTANTS.SELECT_TOOL, payload => console.log(payload));
// When triggered, will log: { toolKey: 'rect }

// Subscribe to all markupViewer events
markupViewer.on(EVENT_CONSTANTS.MARKUP_VIEWER_EVENT, ({ type, payload }) =>
  console.log({ type, payload })
);
// When triggered, will log: { type: EVENT_CONSTANTS.SELECT_TOOL, payload: { toolKey: 'rect } }

// Triggers both of the above listeners.
markupViewer.trigger(TRIGGER_CONSTANTS.SELECT_TOOL, { toolKey: 'rect' });

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 TRIGGER_CONSTANTS.UPDATE_ATTRIBUTES event:

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

Example: setting color of shape

import MarkupViewer, { tools, EVENT_CONSTANTS, TRIGGER_CONSTANTS } 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(TRIGGER_CONSTANTS.SET_ACTIVE_TOOL, {
  toolKey: 'rect',
  options: {
    fill: '#00FF00',
    stroke: '#00FF00',
    'fill-opacity': 0.5,
    'stroke-width': 4,
  }
);

// --------

// Alternatively, properties can be set after a tool is activated
markupViewer.trigger(TRIGGER_CONSTANTS.SET_ACTIVE_TOOL, { toolKey: 'rect' });
markupViewer.trigger(TRIGGER_CONSTANTS.UPDATE_ATTRIBUTES, {
  fill: '#FF0000',
  stroke: '#FF0000',
});