简体中文

---

An embeddable web client for federated comments using the Matrix network. This fork revitalizes the original Cactus Comments with new features and bug fixes.

There are two components to Cactus Comments:

• The embeddable web client (this repo)
• The server-side appservice (found here)

This repository is only the web client.

Demo

You can play with a live demo at nigzu.com.

Screenshots

Features

• Modern Architecture: Refactored to support Node.js v22+.
• Enhanced Media Support:
  • Authenticated Media: Supports Matrix's authenticated media endpoints (isAuthenticated: true) with a three-tier caching system (Memory, IndexedDB, Network) for optimized loading.
• Full Reply Functionality:
  • Quote Replies: Clear context for replies.
  • Hover Preview: Instantly preview the content of a reply (text, image, video).
  • Click to Jump: Navigate to the original message.
• Read-Only Mode: A commentEnabled: false option to disable commenting, perfect for archives or announcements.
• Internationalization:
  • Language Switching: language option to set the display language.
  • Flexible Translations: Supports custom translation files (JS or JSON) with smart fallbacks.
• UI/UX Fixes:
  • Fixed layout overflows and text wrapping issues.
  • Incremental Loading: "Load More" now appends comments instead of refreshing the entire section, preventing flickers and improving performance.

Quick Start

1. Download the latest release from the release page.
2. Upload cactus.js, style.css, and cactus-lang.js to your server or CDN.
3. Include the files in your HTML:

<link rel="stylesheet" href="path/to/your/style.css" type="text/css">
<script type="text/javascript" src="path/to/your/cactus.js"></script>
<script type="text/javascript" src="path/to/your/cactus-lang.js"></script>

4. Add the comment section container and initialize the client:

<div id="comment-section"></div>

<script>
  initComments({
    // Required
    node: document.getElementById("comment-section"),
    defaultHomeserverUrl: "https://matrix.cactus.chat:8448",
    serverName: "cactus.chat",
    siteName: "your-site-name", // The unique name you registered for your site.
    commentSectionId: "unique-page-id", // A unique ID for each page's comment section.

    // Optional - New Features!
    isAuthenticated: true, // Set to true if your homeserver uses authenticated media.
    commentEnabled: true, // Set to false for read-only mode.
    language: 'en', // e.g., 'en', 'cn', 'fr'.
    translationsData: 'cactusTranslations', // Translation file, you can also provide it on your own website.
    
    // Other optional parameters...
    pageSize: 10,
    loginEnabled: true,
    guestPostingEnabled: true,
  });
</script>

You also need to use an appservice. You can host your own, or use the public one at cactus.chat. For self-hosting, see the instructions below.

Configuration

The initComments function accepts the following parameters:

Name	Type	Required	Default	Description
node	HTMLElement/String	Yes	-	The HTML element (or a selector string) to be replaced by the comment section.
defaultHomeserverUrl	String	Yes	-	The URL of the Matrix homeserver that has the Cactus Comments appservice.
serverName	String	Yes	-	The server name of the Matrix homeserver.
siteName	String	Yes	-	The unique identifier for your site registered with the Cactusbot.
commentSectionId	String	Yes	-	A unique identifier for the comment section, used to create the room alias.
pageSize	Integer	No	10	Number of comments to load initially and on "load more".
loginEnabled	Boolean	No	true	If true, users can log in with their Matrix credentials.
guestPostingEnabled	Boolean	No	true	If true, users can post comments as guests without logging in.
updateInterval	Float	No	0	Interval in seconds to fetch new comments. 0 or negative disables it.
isAuthenticated	Boolean	No	false	Enable for homeservers with authenticated media.
commentEnabled	Boolean	No	true	Set to false to make the comment section read-only.
translationsData	String	No	cactusTranslations	The variable name for translation data. Defaults to the one in cactus-lang.js.
language	String	No	en	An ISO 639 language code (e.g., cn, fr, en).

Self-Hosting

When self-hosting the Matrix server (e.g., Synapse) and the Cactus Appservice, make sure to:

1. Enable Guest Access in your homeserver.yaml:

   allow_guest_access: true

2. Enable Legacy Appservice Authorization: The Cactus Appservice requires an older authorization mechanism. Add this to your homeserver.yaml to allow the bot to register and manage rooms correctly:

   use_appservice_legacy_authorization: true

   Warning: This is required for the appservice to create its management bot and for you to register sites. Without it, the appservice will fail with a 401 CHAT.CACTUS.APPSERVICE_UNAUTHORIZED error.

Documentation

The complete documentation for the original project is available at our website, cactus.chat. Note that it may not cover the new features introduced in this fork.

For more instructions and detailed tutorials on this new branch, please refer to the article (in Chinese): Rejuvenating the Matrix Commenting System: New Features I Developed for Cactus Comments.