@procore/markup-viewer
Extendable document viewer that handles the logic of creating/editing/viewing markup.
Last updated 2 months ago by dallashall-procore .
UNLICENSED · Repository · Bugs · Original npm · Tarball · package.json
$ cnpm install @procore/markup-viewer 
SYNC missed versions from official npm registry.

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
  • stamp

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',
});

Constants for events

TRIGGER_CONSTANTS

SET_PAGE

import { TRIGGER_CONSTANTS } from '@procore/markup-viewer';

const options = { htmlText: '<div></div>' };
markupViewer.trigger(TRIGGER_CONSTANTS.SET_PAGE, options);

ZOOM_IN

import { TRIGGER_CONSTANTS } from '@procore/markup-viewer';

const zoomAmount = 0.05;
markupViewer.trigger(TRIGGER_CONSTANTS.ZOOM_IN, zoomAmount);

ZOOM_OUT

import { TRIGGER_CONSTANTS } from '@procore/markup-viewer';

const zoomAmount = 0.05;
markupViewer.trigger(TRIGGER_CONSTANTS.ZOOM_OUT, zoomAmount);

RESET_ZOOM

import { TRIGGER_CONSTANTS } from '@procore/markup-viewer';

markupViewer.trigger(TRIGGER_CONSTANTS.RESET_ZOOM);

SET_ACTIVE_TOOL

Rect

import { TRIGGER_CONSTANTS } from '@procore/markup-viewer';

const toolKey = 'rect';
const options = {
  fill: '#ff0000',
  'fill-opacity': 0.5,
  stroke: '#0000ff',
  'stroke-opacity': 1,
  'stroke-width': 4,
};
markupViewer.trigger(TRIGGER_CONSTANTS.SET_ACTIVE_TOOL, { toolKey, options });

Freehand

import { TRIGGER_CONSTANTS } from '@procore/markup-viewer';

const toolKey = 'freehand';
const options = {
  stroke: '#0000ff',
  'stroke-opacity': 1,
  'stroke-width': 4,
};
markupViewer.trigger(TRIGGER_CONSTANTS.SET_ACTIVE_TOOL, { toolKey, options });

Selection

import { TRIGGER_CONSTANTS } from '@procore/markup-viewer';

const toolKey = 'selection';
markupViewer.trigger(TRIGGER_CONSTANTS.SET_ACTIVE_TOOL, { toolKey });

Stamp

import { TRIGGER_CONSTANTS } from '@procore/markup-viewer';

const stamp = {
  url: 'someImage.svg',
  width: 100,
  height: 100,
};
const options = {
  stamp,
};
const toolKey = 'stamp';
markupViewer.trigger(TRIGGER_CONSTANTS.SET_ACTIVE_TOOL, { toolKey, options });

CANCEL_ACTIVE_TOOL

import { TRIGGER_CONSTANTS } from '@procore/markup-viewer';

markupViewer.trigger(TRIGGER_CONSTANTS.CANCEL_ACTIVE_TOOL);

UPDATE_ATTRIBUTES

Will only trigger successfully if there is an active tool that supports updating attributes (rect/freehand)

import { TRIGGER_CONSTANTS } from '@procore/markup-viewer';

const options = {
  fill: '#ff0000',
  'fill-opacity': 0.5,
  stroke: '#0000ff',
  'stroke-opacity': 1,
  'stroke-width': 4,
};
markupViewer.trigger(TRIGGER_CONSTANTS.UPDATE_ATTRIBUTES, options);

CREATE_MARKUP_ELEMENTS

Typically used for rendering a markupElement from a server-event

import { TRIGGER_CONSTANTS } from '@procore/markup-viewer';

const markupElements = [
  {
    id: 123,
    type: 'rect',
    svg: '<rect width="10" height="10" x="0" y="0"></rect>',
  },
];
markupViewer.trigger(TRIGGER_CONSTANTS.CREATE_MARKUP_ELEMENTS, markupElement);

REMOVE_MARKUP_ELEMENTS

import { TRIGGER_CONSTANTS } from '@procore/markup-viewer';

const markupElements = ['abc-123'];
markupViewer.trigger(TRIGGER_CONSTANTS.REMOVE_MARKUP_ELEMENTS, markupElements);

UPDATE_MARKUP_ELEMENTS

import { TRIGGER_CONSTANTS } from '@procore/markup-viewer';

const uuid = 'abc-123';
const svg = '<rect></rect>';
const id = 321;
markupViewer.trigger(TRIGGER_CONSTANTS.UPDATE_MARKUP_ELEMENT, [
  {
    uuid,
    svg,
    id,
  },
]);

UPDATE_SHAPE_ATTRIBUTES

import { TRIGGER_CONSTANTS } from '@procore/markup-viewer';

const markupElements = ['abc-123', 'def-456', 'ghi-789'];

const attributes = {
  fill: '#ff0000',
  'fill-opacity': 0.5,
  stroke: '#0000ff',
  'stroke-opacity': 1,
  'stroke-width': 4,
};
markupViewer.trigger(TRIGGER_CONSTANTS.UPDATE_SHAPE_ATTRIBUTES, {
  markupElements,
  attributes,
});

UPDATE_MARKUP_ELEMENT_SELECTION

import { TRIGGER_CONSTANTS } from '@procore/markup-viewer';

const markupElements = ['abc-123', 'def-456', 'ghi-789'];
markupViewer.trigger(TRIGGER_CONSTANTS, markupElements);

EVENT_CONSTANTS

SET_PAGE

import { EVENT_CONSTANTS } from '@procore/markup-viewer';
const callback = payload => console.log(payload);
markupViewer.on(EVENT_CONSTANTS.SET_PAGE, callback);

payload:

  • none

ZOOM_IN

import { EVENT_CONSTANTS } from '@procore/markup-viewer';
const callback = payload => console.log(payload);
markupViewer.on(EVENT_CONSTANTS.ZOOM_IN, callback);

payload:

{
  zoomLevel: 1.05
}

ZOOM_OUT

import { EVENT_CONSTANTS } from '@procore/markup-viewer';
const callback = payload => console.log(payload);
markupViewer.on(EVENT_CONSTANTS.ZOOM_OUT, callback);

payload:

{
  zoomLevel: 0.95
}

RESET_ZOOM

import { EVENT_CONSTANTS } from '@procore/markup-viewer';
const callback = payload => console.log(payload);
markupViewer.on(EVENT_CONSTANTS.RESET_ZOOM, callback);

payload:

{
  zoomLevel: 0.95
}


SET_ACTIVE_TOOL

import { EVENT_CONSTANTS } from '@procore/markup-viewer';
const callback = payload => console.log(payload);
markupViewer.on(EVENT_CONSTANTS.SET_ACTIVE_TOOL, callback);

payload:

{
  toolKey: 'rect',
  options
}

CANCEL_ACTIVE_TOOL

import { EVENT_CONSTANTS } from '@procore/markup-viewer';
const callback = payload => console.log(payload);
markupViewer.on(EVENT_CONSTANTS.CANCEL_ACTIVE_TOOL, callback);

payload:

  • undefined

UPDATE_ATTRIBUTES

import { EVENT_CONSTANTS } from '@procore/markup-viewer';
const callback = payload => console.log(payload);
markupViewer.on(EVENT_CONSTANTS.UPDATE_ATTRIBUTES, callback);

payload:

{
  fill: '#ff0000',
  'fill-opacity': 0.5,
  stroke: '#0000ff',
  'stroke-opacity': 1,
  'stroke-width': 4,
}


CREATE_MARKUP_ELEMENTS

import { EVENT_CONSTANTS } from '@procore/markup-viewer';
const callback = payload => console.log(payload);
markupViewer.on(EVENT_CONSTANTS.CREATE_MARKUP_ELEMENTS, callback);

payload:

[
  {
    uuid: 'abc-123',
    id: 123,
    svg: '<rect></rect>',
    type: 'rect',
    attributes: {}
  }
]

REMOVE_MARKUP_ELEMENTS

import { EVENT_CONSTANTS } from '@procore/markup-viewer';
const callback = payload => console.log(payload);
markupViewer.on(EVENT_CONSTANTS.REMOVE_MARKUP_ELEMENTS, callback);

payload:

[
 'abc-123'
]

UPDATE_MARKUP_ELEMENTS

import { EVENT_CONSTANTS } from '@procore/markup-viewer';
const callback = payload => console.log(payload);
markupViewer.on(EVENT_CONSTANTS.UPDATE_MARKUP_ELEMENTS, callback);

payload:

[
    {
      uuid: 'abc-123',
      id: 123,
      svg: '<rect></rect>',
      type: 'rect',
      attributes: {}
  }
]

UPDATE_SHAPE_ATTRIBUTES

import { EVENT_CONSTANTS } from '@procore/markup-viewer';
const callback = payload => console.log(payload);
markupViewer.on(EVENT_CONSTANTS.UPDATE_SHAPE_ATTRIBUTES, callback);

payload:

[
  {
    uuid: 'abc-123',
    id: 123,
    svg: '<rect></rect>',
    type: 'rect',
    attributes: {}
  }
]


UPDATE_MARKUP_ELEMENT_SELECTION

import { EVENT_CONSTANTS } from '@procore/markup-viewer';
const callback = payload => console.log(payload);
markupViewer.on(EVENT_CONSTANTS.UPDATE_MARKUP_ELEMENT_SELECTION, callback);

payload:

[
  'abc-123',
  'def-456',
  'ghi-789'
]


DRAW_COMPLETE

import { EVENT_CONSTANTS } from '@procore/markup-viewer';
const callback = payload => console.log(payload);
markupViewer.on(EVENT_CONSTANTS.DRAW_COMPLETE, callback);

payload:

{
  uuid: 'abc-123',
  svg: '<rect></rect>',
  type: 'rect',
  attributes: {}
}

MARKUP_VIEWER_EVENT

This event is a 'super event'. This event is fired for every event in EVENT_CONSTANTS. Its payload is an object formatted for easy use in Redux-like environments, with type and payload keys. type will be a constant from EVENT_CONSTANTS; payload will be the associated payload listed above.

import { EVENT_CONSTANTS } from '@procore/markup-viewer';
const callback = payload => console.log(payload);
markupViewer.on(EVENT_CONSTANTS.MARKUP_VIEWER_EVENT, callback);

payload:

{
  type: EVENT_CONSTANTS.*,
  payload
}

Current Tags

