Origami Frontend Components & Services

Readme: o-comments

o-comments is not maintained by the Origami team. This means that the Origami team will not necessarily be able to help you with support requests. The people who maintain this component may be able to offer support, but it's not guaranteed.

A component, integrated with FT authentication and Coral Talk, to add a comment stream or comment count to content.

Usage

Check out how to include Origami components in your project to get started with o-comments.

Unlike other Origami components o-comments requires additional peer dependencies.

Additional dependencies

o-comments is dependant on sass from o-overlay and o-forms and requires them to be included by the parent application.

Markup

These elements will be initialized automatically on the o.DOMContentReady event meaning you're unable to defer component initialisation.

Stream

Use the following markup to enable a comment stream:

<div class="o-comments"
    id="{element-id}"
    data-o-component="o-comments"
    data-o-comments-article-id="{article-id}"
    data-o-comments-article-url="{optional-article-url}">
</div>

Coral needs a parent element id when initialising the comment stream embed script.

Count

Add the following attribute to the markup to enable a comment count:

<div class="o-comments"
-    id="{element-id}"
    data-o-component="o-comments"
    data-o-comments-article-id="{article-id}"
+    data-o-comments-count="true">
</div>

The comment count is rendered when the data-o-comments-count attribute value is true.

getCount

If you need the count as a value, use the getCount method which returns an integer.

Comments.getCount('article-id')
    .then(count => console.log(count));

Use staging environment

Add the following attribute to the markup to use Coral staging environment:

For stream:

<div class="o-comments"
    id="o-comments-stream"
    data-o-component="o-comments"
    data-o-comments-article-id="{article-id}"
    data-o-comments-article-url="{optional-article-url}"
+    data-o-comments-use-staging-environment="true">
</div>

For count:

<div class="o-comments"
    data-o-component="o-comments"
    data-o-comments-article-id="{article-id}"
    data-o-comments-count="true"
+    data-o-comments-use-staging-environment="true">
</div>

Pass a display name into Coral Talk

In rare cases, a user may have already set their display name in a different part of the website. In this instance, add the following attribute to pass the display name into Coral Talk when creating a user account:

<div class="o-comments"
    id="o-comments-stream"
    data-o-component="o-comments"
    data-o-comments-article-id="{article-id}"
    data-o-comments-article-url="{optional-article-url}"
+    data-o-comments-display-name="{display-name}">
</div>

JavaScript

No code will run automatically unless you are using the Build Service. You must either construct an o-comments object or fire the o.DOMContentLoaded event, which o-comments listens for.

Constructing an o-comments

Assuming you have an HTML element on the page to represent your comment stream or count:

import oComments from 'o-comments';
const commentsElement = document.querySelector('#element');
const Comments = new oComments(commentsElement, {
    articleId: 'article-id',
    articleUrl: 'optional-article-url'
})

Add useStagingEnvironment: true to the options if you want to use Coral staging environment.

If you want to initialise every comment stream or count element on the page (based on the presence of the attribute: data-o-component="o-comments"):

import oComments from 'o-comments';
oComments.init();

Firing an oDomContentLoaded event

import 'o-comments';

document.addEventListener('DOMContentLoaded', function() {
    document.dispatchEvent(new CustomEvent('o.DOMContentLoaded'));
});

Events

Events are emitted during key events or interactions and can be listened to by listening for events on the document.

document.addEventListener('oComments.ready', (event) => {
    console.log('This comments have rendered');
});

Global / Component

These events are anything to do with the component itself.

Comment

These events are anything to do with comment interactions.

Tracking

To keep tracking consistent across applications o-comments will emit o-tracking events for all of the events. If your application is already using o-tracking then then there is no need to do anything to track common events.

Disable tracking

If you want to disable the o-tracking events and manage tracking / analytics yourself this can be done by passing the disableOTracking option to the o-comments instance.

Imperatively

import oComments from 'o-comments';
const commentsElement = document.querySelector('#element');
const comments = new Comments(commentsElement, {
    disableOTracking: true
});

Declaratively

<div class="o-comments"
    id="o-comments-stream"
    data-o-component="o-comments"
    data-o-comments-article-id="{article-id}"
    data-o-comments-article-url="{optional-article-url}"
+    data-o-comments-disable-o-tracking="true">
</div>

Sass

Include all styles for o-comments with the mixin oComments:

@include oComments()

Styling of Coral Talk iframe

This component contains a sass file (/src/scss/coral-talk-iframe/main.scss) that provides custom styling for Coral Talk components inside their own iframe. That file must only be referenced from Coral Talk admin panel by specifying the path of the file in Origami Build Service.

Example: modules=o-comments@6.0.0-beta.24:/src/scss/coral-talk-iframe/main.scss

Encoded URL: https://www.ft.com/__origami/service/build/v2/bundles/css?modules%3Do-comments%406.0.0-beta.24%3A%2Fsrc%2Fscss%2Fcoral-talk-iframe%2Fmain.scss

Migration

State Major Version Last Minor Release Migration guide
✨ active 7 N/A migrate to v7
⚠ maintained 6 N/A migrate to v6
╳ deprecated 5 5.0.1 migrate to v5
╳ deprecated 4 4.2.0 -
╳ deprecated 3 3.5.0 -
╳ deprecated 2 2.5.0 -
╳ deprecated 1 1.0.10 -

Contact

If you have any questions or comments about this component, or need help using it, please either raise an issue, visit #origami-support or email Origami Support.

Licence

This software is published by the Financial Times under the MIT licence.

Status
active Origami v1
Switch component view

GitHub Repository

Install o-comments

If using the Build Service, add o-comments@^7.7.4 to your script and link tags.

If running a Manual Build, run npm install "o-comments@^7.7.4".

Help & Support

o-comments is not supported directly by the Origami team. We make no guarantees, but will help if we can. First try contacting its maintainers at:

Slack: #content-innovation
Email: content-innovation-team.customer-products@ft.com