HTMLPin

You can use Contextual Comments to embed a customizable commenting experience into your page, enabling people to collaborate. To add the component to an HTML page, you’ll need the HTMLPin adapter.

HTMLPin vs CanvasPin

When utilizing the HTMLPin adapter, the Comment Pins will only be able to be placed on the HTML elements that have the data-superviz-id attribute. The value of this attribute will be used to identify the element and its position on the page, meaning that it should be unique and persist on the page. You can also use the dataAttributeValueFilters option to filter what elements should not be able to receive a Comment Pin.

When utilizing the CanvasPin adapter, the Comment Pins can be placed anywhere on the canvas, containing or not an element for it, meaning that the position of the Comment Pins will be relative to the canvas, and not to the HTML elements.

Before we start

It is important to initialize a room with a defined name and ID for the participant and the group, as it will be used to store the comment data on our servers.

How to use it

When using the HTMLPin adapter, you need to pass, as a parameter in the constructor, the HTML element ID that wrappers the elements where comments can be added, and, optionally, options about the adapter behavior. With that, participants will be able to place a Comment Pin on any element that has the data-superviz-id attribute. The value of this attribute will be used to identify the element and its position on the page, meaning that it should be unique and persist on the page.

After initializing, you can add the adapter to the Contextual Comments passing it as a parameter in its constructor, enabling the Contextual Comments for HTML. Here is how to do it:

<div id="my-id" width="540" height="540">
	<p data-superviz-id="23">Paragraph that can have a comment</p>
	<p data-superviz-id="42">Another paragraph that can have a comment</p>
	<p>Paragraph that won't be able to receive a comment</p>
</div>

import { Comments, HTMLPin } from '@superviz/sdk/lib/components';

// Initializing the Adapter with the HTML element ID 
const pinAdapter = new HTMLPin("my-id", {
	dataAttributeName: "data-comment-id",
	dataAttributeValueFilters: [/.*null-(target|source)$/]
});

// Initializing the Comments component with the adapter created
const comments = new Comments(pinAdapter);

// Adding the component to the already initialized room. 
room.addComponent(comments); 

Properties

See below the parameters to use in the constructor of the HTMLPin:

Name	Type	Description
elementId	string	Required. Specifies the id of the HTML element that wrappers the elements where comments can be added.
options	HTMLPinOptions	Optional. Specifies the settings for the adapter.

Recommendations for use

When the adapter is initialized, it will look for all elements that have the data-superviz-id attribute and add a Comment Pin to them. The value of this attribute will be used to identify the element and with that, the position on the page, meaning that it should be unique and persist on the page.

Please note, that the element should not have the overflow: hidden property, as it can cut some parts of the Comment Pins or the input.

For a better experience, when using options to resize the element, the adapter will resize the Comment Pins proportionally to the previously defined position. For example, if the element has 100px by 100px and the participant places a Comment Pin at (80, 35), if the element is resized to 1000px by 1000px, the Comment Pin will be placed at (800, 350).

Types Definition

HTMLPinOptions

Type: object

An object describing the configuration for the adapter.

Name	Type	Description
dataAttributeName	string	Use this property to change the data attribute used to locate the elements that can receive a comment pin. The value of this attribute should be unique and persist on the page. Default: data-superviz-id.
dataAttributeValueFilters	RegExp[]	This Regex array is used to filter what elements should not be able to receive a comment pin.

Example:

{
	dataAttributeName: "data-comment-id",
	dataAttributeValueFilters: [/.*null-(target|source)$/]
}