HTMLPin
Contextual Comments embeds a customizable commenting experience into your application, enabling people to collaborate in real-time and asynchronously on html
elements.
Before we start
Before utilizing the <Comments>
element, it is essential to initialize a room with a defined name and ID for the participant.
How to use it
Comments
To add contextual comments to a <html>
element, you need to add the <Comments>
component, configure position and styling, and then point it to the 'useHTMLPin' hook.
useHTMLPin
When using the useHTMLPin
hook, 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:
import { Comments, useHTMLPin } from "@superviz/react-sdk";
function Room({ participantId }) {
const { pin } = useHTMLPin({ containerId: "myContainer" });
return (
<Comments pin={pin} buttonLocation="top-right" position="left" />
);
}
export default Room;
Properties
Name | Type | Description |
---|---|---|
pin | pin | Required. Specifies the element or plugin that can receive comments. For <htmls> elements always use the useHTMLPin hook. |
position | string | Optional. Represents the position where the element with the list of comments will be placed on the page. Values are left and right Default value: left |
buttonLocation | string | Optional. Represents the position where the button to activate or deactivate the comments functionality will be placed. Values are top-left , top-right , bottom-left , bottom-right , or an HTML element id. Default value: top-left |
styles | string | Optional. CSS String that allows you to customize all elements individually. |
useComments Hook
openThreads
Type: () => void
Opens the superviz-comments section
, where you can see the list of comments and reply to them.
function Room() {
const { openThreads } = useComments();
function open() {
openThreads();
}
return <button onClick={open}>Open Threads</button>
}
closeThreads
Type: () => void
Closes the superviz-comments
section, where you can see the list of comments and reply to them.
function Room() {
const { closeThreads } = useComments();
function close() {
closeThreads();
}
return <button onClick={close}>Close Threads</button>
}
useHTMLPin Hook
Exported
pin
Type: HTMLPin | null
An HTMLPin object
function Room() {
const { pin } = useHTMLPin({ elementId: "myContainer" });
return (
<Comments pin={pin} />
);
}
destroy
Type: function
Destroy Pin object
function Room() {
const { pin, destroy } = useHTMLPin({ elementId: "myContainer" });
function destroyPin() {
destroy();
}
return (
<>
<Comments pin={pin} />
<button onclick={destroyPin}>Destroy</button>
</>
);
}
Parameters
elementId
Required. string
Specifies the parent of the HTML elements where comments can be added.
function Room({ participantId }) {
const { pin } = useHTMLPin({ containerId: "myContainer" });
return (
<Comments pin={pin} />
);
}
dataAttributeName
Optional. 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
function Room({ participantId }) {
const { pin } = useHTMLPin({
containerId: "myContainer",
dataAttributeName: "data-comment-id",
});
return (
<Comments pin={pin} />
);
}
dataAttributeValueFilters
Optional. RegExp[]
This Regex array is used to filter what elements should not be able to receive a comment pin.
function Room({ participantId }) {
const { pin } = useHTMLPin({
containerId: "myContainer",
dataAttributeValueFilters: [/.*-null-(target|target)$/] ,
});
return (
<Comments pin={pin} />
);
}