151 Versions

  • 0.18.3                                ...           2 months ago
  • 0.18.3-alpha-template-field.0                                ...           2 months ago
  • 0.18.2                                ...           2 months ago
  • 0.18.1                                ...           2 months ago
  • 0.18.0                                ...           2 months ago
  • 0.18.0-event-system-upgrade.1                                ...           2 months ago
  • 0.18.0-event-system-upgrade.0                                ...           2 months ago
  • 0.17.6                                ...           3 months ago
  • 0.17.6-alpha-pan-tool-interaction-layer.1                                ...           4 months ago
  • 0.17.5                                ...           4 months ago
  • 0.17.5-alpha-duplicate-textboxes-fix.0                                ...           4 months ago
  • 0.17.5-alpha-pan-tool-interaction-layer.0                                ...           4 months ago
  • 0.17.4                                ...           4 months ago
  • 0.17.4-alpha-ie11-text-create-fail-bug                                ...           4 months ago
  • 0.17.3                                ...           5 months ago
  • 0.17.3-alpha-stamp-textbox-improvements.3                                ...           5 months ago
  • 0.17.3-alpha-stamp-textbox-improvements.2                                ...           5 months ago
  • 0.17.3-alpha-stamp-textbox-improvements.1                                ...           5 months ago
  • 0.17.2                                ...           5 months ago
  • 0.17.3-alpha-stamp-textbox-improvements.0                                ...           5 months ago
  • 0.17.2-alpha-page-safety.0                                ...           5 months ago
  • 0.17.1                                ...           5 months ago
  • 0.17.0                                ...           5 months ago
  • 1.0.0-page-mounting.3                                ...           7 months ago
  • 1.0.0-page-mounting.2                                ...           7 months ago
  • 0.16.6                                ...           7 months ago
  • 1.0.0-page-mounting.1                                ...           7 months ago
  • 0.16.5                                ...           7 months ago
  • 0.16.5-alpha-new-build.1                                ...           7 months ago
  • 0.16.5-alpha-new-build.0                                ...           7 months ago
  • 0.16.5-alpha-using-core-scripts.1                                ...           7 months ago
  • 1.0.0-page-mounting.0                                ...           7 months ago
  • 0.16.5-alpha-using-core-scripts.0                                ...           7 months ago
  • 0.16.4                                ...           7 months ago
  • 0.16.4-alpha-marching-ants-textbox-resize                                ...           7 months ago
  • 0.16.3                                ...           7 months ago
  • 0.16.2                                ...           8 months ago
  • 0.16.1-0                                ...           8 months ago
  • 0.16.1-highlight-text-2                                ...           8 months ago
  • 0.16.1-highlight-text                                ...           8 months ago
  • 0.16.1-alpha-add-configs-to-content                                ...           8 months ago
  • 0.16.0                                ...           8 months ago
  • 0.16.0-alpha-pagecontent.2                                ...           9 months ago
  • 0.15.1-0                                ...           9 months ago
  • 0.15.1-alpha-text-formatting.1                                ...           9 months ago
  • 0.15.1-alpha-text-formatting.0                                ...           9 months ago
  • 0.15.0-0                                ...           9 months ago
  • 0.15.0-alpha-iframe.3                                ...           9 months ago
  • 0.15.0-alpha-iframe.2                                ...           9 months ago
  • 0.15.0-alpha-iframe.1                                ...           9 months ago
  • 0.15.0-alpha-iframe.0                                ...           9 months ago
  • 0.14.3                                ...           10 months ago
  • 0.14.3-alpha-remove-placeholder.1                                ...           10 months ago
  • 0.14.3-alpha-remove-placeholder.0                                ...           10 months ago
  • 0.14.2-0                                ...           a year ago
  • 0.14.2-alpha-bugfix                                ...           a year ago
  • 0.14.1-0                                ...           a year ago
  • 0.14.1-alpha-add-highlight-trigger.0                                ...           a year ago
  • 0.14.0-0                                ...           a year ago
  • 0.14.0-alpha-template.4                                ...           a year ago
  • 0.14.0-alpha-template.3                                ...           a year ago
  • 0.13.4-0                                ...           a year ago
  • 0.13.4-0.alpha-set-initial-zoom                                ...           a year ago
  • 0.13.3-0                                ...           a year ago
  • 0.14.0-alpha-template.2                                ...           a year ago
  • 0.13.3-3.select-again-alpha                                ...           a year ago
  • 0.13.3-2.select-again-alpha                                ...           a year ago
  • 0.13.3-1.select-again-alpha                                ...           a year ago
  • 0.13.3-0.select-again-alpha                                ...           a year ago
  • 0.14.0-alpha-template.1                                ...           a year ago
  • 0.13.2-0                                ...           a year ago
  • 0.13.2-alpha-copy-paste.0                                ...           a year ago
  • 0.14.0-alpha-template.0                                ...           a year ago
  • 0.13.0-alpha-freehand-highlight.2                                ...           2 years ago
  • 0.13.0-alpha-freehand-highlight.1                                ...           2 years ago
  • 0.13.0-alpha-freehand-highlight.0                                ...           2 years ago
  • 0.12.8-textbox-zero-stroke-alpha.0                                ...           2 years ago
  • 0.13.1-0                                ...           a year ago
  • 0.13.1-typescript-alpha.2                                ...           2 years ago
  • 0.13.1-typescript-alpha.1                                ...           2 years ago
  • 0.13.1-typescript-alpha.0                                ...           2 years ago
  • 0.13.0-0                                ...           2 years ago
  • 0.12.13-0                                ...           2 years ago
  • 0.12.12-0                                ...           2 years ago
  • 0.12.11-0                                ...           2 years ago
  • 0.12.10-0                                ...           2 years ago
  • 0.12.10-textbox-stroke-alpha.2                                ...           2 years ago
  • 0.12.10-min-size-alpha.1                                ...           2 years ago
  • 0.12.10-min-size-alpha.0                                ...           2 years ago
  • 0.12.10-textbox-stroke-alpha.1                                ...           2 years ago
  • 0.12.9-0                                ...           2 years ago
  • 0.12.8-0                                ...           2 years ago
  • 0.12.8-selection-alpha.0                                ...           2 years ago
  • 0.12.8-cancelable-alpha.0                                ...           2 years ago
  • 0.12.7-0                                ...           2 years ago
  • 0.12.7-alpha.0                                ...           2 years ago
  • 0.12.6-0                                ...           2 years ago
  • 0.12.5-0                                ...           2 years ago
  • 0.12.5-alpha.1                                ...           2 years ago
  • 0.12.4-1                                ...           2 years ago
  • 0.12.4-alpha-click-fix.1                                ...           2 years ago
  • 0.12.4-alpha.2                                ...           2 years ago
  • 0.12.3-0                                ...           2 years ago
  • 0.12.3-alpha.1                                ...           2 years ago
  • 0.12.2-0                                ...           2 years ago
  • 0.12.1-text-edit-alpha.2                                ...           2 years ago
  • 0.12.1-0                                ...           2 years ago
  • 0.12.0-0                                ...           2 years ago
  • 0.11.2-text-edit-alpha.1                                ...           2 years ago
  • 0.11.2-placeholder-alpha                                ...           2 years ago
  • 0.12.0-cloud-alpha.1                                ...           2 years ago
  • 0.12.0-cloud-alpha.0                                ...           2 years ago
  • 0.11.1-0                                ...           2 years ago
  • 0.11.1-alpha.1                                ...           2 years ago
  • 0.11.0-0                                ...           2 years ago
  • 0.11.0-alpha.1                                ...           2 years ago
  • 0.10.1-0                                ...           2 years ago
  • 0.10.0-0                                ...           2 years ago
  • 0.9.3-0                                ...           2 years ago
  • 0.9.2-0                                ...           2 years ago
  • 0.9.1-0                                ...           2 years ago
  • 0.9.0-0                                ...           2 years ago
  • 0.8.1-0                                ...           2 years ago
  • 0.8.0-0                                ...           2 years ago
  • 0.7.0-0                                ...           2 years ago
  • 0.6.3-0                                ...           2 years ago
  • 0.6.2-1                                ...           2 years ago
  • 0.6.2-0                                ...           2 years ago
  • 0.6.1-0                                ...           2 years ago
  • 0.6.0-0                                ...           2 years ago
  • 0.5.6-alpha.3                                ...           2 years ago
  • 0.5.6-alpha.2                                ...           2 years ago
  • 0.5.6-alpha.1                                ...           2 years ago
  • 0.5.6-alpha.0                                ...           2 years ago
  • 0.5.6-0                                ...           2 years ago
  • 0.5.5-0                                ...           2 years ago
  • 0.5.4-0                                ...           2 years ago
  • 0.5.3-0                                ...           2 years ago
  • 0.5.2-1                                ...           2 years ago
  • 0.5.2-0                                ...           2 years ago
  • 0.5.1-0                                ...           2 years ago
  • 0.5.0-0                                ...           2 years ago
  • 0.4.2-0                                ...           2 years ago
  • 0.4.1-0                                ...           2 years ago
  • 0.4.0-0                                ...           2 years ago
  • 0.3.0-0                                ...           2 years ago
  • 0.2.1                                ...           2 years ago
  • 0.2.0                                ...           2 years ago
  • 0.1.2                                ...           2 years ago
  • 0.1.1                                ...           2 years ago
  • 0.1.0                                ...           2 years ago

Copyright 2014 - 2016 © taobao.org |