New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More
Socket
Sign inDemoInstall
Socket

@procore/markup-viewer

Package Overview
Dependencies
Maintainers
203
Versions
282
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@procore/markup-viewer

Extendable document viewer that handles the logic of creating/editing/viewing markup.

  • 3.0.1
  • unpublished
  • latest
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
0
Maintainers
203
Weekly downloads
 
Created
Source

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
}

FAQs

Package last updated on 27 Jun 2023

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc