Marfeel Docs

# Create a commenting system extension

If a provider is not supported by Marfeel, create a new extension. If it's the first time for this provider, the extension is created in the Tenant's code repository as a custom commenting system. Otherwise, add the extension to Marfeel core.

You can research if this provider already has a custom implementation via Github with this search URL, replacing ${PROVIDER_NAME} with the one you're looking for.

https://github.com/search?q=org%3AMarfeel+filename%3Acomments+extension%3Ajson+name+${PROVIDER_NAME}&type=Code

For example for Vuukle: https://github.com/search?q=org%3AMarfeel+filename%3Acomments+extension%3Ajson+custom+vuukle&type=Code (opens new window)

# Custom commenting system as a plugin

Comments systems implemented as Marfeel plugins benefit from Marfeel's lazy loading strategy and work on PWA and native platforms out-of-the-box. Marfeel doesn't handle authentication to post comments. When that feature exists, it redirects users to the classic version of the Tenant's website.

  1. Write a Javascript class with all the required behavior, following the provider's implementation guidelines.

The file must be in under src/js/features/comments/ in the site code repository.

WARNING

Always extend AbstractEmbedComments in your CustomComments class, overwriting its functions if needed.

  1. Declare the implementation as a Marfeel plugin, at the end of the file:
import m from 'Marfeel';

m.definePlugin('AwesomeCustomComments', function() {
    return new AwesomeCustomComments(this);
});
  1. Reference the plugin you created in the comments.json file:
{
    "custom" : [ {
      "name" : "AwesomeCustomComments",
      "file" : "AwesomeCustomComments"
    } ]
  }
  • The file property points to the file name, here: src/js/features/comments/awesomeCustomComments.js
  • The name property is the name used in the definePlugin method.
  1. Add styles in an scss file, following Marfeel Coding Standards.

# Plugin Implementation examples

AMP support

Custom comments created this way are not supported in AMP.

# Custom commenting system as a 3pi-widget

A custom commenting system can also be implemented as a 3pi-widget. This makes custom comments AMP-friendly.

Create it like a normal 3pi-widget, but call it customComments.

# Promote a custom commenting system to Marfeel Core

If an extension already exists as Custom and has to be reused for a different Tenant, promote it to Marfeel Core. The steps to follow are similar to the ones for promoting Metrics providers:

  1. Create the entity in MarfeelWonderlandDomain/src/main/java/com/marfeel/wonderland/entity/comments/
  2. Add the entity to MarfeelWonderlandDomain/src/main/java/com/marfeel/wonderland/entity/comments/Comments
  3. Add the JS implementation for TOUCH in MarfeelXP/Dixie/src/js/marfeel/touch/features/comments/
    • This implementation should be the same as the existing custom one, save for additional parameters as needed.
    • The definePlugin part can be skipped
  4. Move the HTML template (if it exists) to a JSP template, under marfeel/themes/default/commentingSystems
  5. Move the PWA styles (if they exist):
    • to Pixie/scss/detailsLayouts/detailsDecorator/_${PROVIDER_NAME}.scss
    • import this file in Pixie/scss/detailsLayouts/_detailsDecorator.scss
  6. Move the AMP styles (if they exist):
    • to Pixie/scss/amp/components/_${PROVIDER_NAME}.scss
    • import this file in marfeel/themes/amp/styles.jsp
  7. Add the json schema to MarfeelSchemas/json-lint/schemas/metrics/providers/

For AMP support of this extension, additionally:

  1. Add the extension name to the list in the marfeel/themes/amp/detailsLayouts/detailsDecoratorComments template
  2. Add under marfeel/themes/amp/commentingSystems/ the AMP-specific template.

Deployment order

Shuttle Gutenberg before you use a new Commenting extension in the Tenant's repository.

# Implementation tips

While there is no interface to implement, it is recommended to implement the following methods in all commenting systems:

class AwesomeCustomComments extends AbstractEmbedComments {
  constructor();
  loadComments();
  postComment();
  destroy();
}

The module CommentsUtils provides often-needed methods, such as notifyHeightUpdate to communicate with Marfeel core.

# Leverage collapsable comments

Any custom commenting system can leverage the collapsable comments feature. To use it, the Comment class must have an instance of CollapsableComments as an attribute.

The implementation can communicate lifecycle events with the Collapsable feature, as well as give a comments count.

import m from 'Marfeel';
import AbstractEmbedComments from 'AbstractEmbedComments';
import CollapsableComments from 'CollapsableComments';


class AwesomeCollapsableCustomComments extends AbstractEmbedComments {
  constructor(element) {
    super(...arguments);
    this.collapsableComments = new CollapsableComments(this.element);
  }
  destroy() {
    this.collapsableComments.destroy();
  }
  loadComments() {
    //...
    this.collapsableComments.commentsReady();
    this.collapsableComments.setCommentsCount(numComments);
  }
}
m.definePlugin('AwesomeCollapsableCustomComments', function() {
	return new AwesomeCollapsableCustomComments(this);
});

# Leverage metadata providers

Custom comments providers implementations can use metadata providers. See an implementation example on Github (opens new window).

← Overview →