From 5e4b5883a1e86c0d301e6cc90ac282502f1012a8 Mon Sep 17 00:00:00 2001 From: Rohan Shaw Date: Mon, 2 Jun 2025 22:02:40 +0530 Subject: [PATCH 1/4] docs: Add comprehensive documentation for plone.app.discussion components --- .readthedocs.yaml | 32 ++++ docs/architecture.md | 50 +++++++ docs/auto-approve.md | 49 +++++++ docs/components/behavior.md | 122 ++++++++++++++++ docs/components/catalog.md | 251 ++++++++++++++++++++++++++++++++ docs/components/comment.md | 157 ++++++++++++++++++++ docs/components/controlpanel.md | 195 +++++++++++++++++++++++++ docs/components/conversation.md | 184 +++++++++++++++++++++++ docs/components/events.md | 207 ++++++++++++++++++++++++++ docs/components/form.md | 155 ++++++++++++++++++++ docs/components/index.md | 35 +++++ docs/components/moderation.md | 139 ++++++++++++++++++ docs/components/restapi.md | 239 ++++++++++++++++++++++++++++++ docs/components/tool.md | 202 +++++++++++++++++++++++++ docs/components/viewlet.md | 198 +++++++++++++++++++++++++ docs/conf.py | 65 +++++++++ docs/index.md | 54 +++++++ requirements-docs.txt | 9 ++ 18 files changed, 2343 insertions(+) create mode 100644 .readthedocs.yaml create mode 100644 docs/architecture.md create mode 100644 docs/auto-approve.md create mode 100644 docs/components/behavior.md create mode 100644 docs/components/catalog.md create mode 100644 docs/components/comment.md create mode 100644 docs/components/controlpanel.md create mode 100644 docs/components/conversation.md create mode 100644 docs/components/events.md create mode 100644 docs/components/form.md create mode 100644 docs/components/index.md create mode 100644 docs/components/moderation.md create mode 100644 docs/components/restapi.md create mode 100644 docs/components/tool.md create mode 100644 docs/components/viewlet.md create mode 100644 docs/conf.py create mode 100644 docs/index.md create mode 100644 requirements-docs.txt diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..590d12d9 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,32 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the OS, Python version and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.11" + jobs: + pre_build: + # Generate the Sphinx configuration for this Jupyter Book so it builds. + - pip install -r requirements-docs.txt + - jupyter-book config sphinx docs/ + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: docs/conf.py + fail_on_warning: false + +# Optionally build your docs in additional formats such as PDF and ePub +formats: + - pdf + - epub + +# Declare the Python requirements required to build your docs +python: + install: + - requirements: requirements-docs.txt diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 00000000..c059d4c2 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,50 @@ +--- +myst: + html_meta: + "description": "Architectural Principles of plone.app.discussion" + "property=og:description": "Architectural Principles of plone.app.discussion" + "property=og:title": "Architectural Principles" + "keywords": "Plone, Discussion, Architecture, Comments, Design" +--- + +# Architectural Principles + +This document outlines architectural principles used in the design of plone.app.discussion. + +## Core Design Principles + +**Discussion items have a portal_type** +: This makes it easier to search for them and manage them using existing CMF and Plone UI constructs. + +**Discussion items are cataloged** +: It is possible to search for discussion items like any other type of content. + +**Discussion items are subject to workflow and permission** +: Moderation, anonymous commenting, and auto-approve/reject should be handled using workflow states, automatic and manual transitions, and permissions. + +**Discussion items are lightweight objects** +: Discussion item objects are as lightweight as possible. Ideally, a discussion item should be as lightweight as a catalog brain. This may mean that we forego convenience base classes and re-implement certain interfaces. Comments should not provide the full set of Dublin Core metadata, though custom indexers can be used to provide values for standard catalog indexes. + +**Optimise for retrieval speed** +: Most users will be reading comments, not posting them. HTML filtering and other processing should happen on save, not on render, to make rendering quick. + +**Settings are stored using plone.registry** +: Any global setting should be stored in plone.registry records. + +**Forms are constructed using extensible z3c.form forms** +: This allows plugins (such as spam protection algorithms) to provide additional validation. It also allows integrators to write add-ons that add new fields to the comment form. + +**Discussion items are stored in a BTree container** +: This allows faster lookup and manipulation. + +**Discussion items are accessed using a dict-like interface** +: This makes iteration and manipulation more natural. Even if comments are not stored threaded, the dict interface should act as if they are, i.e. calling items() on a comment should return the replies to that comment (in order). + +**Discussion items are retrieved in reverse creation date order** +: Discussion items do not need to support explicit ordering. They should always be retrieved in reverse creation date order (most recent for). They can be stored with keys so this is always true. + +**Discussion items do not need readable ids** +: Ids can be based on the creation date. + +**Discussion items send events** +: The usual zope.lifecycleevent and zope.container events are fired when discussion items are added, removed, or modified. diff --git a/docs/auto-approve.md b/docs/auto-approve.md new file mode 100644 index 00000000..d33b7a2e --- /dev/null +++ b/docs/auto-approve.md @@ -0,0 +1,49 @@ +--- +myst: + html_meta: + "description": "Automatic Comment Approval in plone.app.discussion" + "property=og:description": "Automatic Comment Approval in plone.app.discussion" + "property=og:title": "Automatic Comment Approval" + "keywords": "Plone, Discussion, Comments, Approval, Moderation" +--- + +# Automatic Comment Approval + +## Introduction + +This feature enhances the Plone discussion system by automatically approving comments from users +who have the "Review comments" permission, even when comment moderation is enabled site-wide. + +## How It Works + +When a user with the "Review comments" permission creates a comment, the system will: + +1. Check if comment moderation is enabled +2. Verify if the user has the "Review comments" permission +3. Automatically publish the comment if both conditions are met + +This functionality is particularly useful for: + +- Trusted community members +- Moderators who should bypass the moderation queue +- Site editors or staff members + +## Configuration + +No additional configuration is needed. Simply assign the "Review comments" permission to +the roles or users you want to bypass moderation. + +### Examples + +- Assign "Review comments" permission to the Editor role +- Create a "Trusted Commenter" role with the "Review comments" permission +- Give specific users the permission on specific content + +## Permission Management + +The "Review comments" permission can be managed: + +- Site-wide through the Security control panel +- Per content type through the Types control panel +- Per folder through the Sharing tab +- Per item through the Sharing tab diff --git a/docs/components/behavior.md b/docs/components/behavior.md new file mode 100644 index 00000000..1f2fdf2f --- /dev/null +++ b/docs/components/behavior.md @@ -0,0 +1,122 @@ +--- +myst: + html_meta: + "description": "Discussion behavior in plone.app.discussion" + "property=og:description": "Discussion behavior in plone.app.discussion" + "property=og:title": "Discussion Behavior" + "keywords": "Plone, Discussion, Behavior, IAllowDiscussion" +--- + +# Allow Discussion Behavior + +## Overview + +The `IAllowDiscussion` behavior provides a UI control for enabling or disabling comments on individual content objects. This behavior can be applied to any content type, allowing fine-grained control over which content items can have comments. + +## Interface + +The behavior is defined in `plone.app.discussion.behavior`: + +```python +@provider(IFormFieldProvider) +class IAllowDiscussion(model.Schema): + """Allow discussion behavior. + + Provides a field to enable or disable comments on a content item. + """ + + model.fieldset( + "settings", + label=_("Settings"), + fields=["allow_discussion"], + ) + + allow_discussion = schema.Choice( + title=_("Allow discussion"), + description=_("Allow discussion for this content object."), + vocabulary=options, + required=False, + default=None, + ) +``` + +The vocabulary options are simple Yes/No values: + +```python +options = SimpleVocabulary( + [ + SimpleTerm(value=True, title=_("Yes")), + SimpleTerm(value=False, title=_("No")), + ] +) +``` + +## Usage + +### Enabling the Behavior + +To enable the behavior on a content type, add it to the type's FTI: + +```xml + + + +``` + +Or in Python: + +```python +fti = getUtility(IDexterityFTI, name='my_content_type') +behaviors = list(fti.behaviors) +behaviors.append('plone.allowdiscussion') +fti.behaviors = tuple(behaviors) +``` + +### Using the Behavior + +Once the behavior is enabled for a content type: + +1. The "Allow discussion" field appears in the "Settings" fieldset of the edit form. +2. Users can select "Yes" or "No" to enable or disable comments. +3. If left unselected (None), the content type's default setting is used. + +## Checking If Discussion is Enabled + +The conversation component uses this behavior to determine if discussion is enabled: + +```python +def enabled(self): + """Return True if commenting is enabled on this conversation.""" + + # Global setting + if not registry_settings.globally_enabled: + return False + + # Content-specific setting + if context.allow_discussion is not None: + return context.allow_discussion + + # Content type setting + return portal_types.getTypeInfo(context).getProperty('allow_discussion') +``` + +## Default Settings + +The behavior defaults to `None`, which means the content type's setting is used. +Content types have an `allow_discussion` property that can be set in their FTI: + +```xml +False +``` + +## Interoperability + +This behavior works with both Dexterity and Archetypes content types: + +- For Dexterity, the `plone.allowdiscussion` behavior is used. +- For Archetypes, the `allowDiscussion` method is used. + +## Related Components + +- [Conversation](./conversation.md) - Uses the behavior to determine if comments are enabled +- [Control Panel](./controlpanel.md) - Global settings for discussions diff --git a/docs/components/catalog.md b/docs/components/catalog.md new file mode 100644 index 00000000..6ca86583 --- /dev/null +++ b/docs/components/catalog.md @@ -0,0 +1,251 @@ +--- +myst: + html_meta: + "description": "Comment cataloging in plone.app.discussion" + "property=og:description": "Comment cataloging in plone.app.discussion" + "property=og:title": "Comment Cataloging" + "keywords": "Plone, Discussion, Catalog, Indexing" +--- + +# Comment Cataloging + +## Overview + +plone.app.discussion integrates with Plone's catalog system to make comments searchable and efficiently retrievable. This is accomplished through custom indexers and standard catalog integration. + +## Indexers + +The module `plone.app.discussion.catalog` defines custom indexers for comments: + +```python +@indexer(IComment) +def SearchableText(object): + """Indexer for the SearchableText field. + + Includes the comment text, author name, and other searchable fields. + """ + return " ".join([ + safe_text(object.text) or "", + safe_text(object.author_name) or "", + safe_text(object.author_email) or "", + ]) + +@indexer(IComment) +def Title(object): + """Indexer for the Title field.""" + if hasattr(object, 'title') and object.title: + return object.title + else: + # Generate a title from the author's name and the content + content_title = object.__parent__.__parent__.title + author = object.author_name or _('Anonymous') + return translate( + COMMENT_TITLE, + context=getSite().REQUEST, + mapping={'author_name': author, 'content': content_title} + ) + +@indexer(IComment) +def Creator(object): + """Indexer for the Creator field.""" + return object.creator + +@indexer(IComment) +def in_response_to(object): + """Indexer for the in_response_to field.""" + return object.in_reply_to + +@indexer(IComment) +def effective(object): + """Indexer for the effective date.""" + if object.publication_date is not None: + return object.publication_date + return object.creation_date + +@indexer(IComment) +def created(object): + """Indexer for the creation date.""" + return object.creation_date + +@indexer(IComment) +def modified(object): + """Indexer for the modification date.""" + return object.modification_date +``` + +## Special Indexers + +Some indexers are specially defined to avoid comments inheriting properties from their container: + +```python +@indexer(IComment) +def UID(object): + """Indexer for the UID. + + Make sure comments don't inherit their container's UID. + """ + return object.comment_id +``` + +## Conversation-related Indexers + +Special indexers handle conversation-related metadata: + +```python +@indexer(IComment) +def comments_total_comments(object): + """Total comment count for a comment. + + Override the conversation indexers for comments. + """ + return 0 + +@indexer(IComment) +def comments_last_comment_date(object): + """Date of the most recent comment. + + Override the conversation indexers for comments. + """ + return None + +@indexer(IComment) +def comments_commentators(object): + """List of commentators. + + Override the conversation indexers for comments. + """ + return () +``` + +## Comment Metadata + +Comments are indexed with several metadata columns: + +### Standard Metadata + +- `Title` - The comment title +- `Creator` - The comment author +- `created` - Creation date +- `modified` - Modification date +- `effective` - Effective date (publication date) +- `SearchableText` - Full-text search index + +### Custom Metadata + +- `in_response_to` - Parent comment ID +- `author_name` - Display name of the author +- `author_username` - Username of the author +- `review_state` - Workflow state of the comment + +## Catalog Configuration + +The catalog configuration is set up in the installation profile: + +```xml + + + + + +``` + +## Indexing Events + +Comments are automatically indexed when events occur: + +```python +def index_object(obj, event): + """Index the object when added to the conversation""" + # Skip if object isn't a comment + if not IComment.providedBy(obj): + return + + tool = queryUtility(ICommentingTool) + if tool is not None: + tool.indexObject(obj) +``` + +The indexing is triggered by: + +- `ObjectAddedEvent` - When a comment is added +- `ObjectModifiedEvent` - When a comment is modified +- `WorkflowTransitionEvent` - When a comment's workflow state changes + +## Unindexing Events + +Comments are automatically unindexed when removed: + +```python +def unindex_object(obj, event): + """Unindex the object when removed""" + # Skip if object isn't a comment + if not IComment.providedBy(obj): + return + + tool = queryUtility(ICommentingTool) + if tool is not None: + tool.unindexObject(obj) +``` + +## Portal Catalog Integration + +Comments are fully integrated with the portal_catalog, which means: + +1. They can be found using standard catalog searches +2. They appear in search results alongside other content +3. They can be filtered by workflow state, creation date, etc. + +## Usage Examples + +### Finding Comments by Keyword + +```python +def search_comments_by_text(context, searchtext): + catalog = getToolByName(context, 'portal_catalog') + + results = catalog( + object_provides=IComment.__identifier__, + SearchableText=searchtext, + sort_on='created', + sort_order='reverse', + ) + + return [r.getObject() for r in results] +``` + +### Finding Recent Comments + +```python +def get_recent_comments(context, count=5): + catalog = getToolByName(context, 'portal_catalog') + + results = catalog( + object_provides=IComment.__identifier__, + sort_on='created', + sort_order='reverse', + sort_limit=count, + ) + + return [r.getObject() for r in results[:count]] +``` + +### Finding Comments by Review State + +```python +def get_comments_by_state(context, state): + catalog = getToolByName(context, 'portal_catalog') + + results = catalog( + object_provides=IComment.__identifier__, + review_state=state, + sort_on='created', + sort_order='reverse', + ) + + return [r.getObject() for r in results] +``` + +## Related Components + +- [Comment](./comment.md) - The objects being indexed +- [Tool](./tool.md) - The portal_discussion tool for searching comments diff --git a/docs/components/comment.md b/docs/components/comment.md new file mode 100644 index 00000000..7c8c0d01 --- /dev/null +++ b/docs/components/comment.md @@ -0,0 +1,157 @@ +--- +myst: + html_meta: + "description": "Comment component in plone.app.discussion" + "property=og:description": "Comment component in plone.app.discussion" + "property=og:title": "Comment Component" + "keywords": "Plone, Discussion, Comment, IComment" +--- + +# Comment Component + +## Overview + +The Comment component is the core object that represents a user comment in the plone.app.discussion system. Comments are lightweight content objects that store the actual comment text and metadata. + +## Interfaces + +The primary interface for comments is `IComment`, defined in `plone.app.discussion.interfaces`: + +```python +class IComment(Interface): + """A comment. + + Comments are stored in IConversation objects and contained in them. + """ + + portal_type = schema.ASCIILine( + title=_("Portal type"), + default="Discussion Item", + readonly=True, + ) + + __parent__ = schema.Object( + title=_("Conversation"), + schema=Interface, + ) + + __name__ = schema.TextLine(title=_("Name"), default=None) + + comment_id = schema.Int( + title=_("Comment id"), + default=None, + ) + + in_reply_to = schema.Int( + title=_("In reply to"), + default=0, + ) + + # plus additional fields for content, author info, etc. +``` + +## Implementation + +The `Comment` class implements the `IComment` interface and is defined in `plone.app.discussion.comment`. It inherits from several base classes to provide its functionality: + +```python +@implementer(IComment) +class Comment( + CatalogAware, + WorkflowAware, + DynamicType, + Traversable, + RoleManager, + Owned, + Implicit, + Persistent, +): + """A comment. + + Comments are stored in Conversation objects and contained in them. + """ +``` + +The base classes provide the following capabilities: + +- `CatalogAware` - For indexing in the portal_catalog +- `WorkflowAware` - For workflow integration +- `DynamicType` - For dynamic type information +- `Traversable` - For traversal support (URLs) +- `RoleManager` - For permissions and role management +- `Owned` - For ownership tracking +- `Implicit` - For implicit acquisition +- `Persistent` - For ZODB persistence + +## Key Attributes + +A comment has several important attributes: + +- `text`: The actual comment text +- `creator`: The user who created the comment +- `creation_date`: When the comment was created +- `modification_date`: When the comment was last modified +- `author_name`: Display name of the author +- `author_email`: Email of the author +- `title`: Auto-generated title based on author and content +- `mime_type`: MIME type of the comment text (plain text, HTML, etc.) +- `comment_id`: Unique identifier for the comment +- `in_reply_to`: ID of the parent comment (0 for top-level comments) + +## Usage + +### Creating a Comment + +Comments are created using the `createObject` factory: + +```python +from zope.component import createObject + +comment = createObject("plone.Comment") +comment.text = "This is a comment" +comment.author_name = "John Doe" +comment.author_email = "john@example.com" +``` + +### Adding a Comment to a Conversation + +```python +from plone.app.discussion.interfaces import IConversation + +conversation = IConversation(context) +comment_id = conversation.addComment(comment) +``` + +### Retrieving a Comment + +```python +# By traversal +comment = context.restrictedTraverse("++conversation++default/123") + +# Or from the conversation +conversation = IConversation(context) +comment = conversation.get(comment_id) +``` + +## Workflow Integration + +Comments can be subject to workflow. The default workflows provided are: + +1. `comment_one_state_workflow` - Comments are immediately published +2. `comment_review_workflow` - Comments require moderation before publishing + +Workflows are applied to the "Discussion Item" portal type. + +## Events + +When comments are added, modified, or removed, corresponding events are fired: + +- `ICommentAddedEvent` - When a comment is added to a conversation +- `ICommentModifiedEvent` - When a comment is modified +- `ICommentRemovedEvent` - When a comment is removed + +## Related Components + +- [Conversation](./conversation.md) - Container for comments +- [Events](./events.md) - Event system for comments +- [Form](./form.md) - UI for adding and editing comments diff --git a/docs/components/controlpanel.md b/docs/components/controlpanel.md new file mode 100644 index 00000000..6cd0100a --- /dev/null +++ b/docs/components/controlpanel.md @@ -0,0 +1,195 @@ +--- +myst: + html_meta: + "description": "Discussion control panel in plone.app.discussion" + "property=og:description": "Discussion control panel in plone.app.discussion" + "property=og:title": "Discussion Control Panel" + "keywords": "Plone, Discussion, Control Panel, Settings" +--- + +# Discussion Control Panel + +## Overview + +The Discussion Control Panel provides a centralized interface for configuring the global settings of the plone.app.discussion system. It uses `plone.registry` to store and manage these settings. + +## Implementation + +The control panel is implemented in `plone.app.discussion.browser.controlpanel`: + +```python +class DiscussionSettingsEditForm(controlpanel.RegistryEditForm): + """Discussion settings form.""" + + schema = IDiscussionSettings + id = "DiscussionSettingsEditForm" + label = _("Discussion settings") + + # Form implementation details +``` + +```python +class DiscussionSettingsControlPanel(controlpanel.ControlPanelFormWrapper): + """Discussion settings control panel.""" + + form = DiscussionSettingsEditForm + index = ViewPageTemplateFile("controlpanel.pt") +``` + +## Settings Schema + +The settings schema is defined in `plone.app.discussion.interfaces.IDiscussionSettings`: + +```python +class IDiscussionSettings(Interface): + """Global discussion settings. + + Interface for the plone.registry configuration records. + """ + + globally_enabled = schema.Bool( + title=_("Globally enable comments"), + description=_("Enable comments globally"), + required=True, + default=False, + ) + + anonymous_comments = schema.Bool( + title=_("Anonymous comments"), + description=_("Enable anonymous comments"), + required=True, + default=False, + ) + + moderation_enabled = schema.Bool( + title=_("Comment moderation"), + description=_("Require moderation for all comments"), + required=True, + default=False, + ) + + # Additional settings for email, captcha, etc. +``` + +## Available Settings + +The control panel provides settings for: + +### Core Functionality + +- `globally_enabled` - Enable/disable commenting globally +- `moderation_enabled` - Enable comment moderation for all comments +- `edit_comment_enabled` - Allow users to edit their own comments +- `delete_own_comment_enabled` - Allow users to delete their own comments +- `anonymous_comments` - Allow anonymous users to comment + +### Display Options + +- `show_commenter_image` - Show user portrait images +- `text_transform` - Text transformation method for comments + +### CAPTCHA + +- `captcha` - CAPTCHA method for anonymous comments (disabled, standard, recaptcha, norobots, hcaptcha) + +### Email Notifications + +- `moderator_notification_enabled` - Email notifications for moderators +- `user_notification_enabled` - Email notifications for users (on replies) + +## Form Widgets + +The control panel form uses custom widgets for better user experience: + +```python +def updateWidgets(self): + super().updateWidgets() + self.widgets["globally_enabled"].label = _("Enable Comments") + self.widgets["anonymous_comments"].label = _("Anonymous Comments") + self.widgets["show_commenter_image"].label = _("Commenter Image") + # etc. +``` + +Most boolean fields use `SingleCheckBoxFieldWidget` for a cleaner UI. + +## Warning Messages + +The control panel displays warning messages for common issues: + +### Mail Host Warning + +If email notifications are enabled but the mail server isn't configured: + +```python +def mailhost_warning(self): + """Returns true if mailhost is not configured properly.""" + registry = getUtility(IRegistry) + mail_settings = registry.forInterface(IMailSchema, prefix="plone") + return not mail_settings.email_from_address or not mail_settings.smtp_host +``` + +### Custom Workflow Warning + +If a custom workflow is used for the Discussion Item type: + +```python +def custom_comment_workflow_warning(self): + """Return True if a custom comment workflow is enabled.""" + wftool = getToolByName(self.context, "portal_workflow", None) + workflow_chain = wftool.getChainForPortalType("Discussion Item") + one_state_workflow_enabled = "comment_one_state_workflow" in workflow_chain + comment_review_workflow_enabled = "comment_review_workflow" in workflow_chain + return not (one_state_workflow_enabled or comment_review_workflow_enabled) +``` + +## REST API Integration + +The control panel also provides a REST API endpoint for Volto and other clients: + +```python +@adapter(Interface, IControlpanelLayer) +class DiscussionControlPanel(RegistryConfigletPanel): + """Volto-compatible REST API control panel for discussion settings.""" + + schema = IDiscussionSettings + schema_prefix = None + configlet_id = "discussion" + configlet_category_id = "plone-content" + title = _("Discussion") + group = "Content" +``` + +## Events + +Configuration changes trigger events that subscribers can listen to: + +```python +def notify_configuration_changed(event): + """Event subscriber that is called every time the configuration changed.""" + if IRecordModifiedEvent.providedBy(event) and \ + event.record.interface == IDiscussionSettings: + pass # Handle configuration change +``` + +## Accessing Settings + +The settings can be accessed from code using the registry: + +```python +from plone.registry.interfaces import IRegistry +from zope.component import queryUtility +from plone.app.discussion.interfaces import IDiscussionSettings + +registry = queryUtility(IRegistry) +settings = registry.forInterface(IDiscussionSettings) + +# Access settings +if settings.globally_enabled: + # Comments are enabled globally +``` + +## Related Components + +- [Behavior](./behavior.md) - Per-content type and per-item settings +- [Moderation](./moderation.md) - Comment moderation system +- [Conversation](./conversation.md) - Uses settings to determine if comments are enabled diff --git a/docs/components/conversation.md b/docs/components/conversation.md new file mode 100644 index 00000000..0936b925 --- /dev/null +++ b/docs/components/conversation.md @@ -0,0 +1,184 @@ +--- +myst: + html_meta: + "description": "Conversation component in plone.app.discussion" + "property=og:description": "Conversation component in plone.app.discussion" + "property=og:title": "Conversation Component" + "keywords": "Plone, Discussion, Conversation, IConversation" +--- + +# Conversation Component + +## Overview + +The Conversation component is the container for comments in the plone.app.discussion system. Each content object that allows commenting has an associated Conversation object, which is stored as an annotation on the content. + +## Interfaces + +### IConversation + +The primary interface for conversations is `IConversation`, defined in `plone.app.discussion.interfaces`: + +```python +class IConversation(IIterableMapping): + """A conversation about a content object. + + This is a persistent object in its own right and manages all comments. + + The dict interface allows access to all comments. They are stored by + long integer key, in the order they were added. + """ + + total_comments = schema.Int( + title=_("Total number of public comments on this item"), + min=0, + readonly=True, + ) + + last_comment_date = schema.Date( + title=_("Date of the most recent public comment"), + readonly=True, + ) + + commentators = schema.Set( + title=_("The set of commentators (usernames)"), + readonly=True, + ) +``` + +### IReplies + +The `IReplies` interface represents the set of replies to a specific comment or the top-level comments in a conversation: + +```python +class IReplies(IIterableMapping): + """A set of related comments. + + This is a dict-like object that can be used to access comments that are + either direct replies to a content object (i.e. the root comments in a + conversation) or replies to another comment. + """ +``` + +## Implementation + +The `Conversation` class implements the `IConversation` interface: + +```python +@implementer(IConversation, IHideFromBreadcrumbs) +class Conversation(Traversable, Persistent, Explicit): + """A conversation about a content object. + + This implements a dict-like API for accessing comments by id. + """ +``` + +Two adapter implementations provide the `IReplies` interface: + +1. `ConversationReplies` - For top-level comments in a conversation +2. `CommentReplies` - For replies to a specific comment + +## Storage Model + +The conversation maintains three dictionary-like structures: + +1. `_comments` - Maps comment IDs to actual comment objects +2. `_children` - Maps IDs (including 0 for the root) to sets of child comment IDs +3. `_depths` - Cache of comment depths for efficient retrieval + +## Key Methods + +### Comment Management + +- `addComment(comment)` - Adds a comment to the conversation +- `__delitem__(key)` - Removes a comment from the conversation +- `getComments()` - Returns an iterator of all comments +- `getThreads()` - Returns an iterator of all comments with their depths + +### Collection-like Methods + +- `__getitem__(key)` - Retrieves a comment by ID +- `get(key, default=None)` - Retrieves a comment by ID with a default value +- `keys()` - Returns all comment IDs +- `values()` - Returns all comments +- `items()` - Returns (id, comment) pairs +- `__iter__()` - Iterates over comment IDs + +### Enabling Comments + +The conversation object has a method to check if commenting is enabled on its content: + +```python +def enabled(self): + """Return True if commenting is enabled on this conversation.""" +``` + +This is implemented in the `ConversationView` class, which considers: + +1. Global settings from `IDiscussionSettings` +2. Content-specific settings (the `allow_discussion` attribute) +3. Content type settings from `portal_types` + +## Usage + +### Getting a Conversation + +```python +from plone.app.discussion.interfaces import IConversation + +conversation = IConversation(context) +``` + +### Adding a Comment + +```python +from zope.component import createObject + +comment = createObject("plone.Comment") +comment.text = "This is a comment" + +comment_id = conversation.addComment(comment) +``` + +### Accessing Comments + +```python +# Get a specific comment +comment = conversation.get(comment_id) + +# Iterate through all comments +for comment in conversation.values(): + print(comment.text) + +# Get only top-level comments +from plone.app.discussion.interfaces import IReplies +for comment in IReplies(conversation).values(): + print(comment.text) + +# Get replies to a specific comment +for reply in IReplies(comment).values(): + print(reply.text) +``` + +### Deleting Comments + +```python +# Delete a comment +del conversation[comment_id] +``` + +## Traversal + +Conversations can be traversed to via the `++conversation++default` namespace: + +``` +path/to/content/++conversation++default/123 +``` + +retrieves comment 123 from the conversation of the content object. + +## Related Components + +- [Comment](./comment.md) - The comment objects stored in conversations +- [Behavior](./behavior.md) - Controls whether commenting is enabled +- [Viewlet](./viewlet.md) - Displays the conversation UI diff --git a/docs/components/events.md b/docs/components/events.md new file mode 100644 index 00000000..0273b6a4 --- /dev/null +++ b/docs/components/events.md @@ -0,0 +1,207 @@ +--- +myst: + html_meta: + "description": "Events in plone.app.discussion" + "property=og:description": "Events in plone.app.discussion" + "property=og:title": "Discussion Events" + "keywords": "Plone, Discussion, Events, Notifications" +--- + +# Discussion Events + +## Overview + +plone.app.discussion provides a rich set of events that are triggered during various comment operations. These events allow for extending the functionality of the discussion system through event subscribers. + +## Event Types + +### Base Events + +All discussion events inherit from the base `IDiscussionEvent` interface: + +```python +class IDiscussionEvent(Interface): + """Base interface for discussion events.""" + + object = Attribute("The comment that is subject of the event") + comment = Attribute("Alias for 'object'") +``` + +### Comment Addition + +```python +class ICommentAddedEvent(IDiscussionEvent): + """Event fired when a comment is added.""" + +class IReplyAddedEvent(ICommentAddedEvent): + """Event fired when a reply is added.""" +``` + +### Comment Modification + +```python +class ICommentModifiedEvent(IDiscussionEvent): + """Event fired when a comment is modified.""" + +class IReplyModifiedEvent(ICommentModifiedEvent): + """Event fired when a reply is modified.""" +``` + +### Comment Removal + +```python +class ICommentRemovedEvent(IDiscussionEvent): + """Event fired when a comment is removed.""" + +class IReplyRemovedEvent(ICommentRemovedEvent): + """Event fired when a reply is removed.""" +``` + +### Comment Workflow + +```python +class ICommentTransitionEvent(IDiscussionEvent): + """Event fired when a workflow transition is performed on a comment.""" + + old_state = Attribute("Old workflow state") + new_state = Attribute("New workflow state") + transition = Attribute("Transition performed") + +class ICommentPublishedEvent(ICommentTransitionEvent): + """Event fired when a comment is published.""" +``` + +## Event Implementation + +Events are implemented in `plone.app.discussion.events`: + +```python +@implementer(IDiscussionEvent) +class DiscussionEvent: + """Custom event""" + + def __init__(self, object): + self.object = object + self.comment = object + +@implementer(ICommentAddedEvent) +class CommentAddedEvent(DiscussionEvent): + """Event to be triggered when a Comment is added""" + +@implementer(ICommentModifiedEvent) +class CommentModifiedEvent(DiscussionEvent): + """Event to be triggered when a Comment is modified""" + +# etc. +``` + +## Email Notifications + +One of the primary uses of discussion events is triggering email notifications. + +### Moderator Notifications + +When a comment is added and moderation is enabled, an email is sent to moderators: + +```python +def notify_comment_added(event): + """Event handler for sending emails when comments are added.""" + + registry = getUtility(IRegistry) + settings = registry.forInterface(IDiscussionSettings, check=False) + + if settings.moderator_notification_enabled: + # Send email to moderators +``` + +### User Notifications + +When a reply is added to a user's comment, the user can receive a notification: + +```python +def notify_user_reply_added(event): + """Event handler for sending emails to users on replies.""" + + registry = getUtility(IRegistry) + settings = registry.forInterface(IDiscussionSettings, check=False) + + if settings.user_notification_enabled and IReplyAddedEvent.providedBy(event): + # Send email to the author of the parent comment +``` + +## Subscribing to Events + +To subscribe to discussion events, use the standard Zope event system: + +```python +from plone.app.discussion.interfaces import ICommentAddedEvent +from zope.component import adapter + +@adapter(ICommentAddedEvent) +def my_comment_added_handler(event): + """Handle comment added event.""" + comment = event.object + # Do something with the comment +``` + +Register the subscriber in ZCML: + +```xml + +``` + +## Content Rules Integration + +Discussion events can be leveraged in Plone's content rules system: + +1. Events are exposed as content rule triggers +2. This allows site administrators to create custom rules for comment events +3. Rules can send notifications, move comments, tag content, etc. + +## Content Rule Conditions + +The `contentrules.py` module defines several conditions for content rules: + +```python +class CommentAuthorCondition(SimpleCondition): + """Content rule condition: comment author is a specific user.""" + + author_name = schema.TextLine(title=_(u"Username"), + description=_(u"The username to check for"), + required=True) + + def evaluate(self): + comment = self.event.object + if IComment.providedBy(comment): + return comment.author_username == self.data.author_name + return False +``` + +Available conditions include: + +- `ICommentAuthorCondition` - Comment was authored by a specific user +- `ICommentTextCondition` - Comment text matches a pattern +- `ICommentInReplyToCondition` - Comment is a reply to a specific comment + +## Custom Event Subscribers + +You can implement your own custom event subscribers, for example: + +```python +from plone.app.discussion.interfaces import ICommentAddedEvent + +@adapter(ICommentAddedEvent) +def log_comment_activity(event): + """Log comment activity to a custom log file.""" + comment = event.object + logger = logging.getLogger('comment_activity') + logger.info(f"Comment added by {comment.author_name} on {comment.creation_date}") +``` + +## Related Components + +- [Comment](./comment.md) - The objects that generate events +- [Moderation](./moderation.md) - Workflow transitions that generate events diff --git a/docs/components/form.md b/docs/components/form.md new file mode 100644 index 00000000..0825035a --- /dev/null +++ b/docs/components/form.md @@ -0,0 +1,155 @@ +--- +myst: + html_meta: + "description": "Comment form in plone.app.discussion" + "property=og:description": "Comment form in plone.app.discussion" + "property=og:title": "Comment Form" + "keywords": "Plone, Discussion, Comment Form" +--- + +# Comment Form + +## Overview + +The Comment Form is the UI component that allows users to add and edit comments. It's implemented using z3c.form and supports extensibility through the plone.z3cform extensible form mechanism. + +## Implementation + +### CommentForm + +The main `CommentForm` class is defined in `plone.app.discussion.browser.comments`: + +```python +class CommentForm(extensible.ExtensibleForm, form.Form): + """Comment form. + + Provides a form for adding and editing comments. + """ + + ignoreContext = True # don't use context to get widget data + id = None + label = _("Add a comment") + fields = field.Fields(IComment).omit( + "portal_type", + "__parent__", + "__name__", + "comment_id", + "mime_type", + "creator", + "creation_date", + "modification_date", + "author_username", + "title", + ) +``` + +### EditCommentForm + +The `EditCommentForm` class extends `CommentForm` for editing existing comments: + +```python +class EditCommentForm(CommentForm): + """Form to edit an existing comment. + + Extends the CommentForm with additional functionality for editing. + """ + + label = _("Edit comment") + + @button.buttonAndHandler(_("update_comment", default="Update Comment"), name="comment") + def handleComment(self, action): + # Handle comment update +``` + +## Form Fields + +The standard fields in the comment form are: + +- `text` - The main comment content +- `author_name` - For anonymous users +- `author_email` - For anonymous users +- `user_notification` - Email notification option + +## Form Behavior + +### Adding Comments + +When a user submits a comment: + +1. The form validates the input data +2. Captcha is verified if enabled +3. A new Comment object is created +4. Author information is set based on the user (anonymous or authenticated) +5. The comment is added to the conversation +6. The user is redirected back to the page + +### Editing Comments + +When editing a comment: + +1. Form is pre-populated with comment data +2. User edits the comment +3. On submit, the comment is updated +4. The user is redirected back to the page + +## Extensibility + +The form uses `plone.z3cform`'s extensible form pattern, which allows add-ons to extend the form with additional fields: + +```python +from plone.z3cform.fieldsets import extensible + +class CommentForm(extensible.ExtensibleForm, form.Form): + """Comment form with extension points.""" +``` + +Example of how an add-on could extend the form: + +```python +from plone.app.discussion.browser.comments import CommentForm +from plone.z3cform.fieldsets.extensible import FormExtender +from z3c.form import field + +class CaptchaExtender(FormExtender): + def __init__(self, context, request, form): + self.context = context + self.request = request + self.form = form + + def update(self): + # Add captcha field to the form + self.add(field.Fields(ICaptcha), group=None) +``` + +## CAPTCHA Integration + +The form supports several CAPTCHA solutions via adapters: + +- `plone.formwidget.captcha` - Simple captcha +- `plone.formwidget.recaptcha` - Google reCAPTCHA +- `collective.z3cform.norobots` - Question-based captcha +- `plone.formwidget.hcaptcha` - HCaptcha integration + +## Integration with Discussion Settings + +The form behavior is influenced by several settings from the Discussion Control Panel: + +- `globally_enabled` - If comments are enabled globally +- `anonymous_comments` - If anonymous users can comment +- `captcha` - Type of CAPTCHA to use +- `text_transform` - Text transformation for comments +- `moderation_enabled` - If comments require moderation + +## Reply Form + +For replies to existing comments: + +1. The JavaScript copies the comment form near the comment being replied to +2. The `in_reply_to` field is set to the parent comment ID +3. The form behavior remains the same otherwise + +## Related Components + +- [Comment](./comment.md) - The object created by the form +- [Viewlet](./viewlet.md) - Displays the form in the context of the page +- [Control Panel](./controlpanel.md) - Configures form behavior diff --git a/docs/components/index.md b/docs/components/index.md new file mode 100644 index 00000000..e10aed75 --- /dev/null +++ b/docs/components/index.md @@ -0,0 +1,35 @@ +--- +myst: + html_meta: + "description": "Components of plone.app.discussion" + "property=og:description": "Components of plone.app.discussion" + "property=og:title": "Components" + "keywords": "Plone, Discussion, Comments, Components" +--- + +# Components + +This section provides detailed documentation for each component in the plone.app.discussion addon. + +## Core Components + +- [Comment](./comment.md) - The Comment object that stores user comments +- [Conversation](./conversation.md) - The container for comments +- [Behavior](./behavior.md) - The behavior that enables discussion on content types + +## User Interface + +- [Form](./form.md) - The comment form for adding and editing comments +- [Viewlet](./viewlet.md) - The viewlet that displays comments +- [Moderation](./moderation.md) - The moderation views and functionality +- [Control Panel](./controlpanel.md) - The settings control panel + +## Integration & Extensions + +- [Events](./events.md) - Events triggered by the discussion system +- [REST API](./restapi.md) - Integration with plone.restapi +- [Tool](./tool.md) - The portal_discussion tool + +## Utilities + +- [Catalog](./catalog.md) - Comment indexing in the portal_catalog diff --git a/docs/components/moderation.md b/docs/components/moderation.md new file mode 100644 index 00000000..71bfdfbe --- /dev/null +++ b/docs/components/moderation.md @@ -0,0 +1,139 @@ +--- +myst: + html_meta: + "description": "Comment moderation in plone.app.discussion" + "property=og:description": "Comment moderation in plone.app.discussion" + "property=og:title": "Comment Moderation" + "keywords": "Plone, Discussion, Comment, Moderation" +--- + +# Comment Moderation + +## Overview + +The comment moderation system in plone.app.discussion provides tools for moderating comments before they are published. It includes a moderation view, bulk action capabilities, and workflow integration. + +## Comment Workflows + +Comments can be subject to two different workflows: + +1. **comment_one_state_workflow** - Comments are immediately published +2. **comment_review_workflow** - Comments require moderation before publishing + +The workflow setting is controlled at the portal_workflow level for the "Discussion Item" portal type. + +## Moderation View + +The moderation view is provided by the `View` class in `plone.app.discussion.browser.moderation`: + +```python +class View(BrowserView): + """Show comment moderation view.""" + + template = ViewPageTemplateFile("moderation.pt") +``` + +### Features + +The moderation view provides: + +1. A list of all comments pending moderation +2. Search/filter capabilities +3. Bulk action capabilities (publish, delete) +4. Individual comment action buttons + +### Accessing the View + +The view is accessible at `@@moderate-comments` on any site or folder: + +- Site level: `http://example.com/@@moderate-comments` +- Folder level: `http://example.com/folder/@@moderate-comments` + +### Moderation at Different Levels + +Comments can be moderated at different levels: + +- Site level: All comments across the site +- Folder level: Only comments in that folder and its subfolders +- Content item level: Only comments on a specific content item + +### Permissions + +The moderation view requires the "Review comments" permission, which is granted to: + +- Site Administrators +- Managers +- Reviewers (if the role has been given the permission) + +## Bulk Actions + +The bulk actions functionality allows moderators to perform actions on multiple comments at once: + +```python +class BulkActionsView(BrowserView): + """Bulk actions for comment moderation.""" + + def __call__(self): + """Execute bulk actions.""" + req = self.request + context = self.context + + # Get all comment ids from the request + comment_ids = req.get('comment_id', []) + + # Determine the action + action = req.get('action', None) + + if action == 'publish': + self.publish(comment_ids) + elif action == 'delete': + self.delete(comment_ids) + + return req.RESPONSE.redirect(context.absolute_url() + '/@@moderate-comments') +``` + +The available bulk actions are: + +1. **Publish** - Marks the selected comments as published +2. **Delete** - Deletes the selected comments + +## Auto-Approve + +plone.app.discussion supports auto-approving comments from trusted users: + +1. Users with "Review comments" permission have their comments auto-approved +2. This happens even when moderation is enabled globally +3. Auto-approval can be managed through permissions rather than hard-coding lists of trusted users + +## Workflow Transitions + +Comment workflows define several transitions: + +1. **publish** - Publishes a pending comment +2. **reject** - Rejects a pending comment (doesn't delete it) +3. **retract** - Unpublishes a published comment + +## Workflow State Flags + +The comment moderation view shows the review state of comments: + +- **pending** - Comment is waiting for moderation +- **published** - Comment is approved and visible +- **rejected** - Comment was rejected but not deleted + +## Multiple State View + +For workflows with multiple states, a specialized view shows comments grouped by their workflow state: + +```python +class MultipleStateView(View): + """Comment moderation view for workflows with multiple states.""" +``` + +This view extends the standard moderation view with filters for different workflow states. + +## Related Components + +- [Comment](./comment.md) - The objects being moderated +- [Control Panel](./controlpanel.md) - Global moderation settings +- [Events](./events.md) - Events triggered during moderation diff --git a/docs/components/restapi.md b/docs/components/restapi.md new file mode 100644 index 00000000..86d57b1e --- /dev/null +++ b/docs/components/restapi.md @@ -0,0 +1,239 @@ +--- +myst: + html_meta: + "description": "REST API integration in plone.app.discussion" + "property=og:description": "REST API integration in plone.app.discussion" + "property=og:title": "Discussion REST API" + "keywords": "Plone, Discussion, REST API, Volto" +--- + +# REST API Integration + +## Overview + +plone.app.discussion provides integration with plone.restapi to enable managing comments through REST API endpoints. This is particularly useful for JavaScript frontends like Volto. + +## Control Panel Integration + +The discussion settings are exposed through the REST API control panel endpoint: + +```python +@adapter(Interface, IControlpanelLayer) +class DiscussionControlPanel(RegistryConfigletPanel): + """Volto-compatible REST API control panel for discussion settings.""" + + schema = IDiscussionSettings + schema_prefix = None + configlet_id = "discussion" + configlet_category_id = "plone-content" + title = _("Discussion") + group = "Content" +``` + +This allows Volto and other clients to: + +- Retrieve the current discussion settings +- Modify the discussion settings +- Access the settings schema for generating UI forms + +### Accessing Settings via REST API + +```http +GET /@controlpanels/discussion HTTP/1.1 +Accept: application/json +``` + +Response: + +```json +{ + "@id": "http://localhost:8080/Plone/@controlpanels/discussion", + "title": "Discussion", + "group": "Content", + "schema": { + "fieldsets": [ + { + "id": "default", + "title": "Default", + "fields": ["globally_enabled", "moderation_enabled", ...] + } + ], + "properties": { + "globally_enabled": { + "title": "Globally enable comments", + "description": "Enable comments globally", + "type": "boolean", + "default": false + }, + "moderation_enabled": { + "title": "Comment moderation", + "description": "Require moderation for all comments", + "type": "boolean", + "default": false + }, + // Additional properties + } + }, + "data": { + "globally_enabled": true, + "moderation_enabled": false, + // Additional data + } +} +``` + +### Updating Settings via REST API + +```http +PATCH /@controlpanels/discussion HTTP/1.1 +Accept: application/json +Content-Type: application/json + +{ + "globally_enabled": true, + "moderation_enabled": true +} +``` + +## Comments Endpoints + +Comments can be accessed and manipulated through content-related endpoints: + +### Getting Comments + +```http +GET /plone/document/@comments HTTP/1.1 +Accept: application/json +``` + +Response: + +```json +{ + "@id": "http://localhost:8080/Plone/document/@comments", + "items_total": 2, + "items": [ + { + "@id": "http://localhost:8080/Plone/document/@comments/123456789", + "@type": "Discussion Item", + "comment_id": "123456789", + "author_name": "John Doe", + "text": "This is a comment", + "creation_date": "2023-01-15T10:00:00", + "modification_date": "2023-01-15T10:00:00", + "is_editable": false, + "is_deletable": false, + // Additional fields + }, + // More comments + ] +} +``` + +### Adding a Comment + +```http +POST /plone/document/@comments HTTP/1.1 +Accept: application/json +Content-Type: application/json + +{ + "text": "My comment text", + "user_notification": true +} +``` + +Response: + +```json +{ + "@id": "http://localhost:8080/Plone/document/@comments/987654321", + "@type": "Discussion Item", + "comment_id": "987654321", + "author_name": "Jane Smith", + "text": "My comment text", + "creation_date": "2023-01-15T11:00:00", + "modification_date": "2023-01-15T11:00:00", + // Additional fields +} +``` + +### Adding a Reply + +To add a reply to a specific comment: + +```http +POST /plone/document/@comments HTTP/1.1 +Accept: application/json +Content-Type: application/json + +{ + "text": "My reply text", + "in_reply_to": "123456789" +} +``` + +### Updating a Comment + +```http +PATCH /plone/document/@comments/123456789 HTTP/1.1 +Accept: application/json +Content-Type: application/json + +{ + "text": "Updated comment text" +} +``` + +### Deleting a Comment + +```http +DELETE /plone/document/@comments/123456789 HTTP/1.1 +Accept: application/json +``` + +## Comment Moderation via REST API + +Comment moderation actions can also be triggered via REST API: + +### Publishing a Comment + +```http +POST /plone/document/@comments/123456789/publish HTTP/1.1 +Accept: application/json +``` + +### Transition Endpoint + +A general transition endpoint allows any workflow transition: + +```http +POST /plone/document/@comments/123456789/@workflow/reject HTTP/1.1 +Accept: application/json +``` + +## Implementation Details + +The plone.restapi integration is conditionally registered only when plone.restapi is installed: + +```python +try: + from plone.restapi.interfaces import IControlpanelLayer +except ImportError: + IControlpanelLayer = Interface +``` + +This approach ensures that the REST API components are only active when needed. + +## Use with Volto + +The REST API integration is particularly useful with Volto, Plone's React-based frontend: + +1. Volto uses the `@comments` endpoint to display comments +2. The control panel integration allows managing discussion settings in Volto +3. Comment forms in Volto submit to the REST API endpoints + +## Related Components + +- [Comment](./comment.md) - The objects exposed via REST API +- [Control Panel](./controlpanel.md) - Settings accessible via REST API diff --git a/docs/components/tool.md b/docs/components/tool.md new file mode 100644 index 00000000..879ef94b --- /dev/null +++ b/docs/components/tool.md @@ -0,0 +1,202 @@ +--- +myst: + html_meta: + "description": "Discussion tool in plone.app.discussion" + "property=og:description": "Discussion tool in plone.app.discussion" + "property=og:title": "Discussion Tool" + "keywords": "Plone, Discussion, CommentingTool" +--- + +# Discussion Tool + +## Overview + +The `portal_discussion` tool provides centralized functionality for indexing and searching comments in plone.app.discussion. It's an instance of the `CommentingTool` class. + +## Implementation + +The tool is defined in `plone.app.discussion.tool`: + +```python +@interface.implementer(ICommentingTool) +class CommentingTool(UniqueObject, SimpleItem): + """plone.app.discussion tool. + + The primary purpose of this tool is indexing and searching comments. + """ + + meta_type = "plone.app.discussion tool" + id = "portal_discussion" +``` + +## Interface + +The tool implements the `ICommentingTool` interface: + +```python +class ICommentingTool(Interface): + """plone.app.discussion tool interface. + + This tool provides comment-specific functionality like searching for + comments. + """ +``` + +## Functions + +### Indexing Comments + +The tool provides functions for indexing comments in the portal_catalog: + +```python +def reindexObject(self, object): + """Reindex the comment in the catalog.""" + catalog = getToolByName(self, "portal_catalog") + catalog.reindexObject(object) + +indexObject = reindexObject # Alias for backward compatibility + +def unindexObject(self, object): + """Remove the comment from the catalog.""" + catalog = getToolByName(self, "portal_catalog") + catalog.unindexObject(object) +``` + +### Searching for Comments + +The tool provides a specialized search function that limits results to comments: + +```python +def searchResults(self, REQUEST=None, **kw): + """Search the catalog for comments. + + Calls ZCatalog.searchResults with extra arguments that limit the + results to comments (objects providing IComment). + """ + catalog = getToolByName(self, "portal_catalog") + object_provides = [IComment.__identifier__] + + # Add any object_provides from the request or kw + # ... + + kw["object_provides"] = object_provides + return catalog.searchResults(REQUEST, **kw) +``` + +### Retrieving Unique Values + +The tool allows retrieving unique values for specific catalog indexes: + +```python +def uniqueValuesFor(self, name): + """Return unique values for a specific metadata column of comments.""" + catalog = getToolByName(self, "portal_catalog") + return catalog.uniqueValuesFor(name) +``` + +## Event Subscribers + +The module also defines event subscribers for indexing and unindexing comments: + +```python +def index_object(obj, event): + """Index the object when added to the conversation""" + # Skip if object isn't a comment + if not IComment.providedBy(obj): + return + + tool = queryUtility(ICommentingTool) + if tool is not None: + tool.indexObject(obj) + +def unindex_object(obj, event): + """Unindex the object when removed""" + # Skip if object isn't a comment + if not IComment.providedBy(obj): + return + + tool = queryUtility(ICommentingTool) + if tool is not None: + tool.unindexObject(obj) +``` + +## Backward Compatibility + +The tool provides backward compatibility with the old `portal_discussion` tool from Plone < 4.1: + +```python +"""The portal_discussion tool, usually accessed via +queryUtility(ICommentingTool). The default implementation delegates to the +standard portal_catalog for indexing comments. + +BBB support for the old portal_discussion is provided in the bbb package. +""" +``` + +## Installation + +The tool is installed as part of the plone.app.discussion installation profile: + +```xml + +``` + +## Usage Examples + +### Finding Recent Comments + +```python +from zope.component import queryUtility +from plone.app.discussion.interfaces import ICommentingTool + +def get_recent_comments(context, limit=10): + tool = queryUtility(ICommentingTool) + if tool is None: + return [] + + results = tool.searchResults( + sort_on='created', + sort_order='reverse', + sort_limit=limit, + ) + + return [r.getObject() for r in results[:limit]] +``` + +### Finding Comments by Author + +```python +def get_comments_by_author(context, author): + tool = queryUtility(ICommentingTool) + if tool is None: + return [] + + results = tool.searchResults( + Creator=author, + sort_on='created', + sort_order='reverse', + ) + + return [r.getObject() for r in results] +``` + +### Finding Comments by Content Path + +```python +def get_comments_for_content(context, content_path): + tool = queryUtility(ICommentingTool) + if tool is None: + return [] + + results = tool.searchResults( + path=content_path, + sort_on='created', + ) + + return [r.getObject() for r in results] +``` + +## Related Components + +- [Comment](./comment.md) - The objects indexed by the tool +- [Catalog](./catalog.md) - Comment indexing in the portal_catalog diff --git a/docs/components/viewlet.md b/docs/components/viewlet.md new file mode 100644 index 00000000..f1004aeb --- /dev/null +++ b/docs/components/viewlet.md @@ -0,0 +1,198 @@ +--- +myst: + html_meta: + "description": "Comments viewlet in plone.app.discussion" + "property=og:description": "Comments viewlet in plone.app.discussion" + "property=og:title": "Comments Viewlet" + "keywords": "Plone, Discussion, Comments Viewlet" +--- + +# Comments Viewlet + +## Overview + +The Comments Viewlet is the UI component that displays the comments list and comment form at the bottom of content pages. It's implemented as a Plone viewlet, which means it can be easily placed in different locations in the page layout. + +## Implementation + +The comments viewlet is defined in `plone.app.discussion.browser.comments`: + +```python +class CommentsViewlet(ViewletBase): + """Discussion Viewlet. + + Renders the comments viewing and posting UI. + """ + + index = ViewPageTemplateFile("comments.pt") + + def update(self): + """Prepare the viewlet for rendering. + """ + super(CommentsViewlet, self).update() + self.portal_discussion = getToolByName(self.context, 'portal_discussion', None) + self.request.set('disable_border', True) +``` + +## Main Features + +The viewlet provides: + +1. Display of existing comments +2. Threading of comments into conversations +3. Integration of the comment form +4. User interface for comment moderation + +## Display of Comments + +The viewlet retrieves comments from the conversation and displays them in a hierarchical structure: + +```python +def getThreads(self, comment_id=0, depth=0): + """Get threaded comments. + + Returns a list of dicts with comment for display in the comment viewlet. + """ + conversation = IConversation(self.context) + return conversation.getThreads(comment_id, depth) +``` + +Each comment is displayed with: +- Author name/information +- Comment date +- Comment text +- Reply link (if authenticated) +- Edit/Delete links (if user has permission) + +## Comment Threading + +Comments are displayed in a threaded view, showing replies indented beneath their parent comments: + +```python +def getThreads(self, comment_id, depth): + """Return all threads in a nested structure. + """ + conversation = IConversation(self.context) + + threads = [] + for comment in conversation.getComments(comment_id): + thread = {'comment': comment, 'depth': depth} + thread['children'] = self.getThreads(comment.comment_id, depth + 1) + threads.append(thread) + + return threads +``` + +## User Interface Conditionals + +The viewlet contains logic to determine which UI elements to show: + +```python +def can_reply(self): + """Check if the user can reply to comments. + """ + return getSecurityManager().checkPermission('Reply to item', self.context) + +def can_manage(self): + """Check if the user can manage comments. + """ + return getSecurityManager().checkPermission('Manage portal', self.context) + +def is_discussion_allowed(self): + """Check if discussion is allowed for this viewlet. + """ + return self.context.restrictedTraverse('@@conversation_view').enabled() +``` + +## Integration with Comment Form + +The viewlet includes the comment form: + +```python +def comment_form(self): + """Return the comment form. + """ + context = aq_inner(self.context) + request = self.request + + form = getMultiAdapter((context, request), name='comment-form') + form.update() + + return form +``` + +## Template Structure + +The viewlet's template (`comments.pt`) includes: + +1. Header section showing the number of comments +2. Comments listing with threading +3. Comment form for adding new comments +4. JavaScript for interactivity (showing/hiding the form, reply functionality) + +## Customizing the Viewlet + +The viewlet can be customized in several ways: + +### CSS Classes + +The viewlet includes numerous CSS hooks for styling: + +- `.discussion` - Main container +- `.comment` - Individual comment +- `.commentImage` - Comment author image +- `.commentBody` - Comment text and metadata +- `.documentByLine` - Comment metadata (author, date) +- `.commentActions` - Reply, edit, delete links + +### Template Override + +The template can be overridden using Plone's template overrides: + +1. Create a `browser/overrides/plone.app.discussion.browser.comments.pt` in your package +2. Register it with ZCML: + +```xml + + + +``` + +### Custom Viewlet Class + +You can create a custom viewlet class that inherits from the standard one: + +```python +from plone.app.discussion.browser.comments import CommentsViewlet + +class MyCommentsViewlet(CommentsViewlet): + """Enhanced comments viewlet with custom functionality.""" + + def update(self): + super(MyCommentsViewlet, self).update() + # Add custom logic +``` + +And register it: + +```xml + +``` + +## Related Components + +- [Comment](./comment.md) - The objects displayed in the viewlet +- [Form](./form.md) - The comment form integrated in the viewlet +- [Conversation](./conversation.md) - Provides the comments data structure diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..2bd4e7c7 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,65 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'plone.app.discussion' +copyright = '2025, Plone Foundation' +author = 'Plone Foundation' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.doctest', + 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', + 'sphinx.ext.coverage', + 'myst_parser', + 'sphinx_design', + 'sphinx_copybutton', +] + +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# -- MyST configuration --------------------------------------------------- + +myst_enable_extensions = [ + "amsmath", + "colon_fence", + "deflist", + "dollarmath", + "html_admonition", + "html_image", + "linkify", + "replacements", + "smartquotes", + "substitution", + "tasklist", +] + +myst_heading_anchors = 3 + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'furo' +html_static_path = ['_static'] + +# -- Options for intersphinx extension --------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration + +intersphinx_mapping = { + 'python': ('https://docs.python.org/3', None), + 'sphinx': ('https://www.sphinx-doc.org/en/master', None), +} + +# -- Options for todo extension ---------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/extensions/todo.html#configuration + +todo_include_todos = True diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..1574ae93 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,54 @@ +--- +myst: + html_meta: + "description": "plone.app.discussion documentation" + "property=og:description": "plone.app.discussion documentation" + "property=og:title": "plone.app.discussion" + "keywords": "Plone, Discussion, Comments" +--- + +# plone.app.discussion + +`plone.app.discussion` is the commenting add-on for Plone. + +## Introduction + +`plone.app.discussion` provides a flexible commenting system for Plone sites. It allows site visitors and members to comment on content objects, with full moderation capabilities and various configuration options. + +## Features + +- Comment moderation +- Threaded comments +- Email notifications +- Spam protection integration +- Customizable workflows +- Support for anonymous commenting +- Integration with Plone security model + +## Installation + +If your installation depends on the `Plone` package, you can install it via the Plone control panel. +In case you do only depend on either the `plone.volto`, `plone.classicui` or `Products.CMFPlone` package, you need to add it to your requirements file. +After adding it and installing the requirement, you can install it via the Plone control panel. + +## Documentation + +```{toctree} +:maxdepth: 2 + +architecture +design +workflow +captcha +email-notification +auto-approve +components/index +api/index +howtos/index +``` + +## Indices and tables + +* [Index](genindex) +* [Module Index](modindex) +* [Search Page](search) diff --git a/requirements-docs.txt b/requirements-docs.txt new file mode 100644 index 00000000..29714f5e --- /dev/null +++ b/requirements-docs.txt @@ -0,0 +1,9 @@ +sphinx>=4.0.0 +sphinx-rtd-theme>=1.0.0 +sphinx-autobuild>=2021.3.14 +sphinx-copybutton>=0.5.0 +sphinx-design>=0.3.0 +myst-parser>=0.19.0 +jupyter-book>=0.15.1 +furo>=2022.9.29 +docutils>=0.17.1 From 8ebacfbafcd5a9ecd4878f07c27f044816f354b4 Mon Sep 17 00:00:00 2001 From: Rohan Shaw Date: Wed, 4 Jun 2025 09:59:07 +0530 Subject: [PATCH 2/4] docs: Add initial Sphinx configuration and table of contents for plone.app.discussion --- docs/_toc.yml | 19 +++++ docs/conf.py | 231 ++++++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 213 insertions(+), 37 deletions(-) create mode 100644 docs/_toc.yml diff --git a/docs/_toc.yml b/docs/_toc.yml new file mode 100644 index 00000000..8642f302 --- /dev/null +++ b/docs/_toc.yml @@ -0,0 +1,19 @@ +root: index +entries: +- file: architecture +- file: auto-approve +- file: auto_approve +- file: components/index + entries: + - file: components/behavior + - file: components/catalog + - file: components/comment + - file: components/controlpanel + - file: components/conversation + - file: components/events + - file: components/form + - file: components/moderation + - file: components/restapi + - file: components/tool + - file: components/viewlet + diff --git a/docs/conf.py b/docs/conf.py index 2bd4e7c7..0628721a 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,65 +1,222 @@ # Configuration file for the Sphinx documentation builder. -# -# For the full list of built-in configuration values, see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html +# plone.app.discussion documentation build configuration file + +# -- Path setup -------------------------------------------------------------- + +from datetime import datetime # -- Project information ----------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information -project = 'plone.app.discussion' -copyright = '2025, Plone Foundation' -author = 'Plone Foundation' +project = "plone.app.discussion" +copyright = "Plone Foundation" +author = "Plone community" +trademark_name = "Plone" +now = datetime.now() +year = str(now.year) + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = "6" +# The full version, including alpha/beta/rc tags. +release = "6" + +# -- General configuration ---------------------------------------------------- -# -- General configuration --------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] +# Add any Sphinx extension module names here, as strings. +# They can be extensions coming with Sphinx (named "sphinx.ext.*") +# or your custom ones. extensions = [ - 'sphinx.ext.autodoc', - 'sphinx.ext.doctest', - 'sphinx.ext.intersphinx', - 'sphinx.ext.todo', - 'sphinx.ext.coverage', - 'myst_parser', - 'sphinx_design', - 'sphinx_copybutton', + "myst_parser", + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.intersphinx", + "sphinx.ext.todo", + "sphinx.ext.viewcode", + "sphinx_copybutton", + "sphinx_design", + "sphinxext.opengraph", ] -templates_path = ['_templates'] -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +# If true, the Docutils Smart Quotes transform will be used to convert quotes +# and dashes to typographically correct entities. +smartquotes = False + +# Options for the linkcheck builder +linkcheck_anchors = True +linkcheck_ignore = [ + # Ignore localhost + r"http://127.0.0.1", + r"http://localhost", + # Ignore static file downloads + r"^/_static/", + r"^/_images/", + # Ignore pages that require authentication + r"https://github.com/orgs/plone/teams/", +] +linkcheck_retries = 1 +linkcheck_report_timeouts_as_broken = True +linkcheck_timeout = 5 + +# The suffix of source filenames. +source_suffix = { + ".md": "markdown", + ".rst": "restructuredtext", +} + +# The master toctree document. +master_doc = "index" + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = [ + "**.ipynb_checkpoints", + ".DS_Store", + "Thumbs.db", + "_build", + "spelling_wordlist.txt", + "**/CHANGES.md", + "**/CHANGES.rst", + "**/LICENSE.rst", + "**/CONTRIBUTORS.md", + "**/CONTRIBUTORS.rst", + "**/README.md", + "**/README.rst", +] + +suppress_warnings = [ + "toc.not_readable", + "myst.strikethrough", +] + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. +html_theme = "plone_sphinx_theme" +html_logo = "_static/logo.svg" if "_static/logo.svg" else "" +html_favicon = "_static/favicon.ico" if "_static/favicon.ico" else "" + +html_sidebars = { + "**": [ + "navbar-logo", + "search-button-field", + "sbt-sidebar-nav", + ] +} + +html_theme_options = { + "article_header_start": ["toggle-primary-sidebar"], + "extra_footer": """

The text and illustrations in this website are licensed by the Plone Foundation under a Creative Commons Attribution 4.0 International license. Plone and the Plone® logo are registered trademarks of the Plone Foundation, registered in the United States and other countries. For guidelines on the permitted uses of the Plone trademarks, see https://plone.org/foundation/logo. All other trademarks are owned by their respective owners.

""", + "footer_content_items": [ + "author", + "copyright", + "last-updated", + "extra-footer", + "icon-links", + ], + "icon_links": [ + { + "name": "GitHub", + "url": "https://github.com/plone/plone.app.discussion", + "icon": "fa-brands fa-square-github", + "type": "fontawesome", + "attributes": { + "target": "_blank", + "rel": "noopener me", + } + }, + ], + "logo": { + "text": "plone.app.discussion v" + version, + }, + "navigation_with_keys": True, + "path_to_docs": "docs", + "repository_branch": "master", + "repository_url": "https://github.com/plone/plone.app.discussion", + "search_bar_text": "Search", + "show_toc_level": 2, + "use_edit_page_button": False, + "use_issues_button": True, + "use_repository_button": True, +} + +# The name for this set of Sphinx documents. +html_title = "%(project)s v%(release)s" % {"project": project, "release": release} + +html_css_files = [] +html_js_files = [] +html_extra_path = [] -# -- MyST configuration --------------------------------------------------- +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] +# -- Options for MyST markdown conversion to HTML ----------------------------- + +# For more information see: +# https://myst-parser.readthedocs.io/en/latest/syntax/optional.html myst_enable_extensions = [ - "amsmath", + "attrs_block", + "attrs_inline", "colon_fence", "deflist", "dollarmath", - "html_admonition", + "fieldlist", "html_image", "linkify", - "replacements", - "smartquotes", + "strikethrough", "substitution", "tasklist", ] -myst_heading_anchors = 3 - -# -- Options for HTML output ------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output +myst_substitutions = {} -html_theme = 'furo' -html_static_path = ['_static'] - -# -- Options for intersphinx extension --------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration +# -- Intersphinx configuration ---------------------------------- +# This extension can generate automatic links to the documentation of objects +# in other projects. intersphinx_mapping = { - 'python': ('https://docs.python.org/3', None), - 'sphinx': ('https://www.sphinx-doc.org/en/master', None), + "plone": ("https://6.docs.plone.org/", None), + "python": ("https://docs.python.org/3/", None), } -# -- Options for todo extension ---------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/extensions/todo.html#configuration +# -- OpenGraph configuration ---------------------------------- + +ogp_site_url = "https://6.docs.plone.org/" +ogp_description_length = 200 +ogp_image = "https://6.docs.plone.org/_static/Plone_logo_square.png" +ogp_site_name = "Plone Documentation" +ogp_type = "website" + +# -- Options for sphinx.ext.todo ----------------------- todo_include_todos = True + +# -- Options for HTML help output ------------------------------------------------- + +htmlhelp_basename = "PloneAppDiscussionDocumentation" + +# -- Options for LaTeX output ------------------------------------------------- + +latex_documents = [ + ( + "index", + "PloneAppDiscussion.tex", + "plone.app.discussion Documentation", + "Plone community", + "manual", + ), +] + +latex_logo = "_static/logo_2x.png" if "_static/logo_2x.png" else "" + +# -- Configuration for custom setup ---------------------------------- + +def setup(app): + app.add_config_value("context", "documentation", "env") From 4e378fce02f1d670876539ab2e07ccb227e02995 Mon Sep 17 00:00:00 2001 From: Rohan Shaw Date: Sat, 7 Jun 2025 18:33:45 +0530 Subject: [PATCH 3/4] Fix documentation structure: ensure each reStructuredText file has a sibling Markdown file at the same location --- CHANGES.md | 1541 ++++++++++++++++ CONTRIBUTING.md | 1 + README.md | 43 + docs/CHANGES.md | 1550 +++++++++++++++++ docs/CONTRIBUTING.md | 10 + docs/README.md | 52 + docs/_toc.yml | 20 +- docs/api/comment.md | 12 + docs/api/conversation.md | 12 + docs/{source/api/index.txt => api/index.md} | 23 +- docs/architecture.md | 52 +- docs/auto_approve.rst | 44 - docs/captcha.md | 12 + docs/design.md | 12 + docs/email-notification.md | 80 + docs/howtos/howto_extend_the_comment_form.md | 173 ++ ..._pad_work_with_a_dexterity_content_type.md | 56 + .../howtos/howto_override_comments_viewlet.md | 154 ++ .../howto_override_enable_conversation.md | 80 + ..._discussion_settings_with_generic_setup.md | 127 ++ ...howto_write_a_custom_email_notification.md | 15 + docs/howtos/index.md | 21 + docs/source/api/comment.md | 12 + docs/source/api/comment.txt | 1 - docs/source/api/conversation.md | 12 + docs/source/api/conversation.txt | 1 - docs/source/api/index.md | 28 + docs/source/architecture.md | 12 + docs/source/architecture.txt | 1 - docs/source/captcha.md | 12 + docs/source/captcha.txt | 1 - docs/source/design.md | 12 + docs/source/design.txt | 1 - docs/source/email-notification.md | 80 + docs/source/email-notification.txt | 78 - .../howtos/howto_extend_the_comment_form.md | 173 ++ .../howtos/howto_extend_the_comment_form.txt | 156 -- ..._pad_work_with_a_dexterity_content_type.md | 56 + ...pad_work_with_a_dexterity_content_type.txt | 39 - .../howtos/howto_override_comments_viewlet.md | 154 ++ .../howto_override_comments_viewlet.txt | 138 -- .../howto_override_enable_conversation.md | 80 + .../howto_override_enable_conversation.txt | 68 - ..._discussion_settings_with_generic_setup.md | 127 ++ ...discussion_settings_with_generic_setup.txt | 118 -- ...howto_write_a_custom_email_notification.md | 15 + ...owto_write_a_custom_email_notification.txt | 8 - docs/source/howtos/index.md | 21 + docs/source/howtos/index.txt | 13 - docs/source/index.md | 37 + docs/source/index.txt | 33 - docs/source/{workflow.txt => workflow.md} | 79 +- docs/workflow.md | 105 ++ 53 files changed, 4967 insertions(+), 794 deletions(-) create mode 100644 CHANGES.md create mode 100644 CONTRIBUTING.md create mode 100644 README.md create mode 100644 docs/CHANGES.md create mode 100644 docs/CONTRIBUTING.md create mode 100644 docs/README.md create mode 100644 docs/api/comment.md create mode 100644 docs/api/conversation.md rename docs/{source/api/index.txt => api/index.md} (62%) delete mode 100644 docs/auto_approve.rst create mode 100644 docs/captcha.md create mode 100644 docs/design.md create mode 100644 docs/email-notification.md create mode 100644 docs/howtos/howto_extend_the_comment_form.md create mode 100644 docs/howtos/howto_make_pad_work_with_a_dexterity_content_type.md create mode 100644 docs/howtos/howto_override_comments_viewlet.md create mode 100644 docs/howtos/howto_override_enable_conversation.md create mode 100644 docs/howtos/howto_set_discussion_settings_with_generic_setup.md create mode 100644 docs/howtos/howto_write_a_custom_email_notification.md create mode 100644 docs/howtos/index.md create mode 100644 docs/source/api/comment.md delete mode 100644 docs/source/api/comment.txt create mode 100644 docs/source/api/conversation.md delete mode 100644 docs/source/api/conversation.txt create mode 100644 docs/source/api/index.md create mode 100644 docs/source/architecture.md delete mode 100644 docs/source/architecture.txt create mode 100644 docs/source/captcha.md delete mode 100644 docs/source/captcha.txt create mode 100644 docs/source/design.md delete mode 100644 docs/source/design.txt create mode 100644 docs/source/email-notification.md delete mode 100644 docs/source/email-notification.txt create mode 100644 docs/source/howtos/howto_extend_the_comment_form.md delete mode 100644 docs/source/howtos/howto_extend_the_comment_form.txt create mode 100644 docs/source/howtos/howto_make_pad_work_with_a_dexterity_content_type.md delete mode 100644 docs/source/howtos/howto_make_pad_work_with_a_dexterity_content_type.txt create mode 100644 docs/source/howtos/howto_override_comments_viewlet.md delete mode 100644 docs/source/howtos/howto_override_comments_viewlet.txt create mode 100644 docs/source/howtos/howto_override_enable_conversation.md delete mode 100644 docs/source/howtos/howto_override_enable_conversation.txt create mode 100644 docs/source/howtos/howto_set_discussion_settings_with_generic_setup.md delete mode 100644 docs/source/howtos/howto_set_discussion_settings_with_generic_setup.txt create mode 100644 docs/source/howtos/howto_write_a_custom_email_notification.md delete mode 100644 docs/source/howtos/howto_write_a_custom_email_notification.txt create mode 100644 docs/source/howtos/index.md delete mode 100644 docs/source/howtos/index.txt create mode 100644 docs/source/index.md delete mode 100644 docs/source/index.txt rename docs/source/{workflow.txt => workflow.md} (61%) create mode 100644 docs/workflow.md diff --git a/CHANGES.md b/CHANGES.md new file mode 100644 index 00000000..f8accb7e --- /dev/null +++ b/CHANGES.md @@ -0,0 +1,1541 @@ +# Changelog + +% You should *NOT* be adding new change log entries to this file. +% You should create a file in the news directory instead. +% For helpful instructions, please see: +% https://github.com/plone/plone.releaser/blob/master/ADD-A-NEWS-ITEM.rst + +% towncrier release notes start + +## 5.1.0 (2025-05-02) + +New features: + +- Implement auto_approve_admin_comments based on specified roles @rohnsha0 (#261) + +Bug fixes: + +- Fix improper handling of logic for showing delete button @rohnsha0 (#182) + +Internal: + +- Update configuration files. + [plone devs] + +## 5.0.0 (2025-02-06) + +Internal: + +- Make final release, no changes. [maurits] (#610) + +## 5.0.0a3 (2025-01-23) + +Bug fixes: + +- Do not depend on `plone.api`. [ale-rt] (#188) +- Fix DeprecationWarnings. [maurits] (#4090) + +## 5.0.0a2 (2024-10-23) + +New features: + +- Update robot framework tests to use + `robotframework-browser` (`playwright` integration on robotframework). + [gforcada] (#3813) + +## 5.0.0a1 (2024-09-05) + +Breaking changes: + +- Move this package in the space of Plone Core add-ons. + It now depends on Products.CMFPlone and is no longer installed by default. + It is still available in the default Plone distribution, but can be omitted in customizations. + Installing this in the Add-ons control panel will enable comments globally. + [jensens] (#211) + +Bug fixes: + +- Fix redirection after comment edit to main content, preventing NotFound. [@jensens] (#211) +- Add missing icon on comments' `view` action + Register contenttype icon for comments. + [gforcada, maurits] (#222) + +## 4.1.2 (2024-04-16) + +Internal: + +- Add capture screen in robot tests to debug. @wesleybl (#235) +- Fix robot test `Add a Comment to a Document and bulk delete it`. @wesleybl (#237) +- Fix robot test `Add a Comment to a Document and bulk delete it` 2. @wesleybl (#238) +- Fix robot test `Add a Comment to a Document and bulk delete it` 3. @wesleybl (#239) + +## 4.1.1 (2024-03-22) + +Bug fixes: + +- Apply validation for all captchas. @ksuess (#234) + +## 4.1.0 (2024-03-19) + +New features: + +- Provide HCaptcha if plone.formwidget.hcaptcha is installed. @ksuess (#230) + +Internal: + +- Fix test "Add a Comment to a Document and bulk delete it". @wesleybl (#228) + +## 4.0.5 (2024-03-15) + +Bug fixes: + +- Fix test "Add a Comment to a Document and bulk delete it". @wesleybl (#226) + +Internal: + +- Fix test "Add a Comment to a Document and bulk delete it" 2. @wesleybl (#227) + +## 4.0.4 (2024-02-21) + +Bug fixes: + +- Report the upgrade steps progress, + really useful for sites with lots of comments. + [gforcada] + +## 4.0.3 (2024-02-13) + +Bug fixes: + +- Do not autofocus on the comments form. + [maurits] (#3623) + +## 4.0.2 (2023-07-14) + +Internal: + +- Update configuration files. + [plone devs] (cfffba8c) + +## 4.0.1 (2023-04-14) + +Internal: + +- Remove translations folder, + for ages they are coming from p.a.locales. + [gforcada] (#1) +- Update configuration files. + [plone devs] (#47959565) + +## 4.0.0 (2022-11-11) + +Bug fixes: + +- Set timezones for creation and modification dates of comments [instification] (#204) + +## 4.0.0b3 (2022-10-11) + +Bug fixes: + +- Fix password used in tests. [davisagli] (#203) + +## 4.0.0b2 (2022-09-30) + +Bug fixes: + +- Use longer passwords in tests. [davisagli] (#203) + +## 4.0.0b1 (2022-06-23) + +Bug fixes: + +- Test-only fix: normalize white space when comparing output of `comment.getText()`. + Needed to not fail with newer `plone.outputfilters`. + [maurits] (#49) + +## 4.0.0a7 (2022-05-14) + +Breaking changes: + +- Code style black & isort. Remove six usage. Use plone.base and move annotation key over to here. + [jensens] (#195) + +Bug fixes: + +- Make compatible with robotframework 3-5. + [maurits] (#5) +- Grant Site Administrators the same workflow permissions as Managers. + They were missing permissions on pending comments. + [maurits] (#199) +- Removed z3c.autoinclude.plugin entrypoint. [maurits] (#3188) + +## 4.0.0a6 (2022-04-28) + +Bug fixes: + +- Replaced use of `plone.api`. That should not be done in Plone core. + [maurits] (#188) + +## 4.0.0a5 (2022-04-04) + +New features: + +- Moved JS to Mockup control panel patterns (ES6) [MrTango] (#190) + +## 4.0.0a4 (2022-03-23) + +New features: + +- Added 'View comments' permission. [@razvanMiu] (#180) + +## 4.0.0a3 (2021-10-16) + +Bug fixes: + +- Add missing i18n:translate tags + [erral] (#189) + +## 4.0.0a2 (2021-09-15) + +New features: + +- Refactor templates and styling for comments and controlpanel. + [santonelli] (#169) +- Implement events for Comment (ICommentModifiedEvent) and Reply(IReplyModifiedEvent) modification [ericof] (#183) + +Bug fixes: + +- Fix tests with Products.MailHost 4.11. + [maurits] (#174) +- Remove cyclic dependency with Products.CMFPlone + [ericof] (#186) + +## 4.0.0a1 (2021-04-21) + +New features: + +- Refactor templates and styling for comments and controlpanel. + [santonelli] (#169) +- Cleanup template and move message to python code. + [santonelli] (#177) + +Bug fixes: + +- Fix tests with Products.MailHost 4.11. + [maurits] (#174) + +## 3.4.4 (2020-10-09) + +New features: + +- Update templates markup to Bootstrap 4. + [andreesg] + +## 3.4.3 (2020-09-28) + +Bug fixes: + +- Fix tests with Products.MailHost 4.10. + [maurits] (#3178) + +## 3.4.2 (2020-06-30) + +Bug fixes: + +- Close input tags properly in moderation.pt to avoid an error with i18ndude find-untranslated + [vincentfretin] (#171) + +## 3.4.1 (2020-06-26) + +Bug fixes: + +- Reuse existing translation for the "Save" button in the Edit comment form. + [vincentfretin] (#170) + +## 3.4.0 (2020-04-20) + +New features: + +- Extended existing review workflow by state `rejected` and `spam` + Moderation view extended to handle four workflow states. + [ksuess and precious input of agitator] (#164) + +Bug fixes: + +- Fix tests failing for Plone 6, deprecate Plone 4 and older. + [tschorr] (#168) + +## 3.3.2 (2019-12-10) + +New features: + +- Notification for moderator: show email address of commentator. (#163) +- Link to the commented page for editing, approving, deleting comment instead of linking to `/@@moderate-publish-comment` and `@@moderate-delete-comment`. + [ksuess] (#163) + +Bug fixes: + +- `/@@moderate-publish-comment`: publish only pending comment, else show status message "comment already approved". + [ksuess] (#163) + +## 3.3.1 (2019-11-25) + +Bug fixes: + +- Use the shared 'Plone test setup' and 'Plone test teardown' keywords in Robot tests. + [Rotonen] (#155) + +## 3.3.0 (2019-10-12) + +New features: + +- Additional view for approved comments + [ksuess] (#159) + +Bug fixes: + +- Load zcml of `plone.resource` for our use of the `plone:static` directive. + [maurits] (#2952) + +## 3.2.1 (2019-06-28) + +Bug fixes: + +- Fix reply to comment by adding old-school js-resources to legacy-bundle. Fix #157 + [pbauer] (#157) + +## 3.2.0 (2019-04-29) + +New features: + +- Index/reindex/unindex the comment itself, do not defer to `ICommentingTool`. + This way it can be integrated into collective.indexing and Solr (or any other indexing tool). + [gforcada] (#77) + +Bug fixes: + +- Fixed DeprecationWarning for ObjectEvent. [jensens] (#153) + +## 3.1.1 (2019-02-08) + +Bug fixes: + +- Changed \$(window).load with \$(document).ready in moderation.js because in + some version of FF and IE doesn't work. [eikichi18] (#144) +- a11y: Added role attribute for portalMessage [nzambello] (#145) +- Do not depend on the `meta_type` metadata in the catalog. [jensens] (#146) + +## 3.1.0 (2018-10-30) + +New features: + +- Added notification about the publishing or elimination of a comment. + [eikichi18] + +Bug fixes: + +- Fix location of controlpanel events. + [jensens] +- Fixed tests when IRichText behavior is used. + IRichText -> IRichTextBehavior + This is a follow up to [issue 476](https://github.com/plone/plone.app.contenttypes/issues/476). + [iham] +- Fix commenting and tests in python 3. + [pbauer, jensens] + +## 3.0.6 (2018-06-18) + +Bug fixes: + +- Fix tests to work with merges plone.login. + [jensens] +- More Python 2 / 3 compatibility. + [pbauer, hvelarde] + +## 3.0.5 (2018-02-04) + +Bug fixes: + +- Add Python 2 / 3 compatibility + [pbauer] + +## 3.0.4 (2017-11-24) + +Bug fixes: + +- Make sure the effects of the robotframework REMOTE_LIBRARY_ROBOT_TESTING fixture + are not accidentally removed when tearing down the PLONE_APP_DISCUSSION_ROBOT_TESTING fixture. + [davisagli] + +## 3.0.3 (2017-08-27) + +Bug fixes: + +- Show email in moderation view [ksuess] +- Remove plone.app.robotframework extras (reload and ride). + They are not needed and they are not Python 3 compatible. + [gforcada] + +## 3.0.2 (2017-07-03) + +New features: + +- Validate that author_email values are emails. + [ksuess] + +## 3.0.1 (2017-05-31) + +Bug fixes: + +- Remove unittest2 dependency + [kakshay21] + +## 3.0.0 (2017-02-12) + +Bug fixes: + +- Fixed tests with newer testbrowser. + [mauristvanrees] +- Remove deprecated \_\_of\_\_ calls on BrowserViews + [MrTango] +- Improve English on a couple of field descriptions + [djowett] +- Fix some easy pep8 issues + [djowett] + +## 2.4.20 (2017-01-17) + +Bug fixes: + +- Make comment on private content not publicly available in search results. + Part of PloneHotfix20161129. [vangheem, maurits] + +## 2.4.19 (2017-01-02) + +New features: + +- Reindex comments when they are modified. + [gforcada] + +## 2.4.18 (2016-09-20) + +Bug fixes: + +- Apply security hotfix 20160830 for redirects. [maurits] +- Update Traditional Chinese translation. + [l34marr] + +## 2.4.17 (2016-08-17) + +Bug fixes: + +- Use zope.interface decorator. + [gforcada] + +## 2.4.16 (2016-06-27) + +Bug fixes: + +- Cleaned code from flake8 errors. [maurits] +- Removed `comment-migration` view. This did not work anymore on + Plone 5. If you still need to migrate from old-style comments, so + from Plone 4.0 or earlier, please upgrade to Plone 4.3 first. + [maurits] + +## 2.4.15 (2016-06-12) + +Bug fixes: + +- Reset the required setting of the author_email widget each time. + Otherwise, the email field might get set to required when an + anonymous user visits, and then remain required when an + authenticated user visits, making it impossible for an authenticated + user to fill in the form without validation error. Or when in the + control panel the field is set as not required anymore, that change + would have no effect until the instance was restarted. [maurits] + +## 2.4.14 (2016-06-06) + +New features: + +- Make tests work with lxml safe html cleaner + +Bug fixes: + +- Fixed possible cross site scripting (XSS) attack on moderate comments page. [maurits] + +## 2.4.13 (2016-05-04) + +Fixes: + +- Removed docstrings from some methods to avoid publishing them. From + Products.PloneHotfix20160419. [maurits] + +## 2.4.12 (2016-04-13) + +Fixes: + +- Mark 'Edit' button for translation. + + [gforcada] + +## 2.4.11 (2016-03-31) + +New: + +- For the discussion controlpanel, change base URLs from portal URL to what getSite returns, but don't change the controlpanels context binding. + This allows for more flexibility when configuring it to be allowed on a sub site with a local registry. + [thet] + +Fixes: + +- fixed translate translation plone-ru.po + +## 2.4.10 (2016-02-08) + +New: + +- Added russian translations. [serge73] + +Fixes: + +- Get rid of the monkey patch on Products.CMFPlone's CatalogTool. + Issue + [staeff, fredvd] +- Cleanup code according to our style guide. + [gforcada] + +## 2.4.9 (2015-11-25) + +Fixes: + +- Update Site Setup link in all control panels (fixes ) + [davilima6] +- In tests, use `selection.any` in querystrings. + Issue + [maurits] +- Move translations to plone.app.locales + + [gforcada] + +## 2.4.8 (2015-09-20) + +- Use registry lookup for types_use_view_action_in_listings + [esteele] +- Remove discussion.css + [pbauer] +- Fix reply button not showing up since it uses a hide class which needs + to be removed instead of a display value + [ichim-david] + +## 2.4.7 (2015-09-15) + +- Tweak discussions.css styles to better live with plonetheme.barcelonata + [ichim-david] + +## 2.4.6 (2015-09-14) + +- Fix editing comments in Plone 5. + [pbauer] +- Move anonymous_email_enabled after anonymous_comments in controlpanel. + [pbauer] + +## 2.4.5 (2015-09-11) + +- Updated basque translation + [erral] + +## 2.4.4 (2015-07-18) + +- Change the category of the configlet to 'plone-general'. + [sneridagh] +- Updated links for the renamed 'Types' control panel. + [sneridagh] +- Updated Spanish translation. + [Caballero] + +## 2.4.3 (2015-06-05) + +- Update Spanish translation. + [macagua] +- Only use edit overlay if available for editing comments + [vangheem] + +## 2.4.2 (2015-05-04) + +- Update Japanese translation. + [takanory] +- Update Japanese translation. + [terapyon] +- Sort imports as per plone.api styleguide. + [gforcada] +- Fix flake8 errors reported by jenkins.plone.org. + [gforcada] + +## 2.4.1 (2015-03-26) + +- i18n for ICaptcha interface. + [davidjb] + +## 2.4.0 (2015-03-12) + +- use requirejs if available + [vangheem] +- Rename @@discussion-settings to @@discussion-controlpanel + [maartenkling] +- Add permission to allow comment authors to delete their own comments if + there are no replies yet. + [gaudenz] +- Updated portuguese pt-br translation. + [jtmolon] +- Read mail settings from new (Plone 5) registry. + [timo] +- Remove @property from Conversation.total_comments as @property and + Acquisition don't play well together. + [gforcada] + +## 2.3.3 (2014-10-23) + +- Don't execute createReplyForm js if there is no in_reply_to button. + [vincentfretin] +- Register events as Content Rules Event Types if plone.contentrules is present + [avoinea] +- Trigger custom events on comment add/remove/reply + [avoinea] +- Replace \$.live with \$.on for jQuery >= 1.9 compatibility. This works on + jQuery >= 1.7 (Plone 4.3 onwards). + [gaudenz] +- Update Traditional Chinese translations. + [marr] +- Make comments editable. + [pjstevns, gyst] +- Provide 'Delete comments' permission to handle comments deletion + [cekk] +- Fixed Italian translations [cekk] + +## 2.3.2 (2014-04-05) + +- bugfix: according to IDiscussionSettings.anonymous_email_enabled (cite): + "If selected, anonymous user will have to give their email." - But field + was not required. Now it is. + [jensens] +- bugfix: anonymous email field was never saved. + [jensens] +- updated german translations: added some missing msgstr. + [jensens] +- added i18ndude and a script `update_translations` to buildout in order + to make translation updates simpler. + [jensens] +- Fix reindexObject for content_object in moderation views. + Now reindex only "total_comments" index and not all the indexes + [cekk] +- Fix comments Title if utf-8 characters in author_name + [huub_bouma] +- use member.getId as author_username, so membrane users having different id + then username still have there picture shown and author path is correct. + [maartenkling] + +## 2.3.1 (2014-02-22) + +- 2.3.0 was a brown bag release. + [timo] + +## 2.3.0 (2014-02-22) + +- Remove DL's from portal message in templates. + + [khink] +- Execute the proper workflow change when using the moderation buttons instead + of hardcoding the workflow action to always publish + [omiron] +- Corrections and additions to the Danish translation + [aputtu] + +## 2.2.12 (2014-01-13) + +- Show author email to Moderator when it is available in anonymous comment. + [gotcha, smoussiaux] +- Put defaultUser.png instead of old defaultUser.gif + [bsuttor] +- Remove bbb directory. bbb was never really implemented. + [timo] +- Replace deprecated test assert statements. + [timo] +- Remove portal_discussion tool. + [timo] +- Refactor tests to use the PLONE_APP_CONTENTTYPES_FIXTURE instead of + PLONE_FIXTURE. + [timo] +- Fix ownership of comments. + [toutpt] + +## 2.2.10 (2013-09-24) + +- Revert "Refactor tests to use the PLONE_APP_CONTENTTYPES_FIXTURE instead of + the PLONE_FIXTURE." that has been accidentally introduced into the 2.2.9 + release. + [timo] + +## 2.2.9 (2013-09-24) + +- Portuguese translation added. + [Rui Silva] +- Rename CHANGES.txt to CHANGES.rst. + [timo] +- Fix ajax form submit for delete comment action: add 'data' to the request. + [toutpt] + +## 2.2.8 (2013-08-20) + +- Re-release 2.2.7 with .mo files. Seems like 2.2.7 has been released twice on + two different dates. The first release seems to be made without a github + push. + [timo] +- Fix comments viewlet's get_replies for non-annotatable objects. + [witsch] + +## 2.2.7 (2013-07-04) + +- making sure .mo files are present at release + [garbas] +- Revert change that silently added mime_type attribute values + to old discussion items that had none. + [pjstevns] + +## 2.2.6 (2013-05-23) + +- Fix migration to not fail when member has been deleted. + [datakurre] + +## 2.2.5 (2013-04-06) + +- Update pt_BR translation [ericof] +- Do not raise an error when no workflow is assigned to the comment type. + [timo] +- Add a conversation property public_commentators that only lists + commentators of comments that are public. + The commentators indexer indexes this field now. + The behavior of the conversation property commentators is + unchanged. + [do3cc] +- The last comment date now only returns the date of the newest + published comment. + [do3cc] + +## 2.2.4 (2013-03-05) + +- Check for 'checked' attribute in a way that work also for jQuery 1.7 + [ichimdav] +- Better fix for #13037 by removing submit event trigger altogether + [ichimdav] +- Added Romanian translation + [ichimdav] +- Updated Ukrainian translation + [kroman0] + +## 2.2.3 (2013-01-13) + +- add anonymous_email_enabled settings to really let integrator activate + the email field on comment add form when anonymous. + [toutpt] + +## 2.2.2 (2012-11-16) + +- first check if captcha is installed before we open browsers zcml + files that depend on these packages, fixes #12118 and #12774 + [maartenkling] + +## 2.2.1 (2012-11-16) + +- Make conversation view not break when comment-id cannot be converted to + long. This fixes #13327 + [khink] +- fix insufficient privileges when trying to view + the RSS feed of a comment collection + [maartenkling] +- removed inline border=0 and move it to css + [maartenkling] +- For migrations of comments without a valid old_status, apply the 'published' + state. + [thet] +- Re-apply eleddy's "Revert modification date since this is fixed in + p.a.caching now." as her commit was lost later on due to some git magic. + [thet] +- Remove submitting the controlpanel form again after removing disabled tags + fixes #13037 and #12357 + [maartenkling] +- Remove inline styles, fixes #12399 + [maartenkling] +- add fallback border color for i8, fixes #11324 + [maartenkling] +- Replace discussionitem_icon.gif with png version. + [timo] +- Fix catalog updates for IObjectMovedEvent + [gaudenz] +- Fix non-functioning user_notification feature + [izak] + +## 2.2.0 (2012-08-30) + +- Refactor the comment creator/author_name to comply with the Plone core + convention to store the username on the creator attribute and not the + fullname. + [timo] +- Rename the id of the text widgets because there can be css-id clashes with + the text field of documents when using TinyMCE in overlays or multiple + instances of TinyMCE on a single page. + [timo] +- text/html added to the possible mime types for comments. + [timo] +- Make 'text/plain' the default mime type for comments and make sure the + default type is set properly when creating a new comment. + [timo] +- Fix handling of comments with invalid transforms. Write an error msg + to the log and just return the untransformed text. + [timo] + +## 2.1.8 (unreleased) + +- Support for Dexterity added. The conversation enabled method now detects and + supports Dexterity-based content types. + [timo] +- No more recursive came_from redirection after logged_in. + [kcleong, huubbouma] +- Danish translation updated. + [stonor] +- Documentation and howtos updated. + [timo] +- Remove development buildout files and directories. + [timo] + +## 2.1.7 (2012-06-29) + +- Prune duplicated test code. + [pjstevns] +- Update version in buildout.cfg to allow development. + [pjstevns] +- Conversation.total_comments only counts published comments. + Fixes bug #11591. + [pjstevns] +- Set workflow status of comments during migration based on + the state of the Discussion Item. + [pjstevns] + +## 2.1.6 (2012-05-30) + +- Add Site Administrator role to Review comments permission. + [gaudenz] +- Fix excessive JS comment deletion. + [gaudenz] +- Hide Conversation objects from breadcrumb navigation. The breadcrumbs + navigation is also used in the search results view. This lead to Conversation + objects showing up if 'Discussion Items' are searchable. + [gaudenz] +- No longer depend on zope.app packages. + [hannosch] + +## 2.1.5 (2012-04-05) + +- Redirect to "/view" for Image, File and anything listed as requiring + a view in the url to properly display comments. + [eleddy] +- Make comments and controlpanel views more robust, so they don't break if no + workflow is assigned to the 'Discussion Item' content type. + [timo] +- Warning message added to discussion control panel that shows up if there are + unmigrated comments. + [timo] +- Make topic/collection tests pass when plone.app.collection is installed. + [timo] + +## 2.1.4 (2012-02-29) + +- Revert modification date since this is fixed in p.a.caching now. + [eleddy] +- Add missing meta_typ to "Review comments" portal action. + [batlock666] + +## 2.1.3 (2012-01-24) + +- Set modified date of object receiving comments so that caching works + correctly (304s) + [eleddy] + +## 2.1.2 (2011-12-21) + +- Fixed language code error in Ukrainian translation. The message + catalog was erroneously set to "English". + [chervol] +- Do not raise an error if the comment text is None. + [timo] +- Updated Spanish translation. + [hvelarde] +- Fix that catalog rebuild breaks the path attribute on comments. This fixes + . + [pjstevns] + +## 2.1.1 (2011-11-24) + +- Include mo files in the distribution. + [vincentfretin] +- Fix various text typos. + [timo] +- Fix control panel help text typos. + [jonstahl] +- Documentation about overriding the comments viewlet js added. + [timo] +- Corrected location of Japanese po file. + [tyam] + +## 2.1.0 (2011-08-22) + +- Avoid error when moving objects that are contentish but not annotatable. + [davisagli] +- New feature: Markdown syntax added to possible comment text transforms. + [timo] +- Make sure the comment brains are updated properly when the content object is + renamed. + [hannosch, timo] +- Make sure only comments to the content object are removed from the catalog + when the content object is moved. + [hannosch, timo, davisagli] +- Make sure the conversation.getComments method returns acquisition wrapped + comments. + [timo] +- Ukrainian translation added. + [chervol] +- Remove one_state_workflow customizations. + [timo] + +## 2.0.9 (2011-07-25) + +- Make sure the creator index always stores utf-8 encoded strings and not + unicode. + [timo] + +## 2.0.8 (2011-07-25) + +- Automatically reload batch moderation page if no comments are left. This + fixes . + [timo] +- Use Plone's safe_encode method instead of encode() for the creator index to + make sure unicode encoded strings can be indexed too. + [timo] + +## 2.0.7 (2011-07-15) + +- Fix discussion control panel submit for Google Chrome. This fixes + . + +## 2.0.6 (2011-07-04) + +- Update comment brains in zcatalog when moving a content object with comments. + This fixes . + [timo] +- Plone 3 specific exclusion of plone.app.uuid removed. + [timo] + +## 2.0.5 (2011-06-16) + +- Simplify CSS and JS registrations. CSS will now be imported using the + standard link and so can be merged, inserted after forms.css. JS will now be + imported after collapsibleformfields.js. + [elro] +- Enable the left-menu on the configlet, to be more consistent with all other + configlets. Related to + [WouterVH] +- Do not render/update the comment form in CommentViewlets if commenting is + disabled, since this slows down the page rendering. This fixes + + [fafhrd] + +## 2.0.4 (2011-05-28) + +- Refactor/clean up the handleComment method. + [timo] +- Make handleComment method store comment attributes from form extenders. This + allows us to extend the comment form with external add-ons. See + + for details. + [timo] + +## 2.0.3 (2011-06-19) + +- Updated Simplified Chinese translation + [jianaijun] +- Italian translation review. + [gborelli] + +## 2.0.2 (2011-05-12) + +- Moderation should be enabled only if there is a workflow set for Discussion + Item. + [erico_andrei] + +## 2.0.1 (2011-04-22) + +- Translations updated. German translations for notifications added. + [timo] +- Add links to delete/approve a comment in the moderator notification email. + [timo] +- Remove the unnecessary workflow_action parameter from the PublishComments + request. + [timo] +- Make sure the email settings in the control panel are disabled when commenting + is disabled globally. + [timo] +- Enable/disable moderator_email setting dynamically as mail settings or + discussion settings change. + [timo] +- Remove ImportError exceptions for Plone < 4.1 code and plone.z3cform < 0.6.0. + [timo] +- Provide the comment body text in the email notification. + [timo] +- Fix comment link in email notification. This fixes + . + [timo] +- Redirect to the comment itself when notifying a user about a new comment. + [timo] + +## 2.0 (2011-04-21) + +- No changes. + +## 2.0b2 (2011-04-21) + +- Added Japanese translation. + [tyam] +- Move all tests from testing layer to plone.app.testing. + [timo] +- Move some policy out of the conversation storage adapter into a + view, specifically "enabled()". Prevents having to replace/migrate + persistent objects to change policy which really only concerns the + context and possibly the request, not the conversation storage. + Fixes #11372. + [rossp] +- Fix unindexing of comments when deleting content resulting from + iterating over a BTree while modifying it. Fixes #11402. + [rossp] +- Fix Missing.Value for Creator in the catalog. Fixes #11634. + [rossp] +- Don't add the annotation unless a comment is actually being added. + Fixes #11370. + [rossp] +- Fixed i18n of the "Commenting has been disabled." message. + [vincentfretin] +- Add a moderator_email setting to control where moderator notifications are + sent. + [davisagli] + +## 2.0b1 (2011-04-06) + +- Make discussion.css cacheable when registering it. + [davisagli] +- Fix issue where GMT datetimes were converted into local timezone DateTimes + during indexing. + [davisagli] +- Handle timezones correctly while converting dates during the migration of + legacy comments. + [davisagli] +- When returning a comment's title, give preference to its title attribute + if set. + [davisagli] +- Use the cooked text of legacy comments when migrating. + [davisagli] +- Make sure that comment text is transformed to plain text when indexing. + [davisagli] +- Move logic for transforming comment text to the Comment class's getText + method. Use a comment instance's mime_type attribute in preference to the + global setting for the source mimetype. Use text/x-html-safe as the target + mimetype to make sure the safe HTML filter is applied, in case the source is + untrusted HTML. + [davisagli] +- Provide a filter_callback option to the migration view, so that a custom + policy for which comments get migrated can be implemented. + [davisagli] +- Fixed RoleManager import to avoid deprecation warning on Zope 2.13. + [davisagli] +- French translations. + [thomasdesvenain] +- Fixed internationalization issues. + [thomasdesvenain] +- Added Afrikaans translations + [jcbrand] + +## 2.0a3 (2011-03-02) + +- Fixed test failure for the default user portrait, which changed from + defaultUser.gif to defaultUser.png in Products.PlonePAS 4.0.5 + [maurits] + +## 2.0a2 (2011-02-08) + +- Fixed test failure for the default user portrait, which changed from + defaultUser.gif to defaultUser.png in Products.PlonePAS 4.0.5. + [maurits] +- Remove "Plone 3 only" code. + [timo] +- Do not monkey patch the BAD_TYPES vocabulary or plone.app.vocabularies + anymore. + [timo] + +## 2.0a1 (2011-02-07) + +- Split up development into two branches. The 1.x branch will be for Plone 3.x + and Plone 4.0.x and the 2.x branch will be for Plone 4.1 and beyond. + [timo] +- Import Owned from OFS.owner to avoid deprecation warnings. + [timo] +- Disable discussion by default. + [timo] +- Enable ajaxify comment deletion again ([thomasdesvenain]). This has been + disabled in 1.0b12 because of problems with Plone 3. + [timo] +- Remove collective.autopermission dependency that has become unnecessary in + Plone 4.1. + [timo] + +## 1.0 (2011-02-07) + +- Do not check for a comment review workflow when sending out a moderator email + notification. This fixes . + [timo] +- Check if the current user has configured an e-mail address for the email + notification option. This fixes . + [timo] + +## 1.0RC2 (2011-01-24) + +- Remove moderation_enabled setting from registry to avoid migration problems + to 1.0RC1. This fixes . + [timo] + +## 1.0RC1 (2011-01-22) + +- Always show existing comments, even if commenting is disabled. + [timo] +- Fix CSS for commenter images with a width of more than 2.5em. This fixes + . + [timo] +- Show a 'Comments are moderated.' message next to the comment form if comments + are moderated. + [timo] +- Make sure plone.app.registry's ZCML is loaded, so that its import step will run + when plone.app.discussion is installed. + [davisagli] +- Avoid sending multiple notification emails to the same person when + he has commented multiple times. + [maurits] +- Move discussion action item from actionicons.xml to actions.xml to avoid + deprecation warning. + [timo] +- Fix cancel button on edit view when using Dexterity types. This fixes + . + [EpeliJYU] +- Assigning the 'Reply to item' permission to the 'Authenticated' role. The old + commenting system allowed 'Authenticated' users to post comments. Also, OpenID + users do not possess the 'Authenticated' role. + [timo] +- Make sure the handleComment method checks for the 'Reply to item' permission + when adding a comment. + [timo] +- Make the mail-setting warning message show up in the discussion control panel. + [timo] +- Link directly to the "Discussion Item" types control panel in the moderation + view. + [timo] +- Show "moderate comments" link in the admin panel only if a moderation + workflow is enabled for comments. + [timo] +- Do not allow to change the mail settings in the discussion control panel, if + there is no valid mail setup. + [timo] +- Disable all commenting options in the discussion control panel if comments + are disabled globally. +- Check for the 'review comments' permission instead of 'manage' to decide + if the user should see a 'this comment is pending' message. + [timo] +- Move "moderate comments" site action above the logout action. + [timo] +- Moderator notification description updated. + [timo] +- Redirect back to the discussion control panel when the discussion control + panel form is submitted. + [timo] +- Fix document_byline bottom margin if commenter images are disabled. + [timo] +- Dynamically show the comment formatting message dependent on the text + transform setting. + [timo] +- Description for text transform added to the discussion control panel. + [timo] +- Move the discussion control panel to the core Plone configuration. + [timo] +- Always set the effective date of a comment to the same value as the creation + date. + [timo] +- Fix SMTP exception when an email is send to the moderator. + [timo] +- Make sure comment UIDs in the catalog are always unique. This fixes + . + [timo] +- Fix 'check all' on batch moderation page. + [davisagli] +- Use safe_unicode to decode the title of the content. encode("utf-9") caused + Dexterity based content types to raise a unicode decode error. This fixes + + [dukebody] +- Spanish translation updated. + [dukebody] +- Catalan translation added. + [sneridagh] +- Convert anonymous-supplied name to unicode as done for authenticated members. + [ggozad] +- Catch SMTP exceptions when sending email notifications. + [timo] +- Updated italian translation. + [keul] + +## 1.0b12 (2010-11-04) + +- Remove AJAX comment deletion binding. This function relies on the nextUntil() + selector introduced by jQuery 1.4 and therefore breaks in Plone 3 + (that currently uses jQuery 1.3.2). + [timo] + +## 1.0b11 (2010-11-03) + +- Fix Dutch and Czech language code and name. + [timo] +- Re-add the CommentsViewlet can_manage method. This method has been removed + in version 1.0b9 and added again in 1.0b11 because we don't want to change + the API in beta releases. + [timo] +- Declare z3c.form and zope.schema as minimum version dependencies in setup.py + in case people use a different KGS. + [timo] +- Add and update es and eu l10ns. + [dukebody, on behalf of erral] +- Ajaxify comment deletion and approval. + [thomasdesvenain] +- New feature: As a logged-in user, I can enable/disable email notification of + additional comments on this content object. + [timo] +- Disable the plone.app.registry check on schema elements, so no error is + raised on upgrades. This fixes . + [timo] +- Remove the too generic id attribute of the comment form. + [timo] +- Fixed handling of non-ascii member data, like fullname and email. + [hannosch] + +## 1.0b10 (2010-10-15) + +- Fixed "global name 'WrongCaptchaCode' is not defined" if norobots captcha, + but no other validation package is installed. + [naro] +- Check if there is a 'pending' review state in the current workflow for + comments instead of just checking for the 'comment_review_workflow'. This + allows integrators to use a custom review workflow. This fixes + . + [timo] +- fixed plone-it.po (improper language code ('en' instead of 'it')) + [ajung] + +## 1.0b9 (2010-10-07) + +- Replace the can_manage method with a can_review method that checks the + 'Review comments' permission. This fixes + . + [timo] +- Fix moderation actions (publish, delete) in the moderation view with virtual + hosts. This is a replacement for . + [timo] +- Do not show two "login to add comments" buttons when there are no comments + yet. This fixes . + [timo] + +## 1.0b8 (2010-10-04) + +- Apply the comment viewlet template and styles to the new title-less comments. + This might require integrators to apply their custom templates and styles. + [timo] +- Remove title field from the comment form and replace it with an auto-generated + title ("John Doe on Welcome to Plone"). + [timo] +- Fix : "Comment byline shows login + name, not full name" + [kiorky] +- Make sure the \_\_parent\_\_ pointer (the conversation) of a comment is not + acquisition wrapped in conversation.addComment. This fixes + . + [timo] +- Revert r35608 since this was breaking the comment moderation bulk actions. + The BulkActionsView expects the absolute path of the comments without the + portal url (e.g. '/plone/doc1/++conversation++default/1285346769126020'). + This fixes . + [timo] +- Use "(function(\$) { /\* some code that uses \$ \*/ })(jQuery)" instead of + "\$(document).ready(function(){ /\* some code that uses \$ \*/ });" to invoke + jQuery code. + [timo] +- Finnish translation added. + [saffe] +- Italian translation updated. + [keul] + +## 1.0b7 (2010-09-15) + +- Captcha plugin support for collective.z3cform.norobots (version >= 1.1) added. + [saffe] +- Store dates in utc and not in local time. Display local time + [do3cc] +- Fetch context for the comment view with "context = aq_inner(self.context)". + [timo] +- Raise an unauthorized error when authenticated users try to post a comment + on a content object that has discussion disabled. Thanks to vincentfrentin + for reporting this. + [timo] +- Czech translation added. + [naro] +- Clean up code with PyLint. + [timo] +- Make Javascripts pass JSLint validation. + [timo] +- Put email notification subscribers into their own zcml file so it is easier + for integrators to override them. + [timo] +- Plain text and intelligent text options for comment text added to preserve + basic text structure and to make links clickable. + [timo] +- Rewrote all tal:condition in comments.pt. The authenticated user has + the reply button and the comment form if he has the "Reply to item" + permission And the discussion is currently allowed. + [vincentfretin] + +## 1.0b6 (2010-08-24) + +- Fixed the case where a folder has allow_discussion=False and + conversation.enabled() on a document in this folder returned False + instead of True because of allow_discussion acquisition. + [vincentfretin] +- Redirect to the comment form action instead of the absolute URL when a + comment is posted. This fixes the accidentally triggered file upload when a + comment is posted on a file content object. + [timo] +- We need five:registerPackage to register the i18n folder. + [vincentfretin] +- Added Traditional Chinese (zh_TW) translation. + [TsungWei Hu] +- Added French translation. + [vincentfretin] +- Renamed legend_add_comment to label_add_comment to have the translation from + plone domain. + [vincentfretin] +- label_comment_by and label_commented_at are not in Plone 4 translation + anymore, so these two messages moved to plone.app.discussions i18n domain. + [vincentfretin] +- Translate "Warning" shown in @@moderate-comments in the plone domain. + [vincentfretin] +- Fixed i18n markup of message_moderation_disabled. + [vincentfretin] +- Catch Type errors in indexers if object can not be adapted to IDiscussion + [do3cc] +- Call the CaptchaValidator even when no captcha data was submitted. This is + necessary to ensure that the collective.akismet validator is called when + installed. + [timo] +- Spanish translation added. Thanks to Judith Sanleandro. + [timo] + +## 1.0b5 (2010-07-16) + +- Use self.form instead of CommentForm for the CommentsViewlet update method so + integrators don't have to override the viewlet's update method. + [matous] +- Make sure the form fields in the reply form are always placed under the field + labels. + [timo] +- Fix CSS overflow bug that occurs with the new Plone 4.0b5 comment styles. + [timo] +- Unnecessary imports and variables removed. + [timo] +- Added norwegian translation. + [ggozad] +- Protect against missing canonical in conversationCanonicalAdapterFactory. + [hannosch] +- Documentation for Captcha plugin architecture and email notification added. + See . + [timo] +- Use sphinx.plonetheme for plone.app.discussion documentation. + [timo] +- Avoid deprecation warning for the Globals package. + [hannosch] +- Remove the hard coded check for title and text when the comment form is + submitted. This allows integrators to write schema extenders that remove the + title from the comment form. + [timo] +- Move captcha registration to its own captcha.zcml file. + [timo] +- Akismet () spam protection plugin (collective.akismet) + support added. + [timo] +- Simplify the CaptchaValidator class by dynamically adapting a view with the + name of the captcha plugin (e.g. recaptcha, captcha, akismet) for the + validator. + [timo] +- Dutch translation added. + [kcleong] +- Enable caching and merging for comments.js to save some requests. + [pelle] +- Design notes for the Captcha plugin architecture added. + [timo] +- Make IDiscussionLayer inherit from Interface again. Remove IDefaultPloneLayer, + since Plone 4.0b1 and plone.theme 2.0b1 are out now. + [timo] +- Clean up Javascript code. + [timo] +- Fix encoding error in migration procedure, otherwise migration procedure + breaks on joining output list in case we have there any non-ascii characters. + [piv] +- plone.z3cform 0.6.0 compatibility (fix maximum recursion depth error which + appears with plone.z3cform higher than 0.5.10). + [piv] +- Removed moderation.js from js registry and include it only in moderation.pt as + that is the only place where it is used. + [ggozad] + +## 1.0b4 (2010-04-04) + +- New feature: As a moderator, I am notified when new comments require my + attention. + [timo] +- Sphinx-based developer documentation added. See + . + [timo] +- Rename "Single State Workflow" to "Comment Single State Workflow". + [timo] +- Rename 'publish comment' to 'approve comment'. This fixes #1608470. + [timo] +- Show a warning in the moderation view if the moderation workflow is disabled. + [timo] +- Move 'Moderate comments' link from site actions to user actions. + [timo] +- Fix #662654: As an administrator, I can configure a Collection to show recent + comments. Comment.Type() now correctly returns the FTI title ('Comment') + [chaoflow] +- German translation updated. + [juh] +- Fix #2419342: Fix untranslated published/deleted status messages. + [timo] +- Remove fixed width of the actions column of the moderation view. The + translated button titles can differ in size from the English titles. + [timo] +- Fix #2494228: Remove comments as well when a content object is deleted. + [timo] +- Fix unicode error when non-ASCII characters are typed into the name field of a + comment by anonymous users. + [regebro] +- Make p.a.d. work with the recent version of plone.z3cform (0.5.10) + [timo] +- Make p.a.d. styles less generic. This fixes #10253. + [timo] +- Added greek translation. + [ggozad] +- A bug in the moderator panel meant you couldn't delete items in a virtual + host, if your portal was named "plone". + [regebro] + +## 1.0b3 (2010-01-28) + +- Added an i18n directory for messages in the plone domain and updated scripts + to rebuild and sync it. + [hannosch] +- Added an optional conversationCanonicalAdapterFactory showing how to share + comments across all translations with LinguaPlone, by storing and retrieving + the conversation from the canonical object. + [hannosch] +- Play by the Plone 3.3+ rules and use the INavigationRoot as a base for the + moderation view. + [hannosch] +- Added a commentTitle CSS class to the comment titles. + [hannosch] +- Update message ids to match their real text. + [hannosch] +- Set CSS classes for the comment form in the updateActions method. + [timo] +- Respect the allow_comments field on an object and avoid calculations if no + comments should be shown. + [hannosch] +- Automatically load the ZCML files of the captcha widgets if they are + installed. + [hannosch] +- Fixed i18n domain in GenericSetup profiles to be `plone`. Other values + aren't supported for GS profiles. + [hannosch] +- Provide our own copy of the default one state workflow. Not all Plone sites + have this workflow installed. + [hannosch] +- Register the event subscribers for the correct interfaces in Plone 3. + [hannosch] +- Factored out subscriber declarations into its own ZCML file. + [hannosch] +- Bugfix for #2281226: Moderation View: Comments disappear when hitting the + 'Apply' button without choosing a bulk action. + [timo] +- Allow to show the full text of a comment in the moderation view. + [timo] +- German translation added. + [timo] +- Italian translation added. + [keul] + +## 1.0b2 (2010-01-22) + +- Bugfix for #2010181: The name of a commenter who commented while not logged in + should not appear as a link. + [timo] +- Bugfix for #2010078: Comments that await moderation are visually distinguished + from published comments. + [timo] +- Bugfix for #2010085: Use object_provides instead of portal_type to query the + catalog for comment. + [timo] +- Bugfix for #2010071: p.a.d. works with plone.z3cform 0.5.7 and + plone.app.z3cform 0.4.9 now. + [timo] +- Bugfix for #1513398: Show "anonymous" when name field is empty in comment + form. + [timo] +- Migration view: Dry run option added, abort transaction when something goes + wrong during migration, be more verbose about errors. + [timo] + +## 1.0b1 (2009-12-08) + +- Fix redirect after a adding a comment + [timo] +- Replace yes/no widgets with check boxes in the discussion control panel + [timo] +- Make comments viewlet show up in Plone 4 + [timo] +- Apply Plone 4 styles to comment form + [timo] +- Simplify moderation view by removing the filters + [timo] + +## 1.0a2 (2009-10-18) + +- Plone 4 / Zope 2.12 support + [timo] +- Comment migration script added + [timo] +- Pluggable plone.z3cform comment forms + [timo] +- Captcha and ReCaptcha support added + [timo] + +## 1.0a1 (2009-06-07) + +- Basic commenting functionality and batch moderation. + [timo] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..9fddb8cd --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1 @@ +Please see diff --git a/README.md b/README.md new file mode 100644 index 00000000..5ff2c6a4 --- /dev/null +++ b/README.md @@ -0,0 +1,43 @@ +# Introduction + +plone.app.discussion is the commenting add-on for Plone. +It is part of the maintained Plone core. + +# Installation + +If your installation depends on the [Plone](https://pypi.org/project/Plone/) package, you can install it via the Plone control panel. +In case you do only depend on either the `plone.volto`, `plone.classicui` or `Products.CMFPlone` package, you need to add it to your requirements file. +After adding it and installing the requirement, you can install it via the Plone control panel. + +# Spam protection + +These days it is essential to protect your site from commenting spam. +The following add-ons can help to protect your site: + +- [plone.formwidget.captcha](https://pypi.org/project/plone.formwidget.captcha/) + (for Captcha spam protection) +- [plone.formwidget.recaptcha](https://pypi.org/project/plone.formwidget.recaptcha/) + (for ReCaptcha spam protection) +- [collective.z3cform.norobots](https://pypi.org/project/collective.z3cform.norobots/) + (provides a "human" captcha widget based on a list of questions/answers) +- [plone.formwidget.hcaptcha](https://pypi.org/project/plone.formwidget.hcaptcha/) + (for spam protection by [HCaptcha](https://www.hcaptcha.com/) ) + +# Documentation + +For further information, please refer to the [official Plone documentation](https://docs.plone.org/). + +# Credits + +This package was initially developed as part of the Google Summer of Code 2009 by Timo Stollenwerk (student) and Martin Aspeli (mentor). + +Many thanks to: + +- Jon Stahl (for acting as "the customer" during GSoC) +- David Glick (for technical expertise and advice during GSoC) +- Lennart Regebro (for writing the portal_discussion tool and initial unit tests) +- Carsten Senger (for fixing the comment z3c.form form and pizza) +- Hanno Schlichting (for making p.a.d work with Zope 2.12) +- Alan Hoey (for providing fixes) +- Maik Roeder (for providing and setting up a buildbot) +- Jens Klein (for ripping it out of core and making it a separate core-addon for Plone 6.1) diff --git a/docs/CHANGES.md b/docs/CHANGES.md new file mode 100644 index 00000000..81d4eeb9 --- /dev/null +++ b/docs/CHANGES.md @@ -0,0 +1,1550 @@ +--- +myst: + html_meta: + "description": "Changelog - plone.app.discussion documentation" + "property=og:description": "Changelog - plone.app.discussion documentation" + "property=og:title": "Changelog" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +# Changelog + +% You should *NOT* be adding new change log entries to this file. +% You should create a file in the news directory instead. +% For helpful instructions, please see: +% https://github.com/plone/plone.releaser/blob/master/ADD-A-NEWS-ITEM.rst + +% towncrier release notes start + +## 5.1.0 (2025-05-02) + +New features: + +- Implement auto_approve_admin_comments based on specified roles @rohnsha0 (#261) + +Bug fixes: + +- Fix improper handling of logic for showing delete button @rohnsha0 (#182) + +Internal: + +- Update configuration files. + [plone devs] + +## 5.0.0 (2025-02-06) + +Internal: + +- Make final release, no changes. [maurits] (#610) + +## 5.0.0a3 (2025-01-23) + +Bug fixes: + +- Do not depend on `plone.api`. [ale-rt] (#188) +- Fix DeprecationWarnings. [maurits] (#4090) + +## 5.0.0a2 (2024-10-23) + +New features: + +- Update robot framework tests to use + `robotframework-browser` (`playwright` integration on robotframework). + [gforcada] (#3813) + +## 5.0.0a1 (2024-09-05) + +Breaking changes: + +- Move this package in the space of Plone Core add-ons. + It now depends on Products.CMFPlone and is no longer installed by default. + It is still available in the default Plone distribution, but can be omitted in customizations. + Installing this in the Add-ons control panel will enable comments globally. + [jensens] (#211) + +Bug fixes: + +- Fix redirection after comment edit to main content, preventing NotFound. [@jensens] (#211) +- Add missing icon on comments' `view` action + Register contenttype icon for comments. + [gforcada, maurits] (#222) + +## 4.1.2 (2024-04-16) + +Internal: + +- Add capture screen in robot tests to debug. @wesleybl (#235) +- Fix robot test `Add a Comment to a Document and bulk delete it`. @wesleybl (#237) +- Fix robot test `Add a Comment to a Document and bulk delete it` 2. @wesleybl (#238) +- Fix robot test `Add a Comment to a Document and bulk delete it` 3. @wesleybl (#239) + +## 4.1.1 (2024-03-22) + +Bug fixes: + +- Apply validation for all captchas. @ksuess (#234) + +## 4.1.0 (2024-03-19) + +New features: + +- Provide HCaptcha if plone.formwidget.hcaptcha is installed. @ksuess (#230) + +Internal: + +- Fix test "Add a Comment to a Document and bulk delete it". @wesleybl (#228) + +## 4.0.5 (2024-03-15) + +Bug fixes: + +- Fix test "Add a Comment to a Document and bulk delete it". @wesleybl (#226) + +Internal: + +- Fix test "Add a Comment to a Document and bulk delete it" 2. @wesleybl (#227) + +## 4.0.4 (2024-02-21) + +Bug fixes: + +- Report the upgrade steps progress, + really useful for sites with lots of comments. + [gforcada] + +## 4.0.3 (2024-02-13) + +Bug fixes: + +- Do not autofocus on the comments form. + [maurits] (#3623) + +## 4.0.2 (2023-07-14) + +Internal: + +- Update configuration files. + [plone devs] (cfffba8c) + +## 4.0.1 (2023-04-14) + +Internal: + +- Remove translations folder, + for ages they are coming from p.a.locales. + [gforcada] (#1) +- Update configuration files. + [plone devs] (#47959565) + +## 4.0.0 (2022-11-11) + +Bug fixes: + +- Set timezones for creation and modification dates of comments [instification] (#204) + +## 4.0.0b3 (2022-10-11) + +Bug fixes: + +- Fix password used in tests. [davisagli] (#203) + +## 4.0.0b2 (2022-09-30) + +Bug fixes: + +- Use longer passwords in tests. [davisagli] (#203) + +## 4.0.0b1 (2022-06-23) + +Bug fixes: + +- Test-only fix: normalize white space when comparing output of `comment.getText()`. + Needed to not fail with newer `plone.outputfilters`. + [maurits] (#49) + +## 4.0.0a7 (2022-05-14) + +Breaking changes: + +- Code style black & isort. Remove six usage. Use plone.base and move annotation key over to here. + [jensens] (#195) + +Bug fixes: + +- Make compatible with robotframework 3-5. + [maurits] (#5) +- Grant Site Administrators the same workflow permissions as Managers. + They were missing permissions on pending comments. + [maurits] (#199) +- Removed z3c.autoinclude.plugin entrypoint. [maurits] (#3188) + +## 4.0.0a6 (2022-04-28) + +Bug fixes: + +- Replaced use of `plone.api`. That should not be done in Plone core. + [maurits] (#188) + +## 4.0.0a5 (2022-04-04) + +New features: + +- Moved JS to Mockup control panel patterns (ES6) [MrTango] (#190) + +## 4.0.0a4 (2022-03-23) + +New features: + +- Added 'View comments' permission. [@razvanMiu] (#180) + +## 4.0.0a3 (2021-10-16) + +Bug fixes: + +- Add missing i18n:translate tags + [erral] (#189) + +## 4.0.0a2 (2021-09-15) + +New features: + +- Refactor templates and styling for comments and controlpanel. + [santonelli] (#169) +- Implement events for Comment (ICommentModifiedEvent) and Reply(IReplyModifiedEvent) modification [ericof] (#183) + +Bug fixes: + +- Fix tests with Products.MailHost 4.11. + [maurits] (#174) +- Remove cyclic dependency with Products.CMFPlone + [ericof] (#186) + +## 4.0.0a1 (2021-04-21) + +New features: + +- Refactor templates and styling for comments and controlpanel. + [santonelli] (#169) +- Cleanup template and move message to python code. + [santonelli] (#177) + +Bug fixes: + +- Fix tests with Products.MailHost 4.11. + [maurits] (#174) + +## 3.4.4 (2020-10-09) + +New features: + +- Update templates markup to Bootstrap 4. + [andreesg] + +## 3.4.3 (2020-09-28) + +Bug fixes: + +- Fix tests with Products.MailHost 4.10. + [maurits] (#3178) + +## 3.4.2 (2020-06-30) + +Bug fixes: + +- Close input tags properly in moderation.pt to avoid an error with i18ndude find-untranslated + [vincentfretin] (#171) + +## 3.4.1 (2020-06-26) + +Bug fixes: + +- Reuse existing translation for the "Save" button in the Edit comment form. + [vincentfretin] (#170) + +## 3.4.0 (2020-04-20) + +New features: + +- Extended existing review workflow by state `rejected` and `spam` + Moderation view extended to handle four workflow states. + [ksuess and precious input of agitator] (#164) + +Bug fixes: + +- Fix tests failing for Plone 6, deprecate Plone 4 and older. + [tschorr] (#168) + +## 3.3.2 (2019-12-10) + +New features: + +- Notification for moderator: show email address of commentator. (#163) +- Link to the commented page for editing, approving, deleting comment instead of linking to `/@@moderate-publish-comment` and `@@moderate-delete-comment`. + [ksuess] (#163) + +Bug fixes: + +- `/@@moderate-publish-comment`: publish only pending comment, else show status message "comment already approved". + [ksuess] (#163) + +## 3.3.1 (2019-11-25) + +Bug fixes: + +- Use the shared 'Plone test setup' and 'Plone test teardown' keywords in Robot tests. + [Rotonen] (#155) + +## 3.3.0 (2019-10-12) + +New features: + +- Additional view for approved comments + [ksuess] (#159) + +Bug fixes: + +- Load zcml of `plone.resource` for our use of the `plone:static` directive. + [maurits] (#2952) + +## 3.2.1 (2019-06-28) + +Bug fixes: + +- Fix reply to comment by adding old-school js-resources to legacy-bundle. Fix #157 + [pbauer] (#157) + +## 3.2.0 (2019-04-29) + +New features: + +- Index/reindex/unindex the comment itself, do not defer to `ICommentingTool`. + This way it can be integrated into collective.indexing and Solr (or any other indexing tool). + [gforcada] (#77) + +Bug fixes: + +- Fixed DeprecationWarning for ObjectEvent. [jensens] (#153) + +## 3.1.1 (2019-02-08) + +Bug fixes: + +- Changed \$(window).load with \$(document).ready in moderation.js because in + some version of FF and IE doesn't work. [eikichi18] (#144) +- a11y: Added role attribute for portalMessage [nzambello] (#145) +- Do not depend on the `meta_type` metadata in the catalog. [jensens] (#146) + +## 3.1.0 (2018-10-30) + +New features: + +- Added notification about the publishing or elimination of a comment. + [eikichi18] + +Bug fixes: + +- Fix location of controlpanel events. + [jensens] +- Fixed tests when IRichText behavior is used. + IRichText -> IRichTextBehavior + This is a follow up to [issue 476](https://github.com/plone/plone.app.contenttypes/issues/476). + [iham] +- Fix commenting and tests in python 3. + [pbauer, jensens] + +## 3.0.6 (2018-06-18) + +Bug fixes: + +- Fix tests to work with merges plone.login. + [jensens] +- More Python 2 / 3 compatibility. + [pbauer, hvelarde] + +## 3.0.5 (2018-02-04) + +Bug fixes: + +- Add Python 2 / 3 compatibility + [pbauer] + +## 3.0.4 (2017-11-24) + +Bug fixes: + +- Make sure the effects of the robotframework REMOTE_LIBRARY_ROBOT_TESTING fixture + are not accidentally removed when tearing down the PLONE_APP_DISCUSSION_ROBOT_TESTING fixture. + [davisagli] + +## 3.0.3 (2017-08-27) + +Bug fixes: + +- Show email in moderation view [ksuess] +- Remove plone.app.robotframework extras (reload and ride). + They are not needed and they are not Python 3 compatible. + [gforcada] + +## 3.0.2 (2017-07-03) + +New features: + +- Validate that author_email values are emails. + [ksuess] + +## 3.0.1 (2017-05-31) + +Bug fixes: + +- Remove unittest2 dependency + [kakshay21] + +## 3.0.0 (2017-02-12) + +Bug fixes: + +- Fixed tests with newer testbrowser. + [mauristvanrees] +- Remove deprecated \_\_of\_\_ calls on BrowserViews + [MrTango] +- Improve English on a couple of field descriptions + [djowett] +- Fix some easy pep8 issues + [djowett] + +## 2.4.20 (2017-01-17) + +Bug fixes: + +- Make comment on private content not publicly available in search results. + Part of PloneHotfix20161129. [vangheem, maurits] + +## 2.4.19 (2017-01-02) + +New features: + +- Reindex comments when they are modified. + [gforcada] + +## 2.4.18 (2016-09-20) + +Bug fixes: + +- Apply security hotfix 20160830 for redirects. [maurits] +- Update Traditional Chinese translation. + [l34marr] + +## 2.4.17 (2016-08-17) + +Bug fixes: + +- Use zope.interface decorator. + [gforcada] + +## 2.4.16 (2016-06-27) + +Bug fixes: + +- Cleaned code from flake8 errors. [maurits] +- Removed `comment-migration` view. This did not work anymore on + Plone 5. If you still need to migrate from old-style comments, so + from Plone 4.0 or earlier, please upgrade to Plone 4.3 first. + [maurits] + +## 2.4.15 (2016-06-12) + +Bug fixes: + +- Reset the required setting of the author_email widget each time. + Otherwise, the email field might get set to required when an + anonymous user visits, and then remain required when an + authenticated user visits, making it impossible for an authenticated + user to fill in the form without validation error. Or when in the + control panel the field is set as not required anymore, that change + would have no effect until the instance was restarted. [maurits] + +## 2.4.14 (2016-06-06) + +New features: + +- Make tests work with lxml safe html cleaner + +Bug fixes: + +- Fixed possible cross site scripting (XSS) attack on moderate comments page. [maurits] + +## 2.4.13 (2016-05-04) + +Fixes: + +- Removed docstrings from some methods to avoid publishing them. From + Products.PloneHotfix20160419. [maurits] + +## 2.4.12 (2016-04-13) + +Fixes: + +- Mark 'Edit' button for translation. + + [gforcada] + +## 2.4.11 (2016-03-31) + +New: + +- For the discussion controlpanel, change base URLs from portal URL to what getSite returns, but don't change the controlpanels context binding. + This allows for more flexibility when configuring it to be allowed on a sub site with a local registry. + [thet] + +Fixes: + +- fixed translate translation plone-ru.po + +## 2.4.10 (2016-02-08) + +New: + +- Added russian translations. [serge73] + +Fixes: + +- Get rid of the monkey patch on Products.CMFPlone's CatalogTool. + Issue + [staeff, fredvd] +- Cleanup code according to our style guide. + [gforcada] + +## 2.4.9 (2015-11-25) + +Fixes: + +- Update Site Setup link in all control panels (fixes ) + [davilima6] +- In tests, use `selection.any` in querystrings. + Issue + [maurits] +- Move translations to plone.app.locales + + [gforcada] + +## 2.4.8 (2015-09-20) + +- Use registry lookup for types_use_view_action_in_listings + [esteele] +- Remove discussion.css + [pbauer] +- Fix reply button not showing up since it uses a hide class which needs + to be removed instead of a display value + [ichim-david] + +## 2.4.7 (2015-09-15) + +- Tweak discussions.css styles to better live with plonetheme.barcelonata + [ichim-david] + +## 2.4.6 (2015-09-14) + +- Fix editing comments in Plone 5. + [pbauer] +- Move anonymous_email_enabled after anonymous_comments in controlpanel. + [pbauer] + +## 2.4.5 (2015-09-11) + +- Updated basque translation + [erral] + +## 2.4.4 (2015-07-18) + +- Change the category of the configlet to 'plone-general'. + [sneridagh] +- Updated links for the renamed 'Types' control panel. + [sneridagh] +- Updated Spanish translation. + [Caballero] + +## 2.4.3 (2015-06-05) + +- Update Spanish translation. + [macagua] +- Only use edit overlay if available for editing comments + [vangheem] + +## 2.4.2 (2015-05-04) + +- Update Japanese translation. + [takanory] +- Update Japanese translation. + [terapyon] +- Sort imports as per plone.api styleguide. + [gforcada] +- Fix flake8 errors reported by jenkins.plone.org. + [gforcada] + +## 2.4.1 (2015-03-26) + +- i18n for ICaptcha interface. + [davidjb] + +## 2.4.0 (2015-03-12) + +- use requirejs if available + [vangheem] +- Rename @@discussion-settings to @@discussion-controlpanel + [maartenkling] +- Add permission to allow comment authors to delete their own comments if + there are no replies yet. + [gaudenz] +- Updated portuguese pt-br translation. + [jtmolon] +- Read mail settings from new (Plone 5) registry. + [timo] +- Remove @property from Conversation.total_comments as @property and + Acquisition don't play well together. + [gforcada] + +## 2.3.3 (2014-10-23) + +- Don't execute createReplyForm js if there is no in_reply_to button. + [vincentfretin] +- Register events as Content Rules Event Types if plone.contentrules is present + [avoinea] +- Trigger custom events on comment add/remove/reply + [avoinea] +- Replace \$.live with \$.on for jQuery >= 1.9 compatibility. This works on + jQuery >= 1.7 (Plone 4.3 onwards). + [gaudenz] +- Update Traditional Chinese translations. + [marr] +- Make comments editable. + [pjstevns, gyst] +- Provide 'Delete comments' permission to handle comments deletion + [cekk] +- Fixed Italian translations [cekk] + +## 2.3.2 (2014-04-05) + +- bugfix: according to IDiscussionSettings.anonymous_email_enabled (cite): + "If selected, anonymous user will have to give their email." - But field + was not required. Now it is. + [jensens] +- bugfix: anonymous email field was never saved. + [jensens] +- updated german translations: added some missing msgstr. + [jensens] +- added i18ndude and a script `update_translations` to buildout in order + to make translation updates simpler. + [jensens] +- Fix reindexObject for content_object in moderation views. + Now reindex only "total_comments" index and not all the indexes + [cekk] +- Fix comments Title if utf-8 characters in author_name + [huub_bouma] +- use member.getId as author_username, so membrane users having different id + then username still have there picture shown and author path is correct. + [maartenkling] + +## 2.3.1 (2014-02-22) + +- 2.3.0 was a brown bag release. + [timo] + +## 2.3.0 (2014-02-22) + +- Remove DL's from portal message in templates. + + [khink] +- Execute the proper workflow change when using the moderation buttons instead + of hardcoding the workflow action to always publish + [omiron] +- Corrections and additions to the Danish translation + [aputtu] + +## 2.2.12 (2014-01-13) + +- Show author email to Moderator when it is available in anonymous comment. + [gotcha, smoussiaux] +- Put defaultUser.png instead of old defaultUser.gif + [bsuttor] +- Remove bbb directory. bbb was never really implemented. + [timo] +- Replace deprecated test assert statements. + [timo] +- Remove portal_discussion tool. + [timo] +- Refactor tests to use the PLONE_APP_CONTENTTYPES_FIXTURE instead of + PLONE_FIXTURE. + [timo] +- Fix ownership of comments. + [toutpt] + +## 2.2.10 (2013-09-24) + +- Revert "Refactor tests to use the PLONE_APP_CONTENTTYPES_FIXTURE instead of + the PLONE_FIXTURE." that has been accidentally introduced into the 2.2.9 + release. + [timo] + +## 2.2.9 (2013-09-24) + +- Portuguese translation added. + [Rui Silva] +- Rename CHANGES.txt to CHANGES.rst. + [timo] +- Fix ajax form submit for delete comment action: add 'data' to the request. + [toutpt] + +## 2.2.8 (2013-08-20) + +- Re-release 2.2.7 with .mo files. Seems like 2.2.7 has been released twice on + two different dates. The first release seems to be made without a github + push. + [timo] +- Fix comments viewlet's get_replies for non-annotatable objects. + [witsch] + +## 2.2.7 (2013-07-04) + +- making sure .mo files are present at release + [garbas] +- Revert change that silently added mime_type attribute values + to old discussion items that had none. + [pjstevns] + +## 2.2.6 (2013-05-23) + +- Fix migration to not fail when member has been deleted. + [datakurre] + +## 2.2.5 (2013-04-06) + +- Update pt_BR translation [ericof] +- Do not raise an error when no workflow is assigned to the comment type. + [timo] +- Add a conversation property public_commentators that only lists + commentators of comments that are public. + The commentators indexer indexes this field now. + The behavior of the conversation property commentators is + unchanged. + [do3cc] +- The last comment date now only returns the date of the newest + published comment. + [do3cc] + +## 2.2.4 (2013-03-05) + +- Check for 'checked' attribute in a way that work also for jQuery 1.7 + [ichimdav] +- Better fix for #13037 by removing submit event trigger altogether + [ichimdav] +- Added Romanian translation + [ichimdav] +- Updated Ukrainian translation + [kroman0] + +## 2.2.3 (2013-01-13) + +- add anonymous_email_enabled settings to really let integrator activate + the email field on comment add form when anonymous. + [toutpt] + +## 2.2.2 (2012-11-16) + +- first check if captcha is installed before we open browsers zcml + files that depend on these packages, fixes #12118 and #12774 + [maartenkling] + +## 2.2.1 (2012-11-16) + +- Make conversation view not break when comment-id cannot be converted to + long. This fixes #13327 + [khink] +- fix insufficient privileges when trying to view + the RSS feed of a comment collection + [maartenkling] +- removed inline border=0 and move it to css + [maartenkling] +- For migrations of comments without a valid old_status, apply the 'published' + state. + [thet] +- Re-apply eleddy's "Revert modification date since this is fixed in + p.a.caching now." as her commit was lost later on due to some git magic. + [thet] +- Remove submitting the controlpanel form again after removing disabled tags + fixes #13037 and #12357 + [maartenkling] +- Remove inline styles, fixes #12399 + [maartenkling] +- add fallback border color for i8, fixes #11324 + [maartenkling] +- Replace discussionitem_icon.gif with png version. + [timo] +- Fix catalog updates for IObjectMovedEvent + [gaudenz] +- Fix non-functioning user_notification feature + [izak] + +## 2.2.0 (2012-08-30) + +- Refactor the comment creator/author_name to comply with the Plone core + convention to store the username on the creator attribute and not the + fullname. + [timo] +- Rename the id of the text widgets because there can be css-id clashes with + the text field of documents when using TinyMCE in overlays or multiple + instances of TinyMCE on a single page. + [timo] +- text/html added to the possible mime types for comments. + [timo] +- Make 'text/plain' the default mime type for comments and make sure the + default type is set properly when creating a new comment. + [timo] +- Fix handling of comments with invalid transforms. Write an error msg + to the log and just return the untransformed text. + [timo] + +## 2.1.8 (unreleased) + +- Support for Dexterity added. The conversation enabled method now detects and + supports Dexterity-based content types. + [timo] +- No more recursive came_from redirection after logged_in. + [kcleong, huubbouma] +- Danish translation updated. + [stonor] +- Documentation and howtos updated. + [timo] +- Remove development buildout files and directories. + [timo] + +## 2.1.7 (2012-06-29) + +- Prune duplicated test code. + [pjstevns] +- Update version in buildout.cfg to allow development. + [pjstevns] +- Conversation.total_comments only counts published comments. + Fixes bug #11591. + [pjstevns] +- Set workflow status of comments during migration based on + the state of the Discussion Item. + [pjstevns] + +## 2.1.6 (2012-05-30) + +- Add Site Administrator role to Review comments permission. + [gaudenz] +- Fix excessive JS comment deletion. + [gaudenz] +- Hide Conversation objects from breadcrumb navigation. The breadcrumbs + navigation is also used in the search results view. This lead to Conversation + objects showing up if 'Discussion Items' are searchable. + [gaudenz] +- No longer depend on zope.app packages. + [hannosch] + +## 2.1.5 (2012-04-05) + +- Redirect to "/view" for Image, File and anything listed as requiring + a view in the url to properly display comments. + [eleddy] +- Make comments and controlpanel views more robust, so they don't break if no + workflow is assigned to the 'Discussion Item' content type. + [timo] +- Warning message added to discussion control panel that shows up if there are + unmigrated comments. + [timo] +- Make topic/collection tests pass when plone.app.collection is installed. + [timo] + +## 2.1.4 (2012-02-29) + +- Revert modification date since this is fixed in p.a.caching now. + [eleddy] +- Add missing meta_typ to "Review comments" portal action. + [batlock666] + +## 2.1.3 (2012-01-24) + +- Set modified date of object receiving comments so that caching works + correctly (304s) + [eleddy] + +## 2.1.2 (2011-12-21) + +- Fixed language code error in Ukrainian translation. The message + catalog was erroneously set to "English". + [chervol] +- Do not raise an error if the comment text is None. + [timo] +- Updated Spanish translation. + [hvelarde] +- Fix that catalog rebuild breaks the path attribute on comments. This fixes + . + [pjstevns] + +## 2.1.1 (2011-11-24) + +- Include mo files in the distribution. + [vincentfretin] +- Fix various text typos. + [timo] +- Fix control panel help text typos. + [jonstahl] +- Documentation about overriding the comments viewlet js added. + [timo] +- Corrected location of Japanese po file. + [tyam] + +## 2.1.0 (2011-08-22) + +- Avoid error when moving objects that are contentish but not annotatable. + [davisagli] +- New feature: Markdown syntax added to possible comment text transforms. + [timo] +- Make sure the comment brains are updated properly when the content object is + renamed. + [hannosch, timo] +- Make sure only comments to the content object are removed from the catalog + when the content object is moved. + [hannosch, timo, davisagli] +- Make sure the conversation.getComments method returns acquisition wrapped + comments. + [timo] +- Ukrainian translation added. + [chervol] +- Remove one_state_workflow customizations. + [timo] + +## 2.0.9 (2011-07-25) + +- Make sure the creator index always stores utf-8 encoded strings and not + unicode. + [timo] + +## 2.0.8 (2011-07-25) + +- Automatically reload batch moderation page if no comments are left. This + fixes . + [timo] +- Use Plone's safe_encode method instead of encode() for the creator index to + make sure unicode encoded strings can be indexed too. + [timo] + +## 2.0.7 (2011-07-15) + +- Fix discussion control panel submit for Google Chrome. This fixes + . + +## 2.0.6 (2011-07-04) + +- Update comment brains in zcatalog when moving a content object with comments. + This fixes . + [timo] +- Plone 3 specific exclusion of plone.app.uuid removed. + [timo] + +## 2.0.5 (2011-06-16) + +- Simplify CSS and JS registrations. CSS will now be imported using the + standard link and so can be merged, inserted after forms.css. JS will now be + imported after collapsibleformfields.js. + [elro] +- Enable the left-menu on the configlet, to be more consistent with all other + configlets. Related to + [WouterVH] +- Do not render/update the comment form in CommentViewlets if commenting is + disabled, since this slows down the page rendering. This fixes + + [fafhrd] + +## 2.0.4 (2011-05-28) + +- Refactor/clean up the handleComment method. + [timo] +- Make handleComment method store comment attributes from form extenders. This + allows us to extend the comment form with external add-ons. See + + for details. + [timo] + +## 2.0.3 (2011-06-19) + +- Updated Simplified Chinese translation + [jianaijun] +- Italian translation review. + [gborelli] + +## 2.0.2 (2011-05-12) + +- Moderation should be enabled only if there is a workflow set for Discussion + Item. + [erico_andrei] + +## 2.0.1 (2011-04-22) + +- Translations updated. German translations for notifications added. + [timo] +- Add links to delete/approve a comment in the moderator notification email. + [timo] +- Remove the unnecessary workflow_action parameter from the PublishComments + request. + [timo] +- Make sure the email settings in the control panel are disabled when commenting + is disabled globally. + [timo] +- Enable/disable moderator_email setting dynamically as mail settings or + discussion settings change. + [timo] +- Remove ImportError exceptions for Plone < 4.1 code and plone.z3cform < 0.6.0. + [timo] +- Provide the comment body text in the email notification. + [timo] +- Fix comment link in email notification. This fixes + . + [timo] +- Redirect to the comment itself when notifying a user about a new comment. + [timo] + +## 2.0 (2011-04-21) + +- No changes. + +## 2.0b2 (2011-04-21) + +- Added Japanese translation. + [tyam] +- Move all tests from testing layer to plone.app.testing. + [timo] +- Move some policy out of the conversation storage adapter into a + view, specifically "enabled()". Prevents having to replace/migrate + persistent objects to change policy which really only concerns the + context and possibly the request, not the conversation storage. + Fixes #11372. + [rossp] +- Fix unindexing of comments when deleting content resulting from + iterating over a BTree while modifying it. Fixes #11402. + [rossp] +- Fix Missing.Value for Creator in the catalog. Fixes #11634. + [rossp] +- Don't add the annotation unless a comment is actually being added. + Fixes #11370. + [rossp] +- Fixed i18n of the "Commenting has been disabled." message. + [vincentfretin] +- Add a moderator_email setting to control where moderator notifications are + sent. + [davisagli] + +## 2.0b1 (2011-04-06) + +- Make discussion.css cacheable when registering it. + [davisagli] +- Fix issue where GMT datetimes were converted into local timezone DateTimes + during indexing. + [davisagli] +- Handle timezones correctly while converting dates during the migration of + legacy comments. + [davisagli] +- When returning a comment's title, give preference to its title attribute + if set. + [davisagli] +- Use the cooked text of legacy comments when migrating. + [davisagli] +- Make sure that comment text is transformed to plain text when indexing. + [davisagli] +- Move logic for transforming comment text to the Comment class's getText + method. Use a comment instance's mime_type attribute in preference to the + global setting for the source mimetype. Use text/x-html-safe as the target + mimetype to make sure the safe HTML filter is applied, in case the source is + untrusted HTML. + [davisagli] +- Provide a filter_callback option to the migration view, so that a custom + policy for which comments get migrated can be implemented. + [davisagli] +- Fixed RoleManager import to avoid deprecation warning on Zope 2.13. + [davisagli] +- French translations. + [thomasdesvenain] +- Fixed internationalization issues. + [thomasdesvenain] +- Added Afrikaans translations + [jcbrand] + +## 2.0a3 (2011-03-02) + +- Fixed test failure for the default user portrait, which changed from + defaultUser.gif to defaultUser.png in Products.PlonePAS 4.0.5 + [maurits] + +## 2.0a2 (2011-02-08) + +- Fixed test failure for the default user portrait, which changed from + defaultUser.gif to defaultUser.png in Products.PlonePAS 4.0.5. + [maurits] +- Remove "Plone 3 only" code. + [timo] +- Do not monkey patch the BAD_TYPES vocabulary or plone.app.vocabularies + anymore. + [timo] + +## 2.0a1 (2011-02-07) + +- Split up development into two branches. The 1.x branch will be for Plone 3.x + and Plone 4.0.x and the 2.x branch will be for Plone 4.1 and beyond. + [timo] +- Import Owned from OFS.owner to avoid deprecation warnings. + [timo] +- Disable discussion by default. + [timo] +- Enable ajaxify comment deletion again ([thomasdesvenain]). This has been + disabled in 1.0b12 because of problems with Plone 3. + [timo] +- Remove collective.autopermission dependency that has become unnecessary in + Plone 4.1. + [timo] + +## 1.0 (2011-02-07) + +- Do not check for a comment review workflow when sending out a moderator email + notification. This fixes . + [timo] +- Check if the current user has configured an e-mail address for the email + notification option. This fixes . + [timo] + +## 1.0RC2 (2011-01-24) + +- Remove moderation_enabled setting from registry to avoid migration problems + to 1.0RC1. This fixes . + [timo] + +## 1.0RC1 (2011-01-22) + +- Always show existing comments, even if commenting is disabled. + [timo] +- Fix CSS for commenter images with a width of more than 2.5em. This fixes + . + [timo] +- Show a 'Comments are moderated.' message next to the comment form if comments + are moderated. + [timo] +- Make sure plone.app.registry's ZCML is loaded, so that its import step will run + when plone.app.discussion is installed. + [davisagli] +- Avoid sending multiple notification emails to the same person when + he has commented multiple times. + [maurits] +- Move discussion action item from actionicons.xml to actions.xml to avoid + deprecation warning. + [timo] +- Fix cancel button on edit view when using Dexterity types. This fixes + . + [EpeliJYU] +- Assigning the 'Reply to item' permission to the 'Authenticated' role. The old + commenting system allowed 'Authenticated' users to post comments. Also, OpenID + users do not possess the 'Authenticated' role. + [timo] +- Make sure the handleComment method checks for the 'Reply to item' permission + when adding a comment. + [timo] +- Make the mail-setting warning message show up in the discussion control panel. + [timo] +- Link directly to the "Discussion Item" types control panel in the moderation + view. + [timo] +- Show "moderate comments" link in the admin panel only if a moderation + workflow is enabled for comments. + [timo] +- Do not allow to change the mail settings in the discussion control panel, if + there is no valid mail setup. + [timo] +- Disable all commenting options in the discussion control panel if comments + are disabled globally. +- Check for the 'review comments' permission instead of 'manage' to decide + if the user should see a 'this comment is pending' message. + [timo] +- Move "moderate comments" site action above the logout action. + [timo] +- Moderator notification description updated. + [timo] +- Redirect back to the discussion control panel when the discussion control + panel form is submitted. + [timo] +- Fix document_byline bottom margin if commenter images are disabled. + [timo] +- Dynamically show the comment formatting message dependent on the text + transform setting. + [timo] +- Description for text transform added to the discussion control panel. + [timo] +- Move the discussion control panel to the core Plone configuration. + [timo] +- Always set the effective date of a comment to the same value as the creation + date. + [timo] +- Fix SMTP exception when an email is send to the moderator. + [timo] +- Make sure comment UIDs in the catalog are always unique. This fixes + . + [timo] +- Fix 'check all' on batch moderation page. + [davisagli] +- Use safe_unicode to decode the title of the content. encode("utf-9") caused + Dexterity based content types to raise a unicode decode error. This fixes + + [dukebody] +- Spanish translation updated. + [dukebody] +- Catalan translation added. + [sneridagh] +- Convert anonymous-supplied name to unicode as done for authenticated members. + [ggozad] +- Catch SMTP exceptions when sending email notifications. + [timo] +- Updated italian translation. + [keul] + +## 1.0b12 (2010-11-04) + +- Remove AJAX comment deletion binding. This function relies on the nextUntil() + selector introduced by jQuery 1.4 and therefore breaks in Plone 3 + (that currently uses jQuery 1.3.2). + [timo] + +## 1.0b11 (2010-11-03) + +- Fix Dutch and Czech language code and name. + [timo] +- Re-add the CommentsViewlet can_manage method. This method has been removed + in version 1.0b9 and added again in 1.0b11 because we don't want to change + the API in beta releases. + [timo] +- Declare z3c.form and zope.schema as minimum version dependencies in setup.py + in case people use a different KGS. + [timo] +- Add and update es and eu l10ns. + [dukebody, on behalf of erral] +- Ajaxify comment deletion and approval. + [thomasdesvenain] +- New feature: As a logged-in user, I can enable/disable email notification of + additional comments on this content object. + [timo] +- Disable the plone.app.registry check on schema elements, so no error is + raised on upgrades. This fixes . + [timo] +- Remove the too generic id attribute of the comment form. + [timo] +- Fixed handling of non-ascii member data, like fullname and email. + [hannosch] + +## 1.0b10 (2010-10-15) + +- Fixed "global name 'WrongCaptchaCode' is not defined" if norobots captcha, + but no other validation package is installed. + [naro] +- Check if there is a 'pending' review state in the current workflow for + comments instead of just checking for the 'comment_review_workflow'. This + allows integrators to use a custom review workflow. This fixes + . + [timo] +- fixed plone-it.po (improper language code ('en' instead of 'it')) + [ajung] + +## 1.0b9 (2010-10-07) + +- Replace the can_manage method with a can_review method that checks the + 'Review comments' permission. This fixes + . + [timo] +- Fix moderation actions (publish, delete) in the moderation view with virtual + hosts. This is a replacement for . + [timo] +- Do not show two "login to add comments" buttons when there are no comments + yet. This fixes . + [timo] + +## 1.0b8 (2010-10-04) + +- Apply the comment viewlet template and styles to the new title-less comments. + This might require integrators to apply their custom templates and styles. + [timo] +- Remove title field from the comment form and replace it with an auto-generated + title ("John Doe on Welcome to Plone"). + [timo] +- Fix : "Comment byline shows login + name, not full name" + [kiorky] +- Make sure the \_\_parent\_\_ pointer (the conversation) of a comment is not + acquisition wrapped in conversation.addComment. This fixes + . + [timo] +- Revert r35608 since this was breaking the comment moderation bulk actions. + The BulkActionsView expects the absolute path of the comments without the + portal url (e.g. '/plone/doc1/++conversation++default/1285346769126020'). + This fixes . + [timo] +- Use "(function(\$) { /\* some code that uses \$ \*/ })(jQuery)" instead of + "\$(document).ready(function(){ /\* some code that uses \$ \*/ });" to invoke + jQuery code. + [timo] +- Finnish translation added. + [saffe] +- Italian translation updated. + [keul] + +## 1.0b7 (2010-09-15) + +- Captcha plugin support for collective.z3cform.norobots (version >= 1.1) added. + [saffe] +- Store dates in utc and not in local time. Display local time + [do3cc] +- Fetch context for the comment view with "context = aq_inner(self.context)". + [timo] +- Raise an unauthorized error when authenticated users try to post a comment + on a content object that has discussion disabled. Thanks to vincentfrentin + for reporting this. + [timo] +- Czech translation added. + [naro] +- Clean up code with PyLint. + [timo] +- Make Javascripts pass JSLint validation. + [timo] +- Put email notification subscribers into their own zcml file so it is easier + for integrators to override them. + [timo] +- Plain text and intelligent text options for comment text added to preserve + basic text structure and to make links clickable. + [timo] +- Rewrote all tal:condition in comments.pt. The authenticated user has + the reply button and the comment form if he has the "Reply to item" + permission And the discussion is currently allowed. + [vincentfretin] + +## 1.0b6 (2010-08-24) + +- Fixed the case where a folder has allow_discussion=False and + conversation.enabled() on a document in this folder returned False + instead of True because of allow_discussion acquisition. + [vincentfretin] +- Redirect to the comment form action instead of the absolute URL when a + comment is posted. This fixes the accidentally triggered file upload when a + comment is posted on a file content object. + [timo] +- We need five:registerPackage to register the i18n folder. + [vincentfretin] +- Added Traditional Chinese (zh_TW) translation. + [TsungWei Hu] +- Added French translation. + [vincentfretin] +- Renamed legend_add_comment to label_add_comment to have the translation from + plone domain. + [vincentfretin] +- label_comment_by and label_commented_at are not in Plone 4 translation + anymore, so these two messages moved to plone.app.discussions i18n domain. + [vincentfretin] +- Translate "Warning" shown in @@moderate-comments in the plone domain. + [vincentfretin] +- Fixed i18n markup of message_moderation_disabled. + [vincentfretin] +- Catch Type errors in indexers if object can not be adapted to IDiscussion + [do3cc] +- Call the CaptchaValidator even when no captcha data was submitted. This is + necessary to ensure that the collective.akismet validator is called when + installed. + [timo] +- Spanish translation added. Thanks to Judith Sanleandro. + [timo] + +## 1.0b5 (2010-07-16) + +- Use self.form instead of CommentForm for the CommentsViewlet update method so + integrators don't have to override the viewlet's update method. + [matous] +- Make sure the form fields in the reply form are always placed under the field + labels. + [timo] +- Fix CSS overflow bug that occurs with the new Plone 4.0b5 comment styles. + [timo] +- Unnecessary imports and variables removed. + [timo] +- Added norwegian translation. + [ggozad] +- Protect against missing canonical in conversationCanonicalAdapterFactory. + [hannosch] +- Documentation for Captcha plugin architecture and email notification added. + See . + [timo] +- Use sphinx.plonetheme for plone.app.discussion documentation. + [timo] +- Avoid deprecation warning for the Globals package. + [hannosch] +- Remove the hard coded check for title and text when the comment form is + submitted. This allows integrators to write schema extenders that remove the + title from the comment form. + [timo] +- Move captcha registration to its own captcha.zcml file. + [timo] +- Akismet () spam protection plugin (collective.akismet) + support added. + [timo] +- Simplify the CaptchaValidator class by dynamically adapting a view with the + name of the captcha plugin (e.g. recaptcha, captcha, akismet) for the + validator. + [timo] +- Dutch translation added. + [kcleong] +- Enable caching and merging for comments.js to save some requests. + [pelle] +- Design notes for the Captcha plugin architecture added. + [timo] +- Make IDiscussionLayer inherit from Interface again. Remove IDefaultPloneLayer, + since Plone 4.0b1 and plone.theme 2.0b1 are out now. + [timo] +- Clean up Javascript code. + [timo] +- Fix encoding error in migration procedure, otherwise migration procedure + breaks on joining output list in case we have there any non-ascii characters. + [piv] +- plone.z3cform 0.6.0 compatibility (fix maximum recursion depth error which + appears with plone.z3cform higher than 0.5.10). + [piv] +- Removed moderation.js from js registry and include it only in moderation.pt as + that is the only place where it is used. + [ggozad] + +## 1.0b4 (2010-04-04) + +- New feature: As a moderator, I am notified when new comments require my + attention. + [timo] +- Sphinx-based developer documentation added. See + . + [timo] +- Rename "Single State Workflow" to "Comment Single State Workflow". + [timo] +- Rename 'publish comment' to 'approve comment'. This fixes #1608470. + [timo] +- Show a warning in the moderation view if the moderation workflow is disabled. + [timo] +- Move 'Moderate comments' link from site actions to user actions. + [timo] +- Fix #662654: As an administrator, I can configure a Collection to show recent + comments. Comment.Type() now correctly returns the FTI title ('Comment') + [chaoflow] +- German translation updated. + [juh] +- Fix #2419342: Fix untranslated published/deleted status messages. + [timo] +- Remove fixed width of the actions column of the moderation view. The + translated button titles can differ in size from the English titles. + [timo] +- Fix #2494228: Remove comments as well when a content object is deleted. + [timo] +- Fix unicode error when non-ASCII characters are typed into the name field of a + comment by anonymous users. + [regebro] +- Make p.a.d. work with the recent version of plone.z3cform (0.5.10) + [timo] +- Make p.a.d. styles less generic. This fixes #10253. + [timo] +- Added greek translation. + [ggozad] +- A bug in the moderator panel meant you couldn't delete items in a virtual + host, if your portal was named "plone". + [regebro] + +## 1.0b3 (2010-01-28) + +- Added an i18n directory for messages in the plone domain and updated scripts + to rebuild and sync it. + [hannosch] +- Added an optional conversationCanonicalAdapterFactory showing how to share + comments across all translations with LinguaPlone, by storing and retrieving + the conversation from the canonical object. + [hannosch] +- Play by the Plone 3.3+ rules and use the INavigationRoot as a base for the + moderation view. + [hannosch] +- Added a commentTitle CSS class to the comment titles. + [hannosch] +- Update message ids to match their real text. + [hannosch] +- Set CSS classes for the comment form in the updateActions method. + [timo] +- Respect the allow_comments field on an object and avoid calculations if no + comments should be shown. + [hannosch] +- Automatically load the ZCML files of the captcha widgets if they are + installed. + [hannosch] +- Fixed i18n domain in GenericSetup profiles to be `plone`. Other values + aren't supported for GS profiles. + [hannosch] +- Provide our own copy of the default one state workflow. Not all Plone sites + have this workflow installed. + [hannosch] +- Register the event subscribers for the correct interfaces in Plone 3. + [hannosch] +- Factored out subscriber declarations into its own ZCML file. + [hannosch] +- Bugfix for #2281226: Moderation View: Comments disappear when hitting the + 'Apply' button without choosing a bulk action. + [timo] +- Allow to show the full text of a comment in the moderation view. + [timo] +- German translation added. + [timo] +- Italian translation added. + [keul] + +## 1.0b2 (2010-01-22) + +- Bugfix for #2010181: The name of a commenter who commented while not logged in + should not appear as a link. + [timo] +- Bugfix for #2010078: Comments that await moderation are visually distinguished + from published comments. + [timo] +- Bugfix for #2010085: Use object_provides instead of portal_type to query the + catalog for comment. + [timo] +- Bugfix for #2010071: p.a.d. works with plone.z3cform 0.5.7 and + plone.app.z3cform 0.4.9 now. + [timo] +- Bugfix for #1513398: Show "anonymous" when name field is empty in comment + form. + [timo] +- Migration view: Dry run option added, abort transaction when something goes + wrong during migration, be more verbose about errors. + [timo] + +## 1.0b1 (2009-12-08) + +- Fix redirect after a adding a comment + [timo] +- Replace yes/no widgets with check boxes in the discussion control panel + [timo] +- Make comments viewlet show up in Plone 4 + [timo] +- Apply Plone 4 styles to comment form + [timo] +- Simplify moderation view by removing the filters + [timo] + +## 1.0a2 (2009-10-18) + +- Plone 4 / Zope 2.12 support + [timo] +- Comment migration script added + [timo] +- Pluggable plone.z3cform comment forms + [timo] +- Captcha and ReCaptcha support added + [timo] + +## 1.0a1 (2009-06-07) + +- Basic commenting functionality and batch moderation. + [timo] diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 00000000..e6bbd96d --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,10 @@ +--- +myst: + html_meta: + "description": "Contributing - plone.app.discussion documentation" + "property=og:description": "Contributing - plone.app.discussion documentation" + "property=og:title": "Contributing" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +Please see diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..0f09ee60 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,52 @@ +--- +myst: + html_meta: + "description": "Introduction - plone.app.discussion documentation" + "property=og:description": "Introduction - plone.app.discussion documentation" + "property=og:title": "Introduction" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +# Introduction + +plone.app.discussion is the commenting add-on for Plone. +It is part of the maintained Plone core. + +# Installation + +If your installation depends on the [Plone](https://pypi.org/project/Plone/) package, you can install it via the Plone control panel. +In case you do only depend on either the `plone.volto`, `plone.classicui` or `Products.CMFPlone` package, you need to add it to your requirements file. +After adding it and installing the requirement, you can install it via the Plone control panel. + +# Spam protection + +These days it is essential to protect your site from commenting spam. +The following add-ons can help to protect your site: + +- [plone.formwidget.captcha](https://pypi.org/project/plone.formwidget.captcha/) + (for Captcha spam protection) +- [plone.formwidget.recaptcha](https://pypi.org/project/plone.formwidget.recaptcha/) + (for ReCaptcha spam protection) +- [collective.z3cform.norobots](https://pypi.org/project/collective.z3cform.norobots/) + (provides a "human" captcha widget based on a list of questions/answers) +- [plone.formwidget.hcaptcha](https://pypi.org/project/plone.formwidget.hcaptcha/) + (for spam protection by [HCaptcha](https://www.hcaptcha.com/) ) + +# Documentation + +For further information, please refer to the [official Plone documentation](https://docs.plone.org/). + +# Credits + +This package was initially developed as part of the Google Summer of Code 2009 by Timo Stollenwerk (student) and Martin Aspeli (mentor). + +Many thanks to: + +- Jon Stahl (for acting as "the customer" during GSoC) +- David Glick (for technical expertise and advice during GSoC) +- Lennart Regebro (for writing the portal_discussion tool and initial unit tests) +- Carsten Senger (for fixing the comment z3c.form form and pizza) +- Hanno Schlichting (for making p.a.d work with Zope 2.12) +- Alan Hoey (for providing fixes) +- Maik Roeder (for providing and setting up a buildbot) +- Jens Klein (for ripping it out of core and making it a separate core-addon for Plone 6.1) diff --git a/docs/_toc.yml b/docs/_toc.yml index 8642f302..204ad0b2 100644 --- a/docs/_toc.yml +++ b/docs/_toc.yml @@ -2,7 +2,6 @@ root: index entries: - file: architecture - file: auto-approve -- file: auto_approve - file: components/index entries: - file: components/behavior @@ -16,4 +15,23 @@ entries: - file: components/restapi - file: components/tool - file: components/viewlet +- file: captcha +- file: design +- file: email-notification +- file: workflow +- file: api/index + entries: + - file: api/comment + - file: api/conversation +- file: howtos/index + entries: + - file: howtos/howto_extend_the_comment_form + - file: howtos/howto_make_pad_work_with_a_dexterity_content_type + - file: howtos/howto_override_comments_viewlet + - file: howtos/howto_override_enable_conversation + - file: howtos/howto_set_discussion_settings_with_generic_setup + - file: howtos/howto_write_a_custom_email_notification +- file: README +- file: CHANGES +- file: CONTRIBUTING diff --git a/docs/api/comment.md b/docs/api/comment.md new file mode 100644 index 00000000..4094a0d9 --- /dev/null +++ b/docs/api/comment.md @@ -0,0 +1,12 @@ +--- +myst: + html_meta: + "description": "Comment - plone.app.discussion documentation" + "property=og:description": "Comment - plone.app.discussion documentation" + "property=og:title": "Comment" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +```{eval-rst} +.. include:: ../../../plone/app/discussion/comment.txt +``` diff --git a/docs/api/conversation.md b/docs/api/conversation.md new file mode 100644 index 00000000..94c7e837 --- /dev/null +++ b/docs/api/conversation.md @@ -0,0 +1,12 @@ +--- +myst: + html_meta: + "description": "Conversation - plone.app.discussion documentation" + "property=og:description": "Conversation - plone.app.discussion documentation" + "property=og:title": "Conversation" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +```{eval-rst} +.. include:: ../../../plone/app/discussion/conversation.txt +``` diff --git a/docs/source/api/index.txt b/docs/api/index.md similarity index 62% rename from docs/source/api/index.txt rename to docs/api/index.md index 5961046f..d28564d3 100644 --- a/docs/source/api/index.txt +++ b/docs/api/index.md @@ -1,6 +1,13 @@ -=== -API -=== +--- +myst: + html_meta: + "description": "API - plone.app.discussion documentation" + "property=og:description": "API - plone.app.discussion documentation" + "property=og:title": "API" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +# API The conversation and replies adapters. @@ -13,9 +20,9 @@ directly in reply to a particular comment (implemented by the CommentReplies adapter) or at the top level of the conversation (implemented by the ConversationReplies adapter). +```{toctree} +:maxdepth: 1 -.. toctree:: - :maxdepth: 1 - - conversation.txt - comment.txt +conversation.txt +comment.txt +``` diff --git a/docs/architecture.md b/docs/architecture.md index c059d4c2..be1ae88c 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,50 +1,12 @@ --- myst: html_meta: - "description": "Architectural Principles of plone.app.discussion" - "property=og:description": "Architectural Principles of plone.app.discussion" - "property=og:title": "Architectural Principles" - "keywords": "Plone, Discussion, Architecture, Comments, Design" + "description": "Architecture - plone.app.discussion documentation" + "property=og:description": "Architecture - plone.app.discussion documentation" + "property=og:title": "Architecture" + "keywords": "Plone, Discussion, Comments, Documentation" --- -# Architectural Principles - -This document outlines architectural principles used in the design of plone.app.discussion. - -## Core Design Principles - -**Discussion items have a portal_type** -: This makes it easier to search for them and manage them using existing CMF and Plone UI constructs. - -**Discussion items are cataloged** -: It is possible to search for discussion items like any other type of content. - -**Discussion items are subject to workflow and permission** -: Moderation, anonymous commenting, and auto-approve/reject should be handled using workflow states, automatic and manual transitions, and permissions. - -**Discussion items are lightweight objects** -: Discussion item objects are as lightweight as possible. Ideally, a discussion item should be as lightweight as a catalog brain. This may mean that we forego convenience base classes and re-implement certain interfaces. Comments should not provide the full set of Dublin Core metadata, though custom indexers can be used to provide values for standard catalog indexes. - -**Optimise for retrieval speed** -: Most users will be reading comments, not posting them. HTML filtering and other processing should happen on save, not on render, to make rendering quick. - -**Settings are stored using plone.registry** -: Any global setting should be stored in plone.registry records. - -**Forms are constructed using extensible z3c.form forms** -: This allows plugins (such as spam protection algorithms) to provide additional validation. It also allows integrators to write add-ons that add new fields to the comment form. - -**Discussion items are stored in a BTree container** -: This allows faster lookup and manipulation. - -**Discussion items are accessed using a dict-like interface** -: This makes iteration and manipulation more natural. Even if comments are not stored threaded, the dict interface should act as if they are, i.e. calling items() on a comment should return the replies to that comment (in order). - -**Discussion items are retrieved in reverse creation date order** -: Discussion items do not need to support explicit ordering. They should always be retrieved in reverse creation date order (most recent for). They can be stored with keys so this is always true. - -**Discussion items do not need readable ids** -: Ids can be based on the creation date. - -**Discussion items send events** -: The usual zope.lifecycleevent and zope.container events are fired when discussion items are added, removed, or modified. +```{eval-rst} +.. include:: ../../plone/app/discussion/architecture.txt +``` diff --git a/docs/auto_approve.rst b/docs/auto_approve.rst deleted file mode 100644 index 011e63df..00000000 --- a/docs/auto_approve.rst +++ /dev/null @@ -1,44 +0,0 @@ -Automatic Comment Approval -========================== - -Introduction ------------ - -This feature enhances the Plone discussion system by automatically approving comments from users -who have the "Review comments" permission, even when comment moderation is enabled site-wide. - -How It Works ------------ - -When a user with the "Review comments" permission creates a comment, the system will: - -1. Check if comment moderation is enabled -2. Verify if the user has the "Review comments" permission -3. Automatically publish the comment if both conditions are met - -This functionality is particularly useful for: - -- Trusted community members -- Moderators who should bypass the moderation queue -- Site editors or staff members - -Configuration ------------- - -No additional configuration is needed. Simply assign the "Review comments" permission to -the roles or users you want to bypass moderation. - -Examples: - -- Assign "Review comments" permission to the Editor role -- Create a "Trusted Commenter" role with the "Review comments" permission -- Give specific users the permission on specific content - -Permission Management -------------------- - -The "Review comments" permission can be managed: - -- Site-wide through the Security control panel -- On specific folders or content items through the Sharing tab -- Programmatically using the Plone security APIs diff --git a/docs/captcha.md b/docs/captcha.md new file mode 100644 index 00000000..e4ebf9dd --- /dev/null +++ b/docs/captcha.md @@ -0,0 +1,12 @@ +--- +myst: + html_meta: + "description": "Captcha - plone.app.discussion documentation" + "property=og:description": "Captcha - plone.app.discussion documentation" + "property=og:title": "Captcha" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +```{eval-rst} +.. include:: ../../plone/app/discussion/browser/captcha.txt +``` diff --git a/docs/design.md b/docs/design.md new file mode 100644 index 00000000..910b525d --- /dev/null +++ b/docs/design.md @@ -0,0 +1,12 @@ +--- +myst: + html_meta: + "description": "Design - plone.app.discussion documentation" + "property=og:description": "Design - plone.app.discussion documentation" + "property=og:title": "Design" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +```{eval-rst} +.. include:: ../../plone/app/discussion/design.txt +``` diff --git a/docs/email-notification.md b/docs/email-notification.md new file mode 100644 index 00000000..ecad8c75 --- /dev/null +++ b/docs/email-notification.md @@ -0,0 +1,80 @@ +--- +myst: + html_meta: + "description": "Email Notification - plone.app.discussion documentation" + "property=og:description": "Email Notification - plone.app.discussion documentation" + "property=og:title": "Email Notification" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +# Email Notification + +This document describes the plone.app.discussion email notification feature. + +## Introduction + +plone.app.discussion allows users and administrators to be notified about new +comments by email. There are two kinds of email notification: + +1. **User notification**: Tell users when a comment has been added. + + This method composes and sends emails to all users that have added a comment + to this conversation and enabled user notification. + + This requires the user_notification setting to be enabled in the discussion + control panel. + +2. **Moderator notification**: Tell the moderator when a comment needs attention. + + This method sends an email to the site admin (mail control panel setting) if + comment moderation is enabled and a new comment has been added that needs to + be approved. + + This requires the moderator_notification to be enabled in the discussion + control panel and the comment_review_workflow enabled for the comment content + type. + +:::{note} +The user notification feature requires z3c.form >= 2.3.3. +::: + +## User Notification + +*plone/app/discussion/comment.py* + +```{literalinclude} ../../plone/app/discussion/comment.py +:encoding: utf-8 +:language: python +:pyobject: notify_user +``` + +## Moderator Notification + +*plone/app/discussion/comment.py* + +```{literalinclude} ../../plone/app/discussion/comment.py +:encoding: utf-8 +:language: python +:pyobject: notify_moderator +``` + +## Event Subscribers + +Email notifications are triggered by event subscribers that are called when a +comment has been added to a page. + +:::{note} +In Plone 3, the event subscribers were located in the zope.lifecycleevent +package. They moved to zope.app.container in Plone 4. Therefore +plone.app.discussion registers one of the two subscribers, dependent on the +Plone version. +::: + +To create custom email notifications, register a new event subscriber or +override an existing one. + +*plone/app/discussion/notifications.zcml* + +```{literalinclude} ../../plone/app/discussion/notifications.zcml +:encoding: utf-8 +``` diff --git a/docs/howtos/howto_extend_the_comment_form.md b/docs/howtos/howto_extend_the_comment_form.md new file mode 100644 index 00000000..c500ee3a --- /dev/null +++ b/docs/howtos/howto_extend_the_comment_form.md @@ -0,0 +1,173 @@ +--- +myst: + html_meta: + "description": "Howto extend the comment form with additional fields - plone.app.discussion documentation" + "property=og:description": "Howto extend the comment form with additional fields - plone.app.discussion documentation" + "property=og:title": "Howto extend the comment form with additional fields" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +# Howto extend the comment form with additional fields + +This document explains how to extend the plone.app.discussion comment form with +additional fields in an add-on product. + +plone.app.discussion uses the +[plone.z3cform.fieldsets](http://pypi.python.org/pypi/plone.z3cform#fieldsets-and-form-extenders) +package which provides support for modifications via "extender" adapters. The +idea is that a third party component can modify the fields in a form and the +way that they are grouped and ordered. + +:::{note} +This howto applies only to plone.app.discussion >= 2.0.4 and >= 1.1.2. Prior +versions will not store the extended fields on the comment. +::: + +:::{seealso} +The source code of this howto can be found here: + +::: + +## Howto extend the comment form with an additional "website" field + +First, create a new plone package: + +``` +$ paster create -t plone example.commentextender +``` + +Go to the main directory of the package +(example.commentextender/example/commentextender) and create a new file +*commentextender.py*. + +This file contains the ICommentExtenderFields interface definition with a +"website" field, a persistent CommentExtenderFields class to store the value of +the "website" field, a CommentExtenderFactory to create the +CommentExtenderFields, and a CommentExtender class to extend the default +comment form with the "website" field: + +``` +from persistent import Persistent + +from z3c.form.field import Fields + +from zope import interface +from zope import schema + +from zope.annotation import factory +from zope.component import adapter +from zope.interface import Interface +from zope.publisher.interfaces.browser import IDefaultBrowserLayer + +from plone.z3cform.fieldsets import extensible + +from plone.app.discussion.browser.comments import CommentForm +from plone.app.discussion.comment import Comment + +# Interface to define the fields we want to add to the comment form. +class ICommentExtenderFields(Interface): + website = schema.TextLine(title="Website", required=False) + +# Persistent class that implements the ICommentExtenderFields interface +@adapter(Comment) +class CommentExtenderFields(Persistent): + interface.implements(ICommentExtenderFields) + website = "" + +# CommentExtenderFields factory +CommentExtenderFactory = factory(CommentExtenderFields) + +# Extending the comment form with the fields defined in the +# ICommentExtenderFields interface. +@adapter(Interface, IDefaultBrowserLayer, CommentForm) +class CommentExtender(extensible.FormExtender): + fields = Fields(ICommentExtenderFields) + + def __init__(self, context, request, form): + self.context = context + self.request = request + self.form = form + + def update(self): + # Add the fields defined in ICommentExtenderFields to the form. + self.add(ICommentExtenderFields, prefix="") + # Move the website field to the top of the comment form. + self.move('website', before='text', prefix="") +``` + +:::{seealso} +- See the plone.z3cform pypi page for more documentation about how to add, + hide, and reorder fields: + +::: + +Now register the CommentExtenderFactory and CommentExtender Classes that has +been created by adding the following lines to your configure.zcml: + +``` + + + +``` + +Create a new Plone instance, globally allow commenting, allow commenting on a +content object and you will see a comment form with an additional "website" +field. + +Since we do not only want to store the "website" value on the comments, but also +to show these values for existing comments, we have to override the comments +viewlet. The easiest way to do this is to use z3c.jbot. + +First, add [z3c.jbot](http://pypi.python.org/pypi/z3c.jbot). to the setup.py +of the example.commentextender package: + +``` +install_requires=[ + ... + 'z3c.jbot', +], +``` + +Next, create a new directory called "overrides" inside the +example.commentextender package and register it together with z3c.jbot in your +configure.zcml: + +``` + + + ... + + + + + + +``` + +Copy plone.app.discussion/plone/app/discussion/browser/comments.pt to the +overrides directory we just created and rename comments.pt to +plone.app.discussion.browser.comments.pt. + +You can now add code to show the website attribute to the documentByLine: + +``` +
+ ... +
+ +
+
+``` + +Restart your Plone instance and you will see the "website" field in the +documentByLine next to the comments. diff --git a/docs/howtos/howto_make_pad_work_with_a_dexterity_content_type.md b/docs/howtos/howto_make_pad_work_with_a_dexterity_content_type.md new file mode 100644 index 00000000..63672460 --- /dev/null +++ b/docs/howtos/howto_make_pad_work_with_a_dexterity_content_type.md @@ -0,0 +1,56 @@ +--- +myst: + html_meta: + "description": "How to make plone.app.discussion work with a dexterity content type - plone.app.discussion documentation" + "property=og:description": "How to make plone.app.discussion work with a dexterity content type - plone.app.discussion documentation" + "property=og:title": "How to make plone.app.discussion work with a dexterity content type" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +# How to make plone.app.discussion work with a dexterity content type + +This document explains how to make plone.app.discussion work with a custom +dexterity content type. + +XXX: TODO + +configure.zcml: + +``` + +``` + +Define an interface IMyDexterityContentType groked schema, I added: + +``` +allowDiscussion = schema.Bool( + title=_("Allow Users to Comment"), + description=_("Allow users to comment on you. Comments +``` + +are shown at the end of each page"), + +: > required=True, + > default=True, + + ) + +and added this class: + +from plone.app.discussion.browser.comments import CommentsViewlet +class ConversationView(object): + +> """ Ability to either allow / disallow comments based on schema + +option + +: """ + def enabled(self): + + > return getattr(self.context, 'allowDiscussion', False) diff --git a/docs/howtos/howto_override_comments_viewlet.md b/docs/howtos/howto_override_comments_viewlet.md new file mode 100644 index 00000000..dc8edb20 --- /dev/null +++ b/docs/howtos/howto_override_comments_viewlet.md @@ -0,0 +1,154 @@ +--- +myst: + html_meta: + "description": "How to override plone.app.discussion's comments viewlet - plone.app.discussion documentation" + "property=og:description": "How to override plone.app.discussion's comments viewlet - plone.app.discussion documentation" + "property=og:title": "How to override plone.app.discussion's comments viewlet" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +# How to override plone.app.discussion's comments viewlet + +This document explains how to override the plone.app.discussion comments +viewlet that controls the way existing comments are displayed. + +There are three different ways to override plone.app.discussion's comments +viewlet: through-the-web, on the file system with z3c.jbot, and by overriding +the comments viewlet class on the file system. + +Overriding the comments viewlet template throught-the-web is the quick and +dirty approach. Using z3c.jbot is the recommended approach if you just want to +override the comments viewlet template. If you want full control over the +comments viewlet class, for instance if you want to add/customize view methods, +overriding the comments viewlet class on the file system is the recommended +approach. + +## Override the comments template through-the web + +Overriding the comments template through-the web is the easiest way to +customize the comments viewlet: + +``` +* Go to the ZMI (http://localhost:8080/Plone/manage_main) +* Click on "portal_view_customizations" +* Customize plone.comments (plone.app.discussion.interfaces.IDiscussionLayer) +``` + +## Override the comments template with z3c.jbot on the file system + +The easiest way to override the comments template on the file +system is with [z3c.jbot]. [z3c.jbot] allows you to override any +Plone template just by putting a file in a specific directory. + +`z3c.jbot`:: + +Add z3c.jbot to the dependencies of your package by adding a +line to your setup.py file: + +``` +install_requires=[ + ... + 'z3c.jbot', +], +``` + +Register an overrides directory where you can put your file +overrides in your configure.zcml file: + +``` + + + +``` + +Replace \ with a custom browserlayer of your package. + +Create the template directory we just registered: + +``` +$ mkdir overrides +``` + +Copy the comments viewlet template we want to override to the +overrides directory we just created and registered: + +``` +$ cp ../parts/omelette/plone/app/discussion/browser/comments.pt overrides/plone.app.discussion.browser.comments.pt +``` + +Restart your Plone instance and you can start to customize +the plone.app.discussion.browser.comments.pt we just created. + +## Override the comments viewlet class on the file system + +Overriding/subclassing the comments viewlet class is allows you not only to +override the comments viewlet template, but also the comment viewlets view +methods. There are many ways to override components in Plone with the Zope +Component Architecture (ZCA), which is beyond the scope of this howto. + +We are going to register our own browserlayer + +First we define our browser layer in interfaces.py: + +``` +from plone.app.discussion.interfaces import IDiscussionLayer + +class IMyDiscussionLayer(IDiscussionLayer): + """Marker interface for a custom plone.app.discussion browser layer + """ +``` + +Next, we register the browserlayer in our generic setup (GS) setup in the +profiles/default/browserlayer.xml file: + +``` + + + + +``` + +configure.zcml: + +``` + + +``` + +note: Note that we override the comments viewlet by using the my.discussion.interfaces.IMyDiscussionLayer browser layer and not the default plone.app.discussion.interfaces.IDiscussionLayer browser layer. + +Once we registered the custom discussion browser layer and the viewlet, we can create a +comments.py file with our custom version of the comments viewlet: + +``` +from Products.Five.browser.pagetemplatefile import ViewPageTemplateFile + +from plone.app.discussion.browser.comments import CommentsViewlet as PloneAppDiscussionCommentsViewlet +from plone.app.discussion.browser.comments import CommentForm + + +class CommentsViewlet(PloneAppDiscussionCommentsViewlet): + + form = CommentForm + index = ViewPageTemplateFile('comments.pt') + + def get_commenter_home_url(self, username=None): + if username is None: + return None + else: + return "%s/memberhome/%s" % (self.context.portal_url(), username) +``` + +To override the comments viewlet template, we create a comment.pt file in the +same directory and copy the contents from the original. diff --git a/docs/howtos/howto_override_enable_conversation.md b/docs/howtos/howto_override_enable_conversation.md new file mode 100644 index 00000000..1d2e3613 --- /dev/null +++ b/docs/howtos/howto_override_enable_conversation.md @@ -0,0 +1,80 @@ +--- +myst: + html_meta: + "description": "Howto override the enable_conversation method. - plone.app.discussion documentation" + "property=og:description": "Howto override the enable_conversation method. - plone.app.discussion documentation" + "property=og:title": "Howto override the enable_conversation method." + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +# Howto override the enable_conversation method. + +plone.app.discussion way to decide if commenting is enabled on a content +object can be quite complex and cumbersome due to the need to be backward +compatible with the way the old commenting system in Plone (\<4.1) worked. + +The comments viewlet calls the enabled method of the ConversationView to +decide if the add comment form should show up: + +```{literalinclude} ../../../plone/app/discussion/browser/conversation.py +:language: python +:pyobject: ConversationView +``` + +If you want to override this behavior, you just have to create your own enabled method. To do so, we first have to register our custom +ConversationView by overriding the existing one in our configure.zcml: + +``` + + + + + + +``` + +Now we implement the conversation view with a single "enable" method in +conversation.py: + +``` +from zope.component import queryUtility + +from plone.registry.interfaces import IRegistry + +from Acquisition import aq_inner + +from Products.CMFCore.utils import getToolByName + +from plone.app.discussion.interfaces import IDiscussionSettings + + +class ConversationView(object): + + def enabled(self): + context = aq_inner(self.context) + + # Fetch discussion registry + registry = queryUtility(IRegistry) + settings = registry.forInterface(IDiscussionSettings, check=False) + + # Check if discussion is allowed globally + if not settings.globally_enabled: + return False + + # Check if discussion is allowed on the content object + if context.allow_discussion is not None: + return context.allow_discussion + + # Check if discussion is allowed on the content type + portal_types = getToolByName(self, 'portal_types') + document_fti = getattr(portal_types, context.portal_type) + return document_fti.getProperty('allow_discussion') +``` diff --git a/docs/howtos/howto_set_discussion_settings_with_generic_setup.md b/docs/howtos/howto_set_discussion_settings_with_generic_setup.md new file mode 100644 index 00000000..407b095e --- /dev/null +++ b/docs/howtos/howto_set_discussion_settings_with_generic_setup.md @@ -0,0 +1,127 @@ +--- +myst: + html_meta: + "description": "How to set discussion settings with generic setup - plone.app.discussion documentation" + "property=og:description": "How to set discussion settings with generic setup - plone.app.discussion documentation" + "property=og:title": "How to set discussion settings with generic setup" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +# How to set discussion settings with generic setup + +This document explains how to set plone.app.discussion's settings with a +generic setup profile. + +plone.app.discussion uses plone.app.registry to store its global settings. +You can set or override the settings in the registry.xml file of your generic +setup profile: + +``` + + + + False + help_anonymous_comments + False + label_anonymous_comments + + False + + + + disabled + help_captcha + label_captcha + plone.app.discussion.vocabularies.CaptchaVocabulary + + disabled + + + + False + help_globally_enabled + False + label_globally_enabled + + False + + + + False + help_moderation_enabled + False + label_moderation_enabled + + False + + + + help_moderator_email + False + label_moderator_email + + + + + + False + help_moderator_notification_enabled + False + label_moderator_notification_enabled + + False + + + + True + help_show_commenter_image + False + label_show_commenter_image + + True + + + + text/plain + help_text_transform + label_text_transform + plone.app.discussion.vocabularies.TextTransformVocabulary + + text/plain + + + + False + help_user_notification_enabled + False + label_user_notification_enabled + + False + + +``` diff --git a/docs/howtos/howto_write_a_custom_email_notification.md b/docs/howtos/howto_write_a_custom_email_notification.md new file mode 100644 index 00000000..897b4754 --- /dev/null +++ b/docs/howtos/howto_write_a_custom_email_notification.md @@ -0,0 +1,15 @@ +--- +myst: + html_meta: + "description": "Howto write a custom email notification - plone.app.discussion documentation" + "property=og:description": "Howto write a custom email notification - plone.app.discussion documentation" + "property=og:title": "Howto write a custom email notification" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +# Howto write a custom email notification + +This document explains how to write a custom email notification for +plone.app.discussion. + +XXX: TODO diff --git a/docs/howtos/index.md b/docs/howtos/index.md new file mode 100644 index 00000000..d6ffafe1 --- /dev/null +++ b/docs/howtos/index.md @@ -0,0 +1,21 @@ +--- +myst: + html_meta: + "description": "Howtos - plone.app.discussion documentation" + "property=og:description": "Howtos - plone.app.discussion documentation" + "property=og:title": "Howtos" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +# Howtos + +```{toctree} +:maxdepth: 1 + +howto_extend_the_comment_form.txt +howto_make_pad_work_with_a_dexterity_content_type.txt +howto_override_comments_viewlet.txt +howto_override_enable_conversation.txt +howto_set_discussion_settings_with_generic_setup.txt +howto_write_a_custom_email_notification.txt +``` diff --git a/docs/source/api/comment.md b/docs/source/api/comment.md new file mode 100644 index 00000000..4094a0d9 --- /dev/null +++ b/docs/source/api/comment.md @@ -0,0 +1,12 @@ +--- +myst: + html_meta: + "description": "Comment - plone.app.discussion documentation" + "property=og:description": "Comment - plone.app.discussion documentation" + "property=og:title": "Comment" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +```{eval-rst} +.. include:: ../../../plone/app/discussion/comment.txt +``` diff --git a/docs/source/api/comment.txt b/docs/source/api/comment.txt deleted file mode 100644 index 4d5cf79b..00000000 --- a/docs/source/api/comment.txt +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../../plone/app/discussion/comment.txt \ No newline at end of file diff --git a/docs/source/api/conversation.md b/docs/source/api/conversation.md new file mode 100644 index 00000000..94c7e837 --- /dev/null +++ b/docs/source/api/conversation.md @@ -0,0 +1,12 @@ +--- +myst: + html_meta: + "description": "Conversation - plone.app.discussion documentation" + "property=og:description": "Conversation - plone.app.discussion documentation" + "property=og:title": "Conversation" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +```{eval-rst} +.. include:: ../../../plone/app/discussion/conversation.txt +``` diff --git a/docs/source/api/conversation.txt b/docs/source/api/conversation.txt deleted file mode 100644 index a1c3ea4d..00000000 --- a/docs/source/api/conversation.txt +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../../plone/app/discussion/conversation.txt \ No newline at end of file diff --git a/docs/source/api/index.md b/docs/source/api/index.md new file mode 100644 index 00000000..d28564d3 --- /dev/null +++ b/docs/source/api/index.md @@ -0,0 +1,28 @@ +--- +myst: + html_meta: + "description": "API - plone.app.discussion documentation" + "property=og:description": "API - plone.app.discussion documentation" + "property=og:title": "API" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +# API + +The conversation and replies adapters. + +The conversation is responsible for storing all comments. It provides a +dict-like API for accessing comments, where keys are integers and values +are IComment objects. It also provides features for finding comments quickly. + +The IReplies adapter provides an API for finding and manipulating the comments +directly in reply to a particular comment (implemented by the CommentReplies +adapter) or at the top level of the conversation (implemented by the +ConversationReplies adapter). + +```{toctree} +:maxdepth: 1 + +conversation.txt +comment.txt +``` diff --git a/docs/source/architecture.md b/docs/source/architecture.md new file mode 100644 index 00000000..be1ae88c --- /dev/null +++ b/docs/source/architecture.md @@ -0,0 +1,12 @@ +--- +myst: + html_meta: + "description": "Architecture - plone.app.discussion documentation" + "property=og:description": "Architecture - plone.app.discussion documentation" + "property=og:title": "Architecture" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +```{eval-rst} +.. include:: ../../plone/app/discussion/architecture.txt +``` diff --git a/docs/source/architecture.txt b/docs/source/architecture.txt deleted file mode 100644 index e34bb044..00000000 --- a/docs/source/architecture.txt +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../plone/app/discussion/architecture.txt \ No newline at end of file diff --git a/docs/source/captcha.md b/docs/source/captcha.md new file mode 100644 index 00000000..e4ebf9dd --- /dev/null +++ b/docs/source/captcha.md @@ -0,0 +1,12 @@ +--- +myst: + html_meta: + "description": "Captcha - plone.app.discussion documentation" + "property=og:description": "Captcha - plone.app.discussion documentation" + "property=og:title": "Captcha" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +```{eval-rst} +.. include:: ../../plone/app/discussion/browser/captcha.txt +``` diff --git a/docs/source/captcha.txt b/docs/source/captcha.txt deleted file mode 100644 index 11b47196..00000000 --- a/docs/source/captcha.txt +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../plone/app/discussion/browser/captcha.txt \ No newline at end of file diff --git a/docs/source/design.md b/docs/source/design.md new file mode 100644 index 00000000..910b525d --- /dev/null +++ b/docs/source/design.md @@ -0,0 +1,12 @@ +--- +myst: + html_meta: + "description": "Design - plone.app.discussion documentation" + "property=og:description": "Design - plone.app.discussion documentation" + "property=og:title": "Design" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +```{eval-rst} +.. include:: ../../plone/app/discussion/design.txt +``` diff --git a/docs/source/design.txt b/docs/source/design.txt deleted file mode 100644 index bfb5a8e7..00000000 --- a/docs/source/design.txt +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../plone/app/discussion/design.txt \ No newline at end of file diff --git a/docs/source/email-notification.md b/docs/source/email-notification.md new file mode 100644 index 00000000..ecad8c75 --- /dev/null +++ b/docs/source/email-notification.md @@ -0,0 +1,80 @@ +--- +myst: + html_meta: + "description": "Email Notification - plone.app.discussion documentation" + "property=og:description": "Email Notification - plone.app.discussion documentation" + "property=og:title": "Email Notification" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +# Email Notification + +This document describes the plone.app.discussion email notification feature. + +## Introduction + +plone.app.discussion allows users and administrators to be notified about new +comments by email. There are two kinds of email notification: + +1. **User notification**: Tell users when a comment has been added. + + This method composes and sends emails to all users that have added a comment + to this conversation and enabled user notification. + + This requires the user_notification setting to be enabled in the discussion + control panel. + +2. **Moderator notification**: Tell the moderator when a comment needs attention. + + This method sends an email to the site admin (mail control panel setting) if + comment moderation is enabled and a new comment has been added that needs to + be approved. + + This requires the moderator_notification to be enabled in the discussion + control panel and the comment_review_workflow enabled for the comment content + type. + +:::{note} +The user notification feature requires z3c.form >= 2.3.3. +::: + +## User Notification + +*plone/app/discussion/comment.py* + +```{literalinclude} ../../plone/app/discussion/comment.py +:encoding: utf-8 +:language: python +:pyobject: notify_user +``` + +## Moderator Notification + +*plone/app/discussion/comment.py* + +```{literalinclude} ../../plone/app/discussion/comment.py +:encoding: utf-8 +:language: python +:pyobject: notify_moderator +``` + +## Event Subscribers + +Email notifications are triggered by event subscribers that are called when a +comment has been added to a page. + +:::{note} +In Plone 3, the event subscribers were located in the zope.lifecycleevent +package. They moved to zope.app.container in Plone 4. Therefore +plone.app.discussion registers one of the two subscribers, dependent on the +Plone version. +::: + +To create custom email notifications, register a new event subscriber or +override an existing one. + +*plone/app/discussion/notifications.zcml* + +```{literalinclude} ../../plone/app/discussion/notifications.zcml +:encoding: utf-8 +``` diff --git a/docs/source/email-notification.txt b/docs/source/email-notification.txt deleted file mode 100644 index 883ceefb..00000000 --- a/docs/source/email-notification.txt +++ /dev/null @@ -1,78 +0,0 @@ -================== -Email Notification -================== - -This document describes the plone.app.discussion email notification feature. - - -Introduction -============ - -plone.app.discussion allows users and administrators to be notified about new -comments by email. There are two kinds of email notification: - -1) **User notification**: Tell users when a comment has been added. - - This method composes and sends emails to all users that have added a comment - to this conversation and enabled user notification. - - This requires the user_notification setting to be enabled in the discussion - control panel. - - -2) **Moderator notification**: Tell the moderator when a comment needs attention. - - This method sends an email to the site admin (mail control panel setting) if - comment moderation is enabled and a new comment has been added that needs to - be approved. - - This requires the moderator_notification to be enabled in the discussion - control panel and the comment_review_workflow enabled for the comment content - type. - - -.. note:: The user notification feature requires z3c.form >= 2.3.3. - - -User Notification -================= - -*plone/app/discussion/comment.py* - -.. literalinclude:: ../../plone/app/discussion/comment.py - :language: python - :encoding: utf-8 - :pyobject: notify_user - - -Moderator Notification -====================== - -*plone/app/discussion/comment.py* - -.. literalinclude:: ../../plone/app/discussion/comment.py - :language: python - :encoding: utf-8 - :pyobject: notify_moderator - - - -Event Subscribers -================= - -Email notifications are triggered by event subscribers that are called when a -comment has been added to a page. - -.. note:: - In Plone 3, the event subscribers were located in the zope.lifecycleevent - package. They moved to zope.app.container in Plone 4. Therefore - plone.app.discussion registers one of the two subscribers, dependent on the - Plone version. - -To create custom email notifications, register a new event subscriber or -override an existing one. - -*plone/app/discussion/notifications.zcml* - -.. literalinclude:: ../../plone/app/discussion/notifications.zcml - :encoding: utf-8 diff --git a/docs/source/howtos/howto_extend_the_comment_form.md b/docs/source/howtos/howto_extend_the_comment_form.md new file mode 100644 index 00000000..c500ee3a --- /dev/null +++ b/docs/source/howtos/howto_extend_the_comment_form.md @@ -0,0 +1,173 @@ +--- +myst: + html_meta: + "description": "Howto extend the comment form with additional fields - plone.app.discussion documentation" + "property=og:description": "Howto extend the comment form with additional fields - plone.app.discussion documentation" + "property=og:title": "Howto extend the comment form with additional fields" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +# Howto extend the comment form with additional fields + +This document explains how to extend the plone.app.discussion comment form with +additional fields in an add-on product. + +plone.app.discussion uses the +[plone.z3cform.fieldsets](http://pypi.python.org/pypi/plone.z3cform#fieldsets-and-form-extenders) +package which provides support for modifications via "extender" adapters. The +idea is that a third party component can modify the fields in a form and the +way that they are grouped and ordered. + +:::{note} +This howto applies only to plone.app.discussion >= 2.0.4 and >= 1.1.2. Prior +versions will not store the extended fields on the comment. +::: + +:::{seealso} +The source code of this howto can be found here: + +::: + +## Howto extend the comment form with an additional "website" field + +First, create a new plone package: + +``` +$ paster create -t plone example.commentextender +``` + +Go to the main directory of the package +(example.commentextender/example/commentextender) and create a new file +*commentextender.py*. + +This file contains the ICommentExtenderFields interface definition with a +"website" field, a persistent CommentExtenderFields class to store the value of +the "website" field, a CommentExtenderFactory to create the +CommentExtenderFields, and a CommentExtender class to extend the default +comment form with the "website" field: + +``` +from persistent import Persistent + +from z3c.form.field import Fields + +from zope import interface +from zope import schema + +from zope.annotation import factory +from zope.component import adapter +from zope.interface import Interface +from zope.publisher.interfaces.browser import IDefaultBrowserLayer + +from plone.z3cform.fieldsets import extensible + +from plone.app.discussion.browser.comments import CommentForm +from plone.app.discussion.comment import Comment + +# Interface to define the fields we want to add to the comment form. +class ICommentExtenderFields(Interface): + website = schema.TextLine(title="Website", required=False) + +# Persistent class that implements the ICommentExtenderFields interface +@adapter(Comment) +class CommentExtenderFields(Persistent): + interface.implements(ICommentExtenderFields) + website = "" + +# CommentExtenderFields factory +CommentExtenderFactory = factory(CommentExtenderFields) + +# Extending the comment form with the fields defined in the +# ICommentExtenderFields interface. +@adapter(Interface, IDefaultBrowserLayer, CommentForm) +class CommentExtender(extensible.FormExtender): + fields = Fields(ICommentExtenderFields) + + def __init__(self, context, request, form): + self.context = context + self.request = request + self.form = form + + def update(self): + # Add the fields defined in ICommentExtenderFields to the form. + self.add(ICommentExtenderFields, prefix="") + # Move the website field to the top of the comment form. + self.move('website', before='text', prefix="") +``` + +:::{seealso} +- See the plone.z3cform pypi page for more documentation about how to add, + hide, and reorder fields: + +::: + +Now register the CommentExtenderFactory and CommentExtender Classes that has +been created by adding the following lines to your configure.zcml: + +``` + + + +``` + +Create a new Plone instance, globally allow commenting, allow commenting on a +content object and you will see a comment form with an additional "website" +field. + +Since we do not only want to store the "website" value on the comments, but also +to show these values for existing comments, we have to override the comments +viewlet. The easiest way to do this is to use z3c.jbot. + +First, add [z3c.jbot](http://pypi.python.org/pypi/z3c.jbot). to the setup.py +of the example.commentextender package: + +``` +install_requires=[ + ... + 'z3c.jbot', +], +``` + +Next, create a new directory called "overrides" inside the +example.commentextender package and register it together with z3c.jbot in your +configure.zcml: + +``` + + + ... + + + + + + +``` + +Copy plone.app.discussion/plone/app/discussion/browser/comments.pt to the +overrides directory we just created and rename comments.pt to +plone.app.discussion.browser.comments.pt. + +You can now add code to show the website attribute to the documentByLine: + +``` +
+ ... +
+ +
+
+``` + +Restart your Plone instance and you will see the "website" field in the +documentByLine next to the comments. diff --git a/docs/source/howtos/howto_extend_the_comment_form.txt b/docs/source/howtos/howto_extend_the_comment_form.txt deleted file mode 100644 index 3afaf6a6..00000000 --- a/docs/source/howtos/howto_extend_the_comment_form.txt +++ /dev/null @@ -1,156 +0,0 @@ -==================================================== -Howto extend the comment form with additional fields -==================================================== - -This document explains how to extend the plone.app.discussion comment form with -additional fields in an add-on product. - -plone.app.discussion uses the -`plone.z3cform.fieldsets `_ -package which provides support for modifications via "extender" adapters. The -idea is that a third party component can modify the fields in a form and the -way that they are grouped and ordered. - -.. note:: - - This howto applies only to plone.app.discussion >= 2.0.4 and >= 1.1.2. Prior - versions will not store the extended fields on the comment. - -.. seealso:: - - The source code of this howto can be found here: - https://github.com/collective/example.commentextender/ - - -Howto extend the comment form with an additional "website" field -================================================================ - -First, create a new plone package:: - - $ paster create -t plone example.commentextender - -Go to the main directory of the package -(example.commentextender/example/commentextender) and create a new file -*commentextender.py*. - -This file contains the ICommentExtenderFields interface definition with a -"website" field, a persistent CommentExtenderFields class to store the value of -the "website" field, a CommentExtenderFactory to create the -CommentExtenderFields, and a CommentExtender class to extend the default -comment form with the "website" field:: - - from persistent import Persistent - - from z3c.form.field import Fields - - from zope import interface - from zope import schema - - from zope.annotation import factory - from zope.component import adapter - from zope.interface import Interface - from zope.publisher.interfaces.browser import IDefaultBrowserLayer - - from plone.z3cform.fieldsets import extensible - - from plone.app.discussion.browser.comments import CommentForm - from plone.app.discussion.comment import Comment - - # Interface to define the fields we want to add to the comment form. - class ICommentExtenderFields(Interface): - website = schema.TextLine(title="Website", required=False) - - # Persistent class that implements the ICommentExtenderFields interface - @adapter(Comment) - class CommentExtenderFields(Persistent): - interface.implements(ICommentExtenderFields) - website = "" - - # CommentExtenderFields factory - CommentExtenderFactory = factory(CommentExtenderFields) - - # Extending the comment form with the fields defined in the - # ICommentExtenderFields interface. - @adapter(Interface, IDefaultBrowserLayer, CommentForm) - class CommentExtender(extensible.FormExtender): - fields = Fields(ICommentExtenderFields) - - def __init__(self, context, request, form): - self.context = context - self.request = request - self.form = form - - def update(self): - # Add the fields defined in ICommentExtenderFields to the form. - self.add(ICommentExtenderFields, prefix="") - # Move the website field to the top of the comment form. - self.move('website', before='text', prefix="") - -.. seealso:: - - * See the plone.z3cform pypi page for more documentation about how to add, - hide, and reorder fields: - http://pypi.python.org/pypi/plone.z3cform#fieldsets-and-form-extenders - -Now register the CommentExtenderFactory and CommentExtender Classes that has -been created by adding the following lines to your configure.zcml:: - - - - - -Create a new Plone instance, globally allow commenting, allow commenting on a -content object and you will see a comment form with an additional "website" -field. - -Since we do not only want to store the "website" value on the comments, but also -to show these values for existing comments, we have to override the comments -viewlet. The easiest way to do this is to use z3c.jbot. - -First, add `z3c.jbot `_. to the setup.py -of the example.commentextender package:: - - install_requires=[ - ... - 'z3c.jbot', - ], - -Next, create a new directory called "overrides" inside the -example.commentextender package and register it together with z3c.jbot in your -configure.zcml:: - - - - ... - - - - - - - -Copy plone.app.discussion/plone/app/discussion/browser/comments.pt to the -overrides directory we just created and rename comments.pt to -plone.app.discussion.browser.comments.pt. - -You can now add code to show the website attribute to the documentByLine:: - -
- ... -
- -
-
- -Restart your Plone instance and you will see the "website" field in the -documentByLine next to the comments. diff --git a/docs/source/howtos/howto_make_pad_work_with_a_dexterity_content_type.md b/docs/source/howtos/howto_make_pad_work_with_a_dexterity_content_type.md new file mode 100644 index 00000000..63672460 --- /dev/null +++ b/docs/source/howtos/howto_make_pad_work_with_a_dexterity_content_type.md @@ -0,0 +1,56 @@ +--- +myst: + html_meta: + "description": "How to make plone.app.discussion work with a dexterity content type - plone.app.discussion documentation" + "property=og:description": "How to make plone.app.discussion work with a dexterity content type - plone.app.discussion documentation" + "property=og:title": "How to make plone.app.discussion work with a dexterity content type" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +# How to make plone.app.discussion work with a dexterity content type + +This document explains how to make plone.app.discussion work with a custom +dexterity content type. + +XXX: TODO + +configure.zcml: + +``` + +``` + +Define an interface IMyDexterityContentType groked schema, I added: + +``` +allowDiscussion = schema.Bool( + title=_("Allow Users to Comment"), + description=_("Allow users to comment on you. Comments +``` + +are shown at the end of each page"), + +: > required=True, + > default=True, + + ) + +and added this class: + +from plone.app.discussion.browser.comments import CommentsViewlet +class ConversationView(object): + +> """ Ability to either allow / disallow comments based on schema + +option + +: """ + def enabled(self): + + > return getattr(self.context, 'allowDiscussion', False) diff --git a/docs/source/howtos/howto_make_pad_work_with_a_dexterity_content_type.txt b/docs/source/howtos/howto_make_pad_work_with_a_dexterity_content_type.txt deleted file mode 100644 index 84610b37..00000000 --- a/docs/source/howtos/howto_make_pad_work_with_a_dexterity_content_type.txt +++ /dev/null @@ -1,39 +0,0 @@ -=============================================================================== -How to make plone.app.discussion work with a dexterity content type -=============================================================================== - -This document explains how to make plone.app.discussion work with a custom -dexterity content type. - -XXX: TODO - -configure.zcml:: - - - -Define an interface IMyDexterityContentType groked schema, I added:: - - allowDiscussion = schema.Bool( - title=_("Allow Users to Comment"), - description=_("Allow users to comment on you. Comments -are shown at the end of each page"), - required=True, - default=True, - ) - -and added this class:: - -from plone.app.discussion.browser.comments import CommentsViewlet -class ConversationView(object): - """ Ability to either allow / disallow comments based on schema -option - """ - def enabled(self): - return getattr(self.context, 'allowDiscussion', False) - diff --git a/docs/source/howtos/howto_override_comments_viewlet.md b/docs/source/howtos/howto_override_comments_viewlet.md new file mode 100644 index 00000000..dc8edb20 --- /dev/null +++ b/docs/source/howtos/howto_override_comments_viewlet.md @@ -0,0 +1,154 @@ +--- +myst: + html_meta: + "description": "How to override plone.app.discussion's comments viewlet - plone.app.discussion documentation" + "property=og:description": "How to override plone.app.discussion's comments viewlet - plone.app.discussion documentation" + "property=og:title": "How to override plone.app.discussion's comments viewlet" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +# How to override plone.app.discussion's comments viewlet + +This document explains how to override the plone.app.discussion comments +viewlet that controls the way existing comments are displayed. + +There are three different ways to override plone.app.discussion's comments +viewlet: through-the-web, on the file system with z3c.jbot, and by overriding +the comments viewlet class on the file system. + +Overriding the comments viewlet template throught-the-web is the quick and +dirty approach. Using z3c.jbot is the recommended approach if you just want to +override the comments viewlet template. If you want full control over the +comments viewlet class, for instance if you want to add/customize view methods, +overriding the comments viewlet class on the file system is the recommended +approach. + +## Override the comments template through-the web + +Overriding the comments template through-the web is the easiest way to +customize the comments viewlet: + +``` +* Go to the ZMI (http://localhost:8080/Plone/manage_main) +* Click on "portal_view_customizations" +* Customize plone.comments (plone.app.discussion.interfaces.IDiscussionLayer) +``` + +## Override the comments template with z3c.jbot on the file system + +The easiest way to override the comments template on the file +system is with [z3c.jbot]. [z3c.jbot] allows you to override any +Plone template just by putting a file in a specific directory. + +`z3c.jbot`:: + +Add z3c.jbot to the dependencies of your package by adding a +line to your setup.py file: + +``` +install_requires=[ + ... + 'z3c.jbot', +], +``` + +Register an overrides directory where you can put your file +overrides in your configure.zcml file: + +``` + + + +``` + +Replace \ with a custom browserlayer of your package. + +Create the template directory we just registered: + +``` +$ mkdir overrides +``` + +Copy the comments viewlet template we want to override to the +overrides directory we just created and registered: + +``` +$ cp ../parts/omelette/plone/app/discussion/browser/comments.pt overrides/plone.app.discussion.browser.comments.pt +``` + +Restart your Plone instance and you can start to customize +the plone.app.discussion.browser.comments.pt we just created. + +## Override the comments viewlet class on the file system + +Overriding/subclassing the comments viewlet class is allows you not only to +override the comments viewlet template, but also the comment viewlets view +methods. There are many ways to override components in Plone with the Zope +Component Architecture (ZCA), which is beyond the scope of this howto. + +We are going to register our own browserlayer + +First we define our browser layer in interfaces.py: + +``` +from plone.app.discussion.interfaces import IDiscussionLayer + +class IMyDiscussionLayer(IDiscussionLayer): + """Marker interface for a custom plone.app.discussion browser layer + """ +``` + +Next, we register the browserlayer in our generic setup (GS) setup in the +profiles/default/browserlayer.xml file: + +``` + + + + +``` + +configure.zcml: + +``` + + +``` + +note: Note that we override the comments viewlet by using the my.discussion.interfaces.IMyDiscussionLayer browser layer and not the default plone.app.discussion.interfaces.IDiscussionLayer browser layer. + +Once we registered the custom discussion browser layer and the viewlet, we can create a +comments.py file with our custom version of the comments viewlet: + +``` +from Products.Five.browser.pagetemplatefile import ViewPageTemplateFile + +from plone.app.discussion.browser.comments import CommentsViewlet as PloneAppDiscussionCommentsViewlet +from plone.app.discussion.browser.comments import CommentForm + + +class CommentsViewlet(PloneAppDiscussionCommentsViewlet): + + form = CommentForm + index = ViewPageTemplateFile('comments.pt') + + def get_commenter_home_url(self, username=None): + if username is None: + return None + else: + return "%s/memberhome/%s" % (self.context.portal_url(), username) +``` + +To override the comments viewlet template, we create a comment.pt file in the +same directory and copy the contents from the original. diff --git a/docs/source/howtos/howto_override_comments_viewlet.txt b/docs/source/howtos/howto_override_comments_viewlet.txt deleted file mode 100644 index b45aba4f..00000000 --- a/docs/source/howtos/howto_override_comments_viewlet.txt +++ /dev/null @@ -1,138 +0,0 @@ -=============================================================================== -How to override plone.app.discussion's comments viewlet -=============================================================================== - -This document explains how to override the plone.app.discussion comments -viewlet that controls the way existing comments are displayed. - -There are three different ways to override plone.app.discussion's comments -viewlet: through-the-web, on the file system with z3c.jbot, and by overriding -the comments viewlet class on the file system. - -Overriding the comments viewlet template throught-the-web is the quick and -dirty approach. Using z3c.jbot is the recommended approach if you just want to -override the comments viewlet template. If you want full control over the -comments viewlet class, for instance if you want to add/customize view methods, -overriding the comments viewlet class on the file system is the recommended -approach. - - -Override the comments template through-the web ----------------------------------------------- - -Overriding the comments template through-the web is the easiest way to -customize the comments viewlet:: - - * Go to the ZMI (http://localhost:8080/Plone/manage_main) - * Click on "portal_view_customizations" - * Customize plone.comments (plone.app.discussion.interfaces.IDiscussionLayer) - - -Override the comments template with z3c.jbot on the file system ---------------------------------------------------------------- - -The easiest way to override the comments template on the file -system is with `z3c.jbot`_. `z3c.jbot`_ allows you to override any -Plone template just by putting a file in a specific directory. - -`z3c.jbot`:: http://pypi.python.org/pypi/z3c.jbot - -Add z3c.jbot to the dependencies of your package by adding a -line to your setup.py file:: - - install_requires=[ - ... - 'z3c.jbot', - ], - -Register an overrides directory where you can put your file -overrides in your configure.zcml file:: - - - - - -Replace with a custom browserlayer of your package. - -Create the template directory we just registered:: - - $ mkdir overrides - -Copy the comments viewlet template we want to override to the -overrides directory we just created and registered:: - - $ cp ../parts/omelette/plone/app/discussion/browser/comments.pt overrides/plone.app.discussion.browser.comments.pt - -Restart your Plone instance and you can start to customize -the plone.app.discussion.browser.comments.pt we just created. - - -Override the comments viewlet class on the file system ------------------------------------------------------- - -Overriding/subclassing the comments viewlet class is allows you not only to -override the comments viewlet template, but also the comment viewlets view -methods. There are many ways to override components in Plone with the Zope -Component Architecture (ZCA), which is beyond the scope of this howto. - -We are going to register our own browserlayer - -First we define our browser layer in interfaces.py:: - - from plone.app.discussion.interfaces import IDiscussionLayer - - class IMyDiscussionLayer(IDiscussionLayer): - """Marker interface for a custom plone.app.discussion browser layer - """ - -Next, we register the browserlayer in our generic setup (GS) setup in the -profiles/default/browserlayer.xml file:: - - - - - - - - - -configure.zcml:: - - - - -note: Note that we override the comments viewlet by using the my.discussion.interfaces.IMyDiscussionLayer browser layer and not the default plone.app.discussion.interfaces.IDiscussionLayer browser layer. - -Once we registered the custom discussion browser layer and the viewlet, we can create a -comments.py file with our custom version of the comments viewlet:: - - from Products.Five.browser.pagetemplatefile import ViewPageTemplateFile - - from plone.app.discussion.browser.comments import CommentsViewlet as PloneAppDiscussionCommentsViewlet - from plone.app.discussion.browser.comments import CommentForm - - - class CommentsViewlet(PloneAppDiscussionCommentsViewlet): - - form = CommentForm - index = ViewPageTemplateFile('comments.pt') - - def get_commenter_home_url(self, username=None): - if username is None: - return None - else: - return "%s/memberhome/%s" % (self.context.portal_url(), username) - -To override the comments viewlet template, we create a comment.pt file in the -same directory and copy the contents from the original. diff --git a/docs/source/howtos/howto_override_enable_conversation.md b/docs/source/howtos/howto_override_enable_conversation.md new file mode 100644 index 00000000..1d2e3613 --- /dev/null +++ b/docs/source/howtos/howto_override_enable_conversation.md @@ -0,0 +1,80 @@ +--- +myst: + html_meta: + "description": "Howto override the enable_conversation method. - plone.app.discussion documentation" + "property=og:description": "Howto override the enable_conversation method. - plone.app.discussion documentation" + "property=og:title": "Howto override the enable_conversation method." + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +# Howto override the enable_conversation method. + +plone.app.discussion way to decide if commenting is enabled on a content +object can be quite complex and cumbersome due to the need to be backward +compatible with the way the old commenting system in Plone (\<4.1) worked. + +The comments viewlet calls the enabled method of the ConversationView to +decide if the add comment form should show up: + +```{literalinclude} ../../../plone/app/discussion/browser/conversation.py +:language: python +:pyobject: ConversationView +``` + +If you want to override this behavior, you just have to create your own enabled method. To do so, we first have to register our custom +ConversationView by overriding the existing one in our configure.zcml: + +``` + + + + + + +``` + +Now we implement the conversation view with a single "enable" method in +conversation.py: + +``` +from zope.component import queryUtility + +from plone.registry.interfaces import IRegistry + +from Acquisition import aq_inner + +from Products.CMFCore.utils import getToolByName + +from plone.app.discussion.interfaces import IDiscussionSettings + + +class ConversationView(object): + + def enabled(self): + context = aq_inner(self.context) + + # Fetch discussion registry + registry = queryUtility(IRegistry) + settings = registry.forInterface(IDiscussionSettings, check=False) + + # Check if discussion is allowed globally + if not settings.globally_enabled: + return False + + # Check if discussion is allowed on the content object + if context.allow_discussion is not None: + return context.allow_discussion + + # Check if discussion is allowed on the content type + portal_types = getToolByName(self, 'portal_types') + document_fti = getattr(portal_types, context.portal_type) + return document_fti.getProperty('allow_discussion') +``` diff --git a/docs/source/howtos/howto_override_enable_conversation.txt b/docs/source/howtos/howto_override_enable_conversation.txt deleted file mode 100644 index 740b21cf..00000000 --- a/docs/source/howtos/howto_override_enable_conversation.txt +++ /dev/null @@ -1,68 +0,0 @@ -============================================================================== -Howto override the enable_conversation method. -============================================================================== - -plone.app.discussion way to decide if commenting is enabled on a content -object can be quite complex and cumbersome due to the need to be backward -compatible with the way the old commenting system in Plone (<4.1) worked. - -The comments viewlet calls the enabled method of the ConversationView to -decide if the add comment form should show up: - -.. literalinclude:: ../../../plone/app/discussion/browser/conversation.py - :language: python - :pyobject: ConversationView - -If you want to override this behavior, you just have to create your own enabled method. To do so, we first have to register our custom -ConversationView by overriding the existing one in our configure.zcml:: - - - - - - - - -Now we implement the conversation view with a single "enable" method in -conversation.py:: - - from zope.component import queryUtility - - from plone.registry.interfaces import IRegistry - - from Acquisition import aq_inner - - from Products.CMFCore.utils import getToolByName - - from plone.app.discussion.interfaces import IDiscussionSettings - - - class ConversationView(object): - - def enabled(self): - context = aq_inner(self.context) - - # Fetch discussion registry - registry = queryUtility(IRegistry) - settings = registry.forInterface(IDiscussionSettings, check=False) - - # Check if discussion is allowed globally - if not settings.globally_enabled: - return False - - # Check if discussion is allowed on the content object - if context.allow_discussion is not None: - return context.allow_discussion - - # Check if discussion is allowed on the content type - portal_types = getToolByName(self, 'portal_types') - document_fti = getattr(portal_types, context.portal_type) - return document_fti.getProperty('allow_discussion') diff --git a/docs/source/howtos/howto_set_discussion_settings_with_generic_setup.md b/docs/source/howtos/howto_set_discussion_settings_with_generic_setup.md new file mode 100644 index 00000000..407b095e --- /dev/null +++ b/docs/source/howtos/howto_set_discussion_settings_with_generic_setup.md @@ -0,0 +1,127 @@ +--- +myst: + html_meta: + "description": "How to set discussion settings with generic setup - plone.app.discussion documentation" + "property=og:description": "How to set discussion settings with generic setup - plone.app.discussion documentation" + "property=og:title": "How to set discussion settings with generic setup" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +# How to set discussion settings with generic setup + +This document explains how to set plone.app.discussion's settings with a +generic setup profile. + +plone.app.discussion uses plone.app.registry to store its global settings. +You can set or override the settings in the registry.xml file of your generic +setup profile: + +``` + + + + False + help_anonymous_comments + False + label_anonymous_comments + + False + + + + disabled + help_captcha + label_captcha + plone.app.discussion.vocabularies.CaptchaVocabulary + + disabled + + + + False + help_globally_enabled + False + label_globally_enabled + + False + + + + False + help_moderation_enabled + False + label_moderation_enabled + + False + + + + help_moderator_email + False + label_moderator_email + + + + + + False + help_moderator_notification_enabled + False + label_moderator_notification_enabled + + False + + + + True + help_show_commenter_image + False + label_show_commenter_image + + True + + + + text/plain + help_text_transform + label_text_transform + plone.app.discussion.vocabularies.TextTransformVocabulary + + text/plain + + + + False + help_user_notification_enabled + False + label_user_notification_enabled + + False + + +``` diff --git a/docs/source/howtos/howto_set_discussion_settings_with_generic_setup.txt b/docs/source/howtos/howto_set_discussion_settings_with_generic_setup.txt deleted file mode 100644 index d94d93b1..00000000 --- a/docs/source/howtos/howto_set_discussion_settings_with_generic_setup.txt +++ /dev/null @@ -1,118 +0,0 @@ -================================================= -How to set discussion settings with generic setup -================================================= - -This document explains how to set plone.app.discussion's settings with a -generic setup profile. - -plone.app.discussion uses plone.app.registry to store its global settings. -You can set or override the settings in the registry.xml file of your generic -setup profile:: - - - - - False - help_anonymous_comments - False - label_anonymous_comments - - False - - - - disabled - help_captcha - label_captcha - plone.app.discussion.vocabularies.CaptchaVocabulary - - disabled - - - - False - help_globally_enabled - False - label_globally_enabled - - False - - - - False - help_moderation_enabled - False - label_moderation_enabled - - False - - - - help_moderator_email - False - label_moderator_email - - - - - - False - help_moderator_notification_enabled - False - label_moderator_notification_enabled - - False - - - - True - help_show_commenter_image - False - label_show_commenter_image - - True - - - - text/plain - help_text_transform - label_text_transform - plone.app.discussion.vocabularies.TextTransformVocabulary - - text/plain - - - - False - help_user_notification_enabled - False - label_user_notification_enabled - - False - - diff --git a/docs/source/howtos/howto_write_a_custom_email_notification.md b/docs/source/howtos/howto_write_a_custom_email_notification.md new file mode 100644 index 00000000..897b4754 --- /dev/null +++ b/docs/source/howtos/howto_write_a_custom_email_notification.md @@ -0,0 +1,15 @@ +--- +myst: + html_meta: + "description": "Howto write a custom email notification - plone.app.discussion documentation" + "property=og:description": "Howto write a custom email notification - plone.app.discussion documentation" + "property=og:title": "Howto write a custom email notification" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +# Howto write a custom email notification + +This document explains how to write a custom email notification for +plone.app.discussion. + +XXX: TODO diff --git a/docs/source/howtos/howto_write_a_custom_email_notification.txt b/docs/source/howtos/howto_write_a_custom_email_notification.txt deleted file mode 100644 index a32ae990..00000000 --- a/docs/source/howtos/howto_write_a_custom_email_notification.txt +++ /dev/null @@ -1,8 +0,0 @@ -=============================================================================== -Howto write a custom email notification -=============================================================================== - -This document explains how to write a custom email notification for -plone.app.discussion. - -XXX: TODO \ No newline at end of file diff --git a/docs/source/howtos/index.md b/docs/source/howtos/index.md new file mode 100644 index 00000000..d6ffafe1 --- /dev/null +++ b/docs/source/howtos/index.md @@ -0,0 +1,21 @@ +--- +myst: + html_meta: + "description": "Howtos - plone.app.discussion documentation" + "property=og:description": "Howtos - plone.app.discussion documentation" + "property=og:title": "Howtos" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +# Howtos + +```{toctree} +:maxdepth: 1 + +howto_extend_the_comment_form.txt +howto_make_pad_work_with_a_dexterity_content_type.txt +howto_override_comments_viewlet.txt +howto_override_enable_conversation.txt +howto_set_discussion_settings_with_generic_setup.txt +howto_write_a_custom_email_notification.txt +``` diff --git a/docs/source/howtos/index.txt b/docs/source/howtos/index.txt deleted file mode 100644 index 2eeaa68d..00000000 --- a/docs/source/howtos/index.txt +++ /dev/null @@ -1,13 +0,0 @@ -====== -Howtos -====== - -.. toctree:: - :maxdepth: 1 - - howto_extend_the_comment_form.txt - howto_make_pad_work_with_a_dexterity_content_type.txt - howto_override_comments_viewlet.txt - howto_override_enable_conversation.txt - howto_set_discussion_settings_with_generic_setup.txt - howto_write_a_custom_email_notification.txt diff --git a/docs/source/index.md b/docs/source/index.md new file mode 100644 index 00000000..504f1d31 --- /dev/null +++ b/docs/source/index.md @@ -0,0 +1,37 @@ +--- +myst: + html_meta: + "description": "Welcome to plone.app.discussion's documentation! - plone.app.discussion documentation" + "property=og:description": "Welcome to plone.app.discussion's documentation! - plone.app.discussion documentation" + "property=og:title": "Welcome to plone.app.discussion's documentation!" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +% plone.app.discussion documentation master file, created by +% sphinx-quickstart on Thu Mar 18 10:17:15 2010. +% You can adapt this file completely to your liking, but it should at least +% contain the root `toctree` directive. + +# Welcome to plone.app.discussion's documentation! + +% module:`plone.app.discussion` + +Contents: + +```{toctree} +:maxdepth: 2 + +architecture.txt +design.txt +workflow.txt +captcha.txt +email-notification.txt +api/index.txt +howtos/index.txt +``` + +# Indices and tables + +- {ref}`genindex` +- {ref}`modindex` +- {ref}`search` diff --git a/docs/source/index.txt b/docs/source/index.txt deleted file mode 100644 index c8def7f7..00000000 --- a/docs/source/index.txt +++ /dev/null @@ -1,33 +0,0 @@ -.. plone.app.discussion documentation master file, created by - sphinx-quickstart on Thu Mar 18 10:17:15 2010. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to plone.app.discussion's documentation! -================================================ - -.. module:`plone.app.discussion` - - -Contents: - -.. toctree:: - :maxdepth: 2 - - architecture.txt - design.txt - workflow.txt - captcha.txt - email-notification.txt - api/index.txt - howtos/index.txt - - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff --git a/docs/source/workflow.txt b/docs/source/workflow.md similarity index 61% rename from docs/source/workflow.txt rename to docs/source/workflow.md index 33fbf8ef..8a751e5d 100644 --- a/docs/source/workflow.txt +++ b/docs/source/workflow.md @@ -1,41 +1,43 @@ -========================= -Permissions and Workflows -========================= +--- +myst: + html_meta: + "description": "Permissions and Workflows - plone.app.discussion documentation" + "property=og:description": "Permissions and Workflows - plone.app.discussion documentation" + "property=og:title": "Permissions and Workflows" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +# Permissions and Workflows This document describes how plone.app.discussion handles permissions and workflows. - -Introduction -============ +## Introduction plone.app.discussion uses permissions and workflows to control what a user is allowed to do. It tries to use the default Plone permissions and workflow engine as much as possible. - -Permissions -=========== +## Permissions plone.app.discussion knows two permissions to control what a user is allowed to do. The 'Reply to item' permission to control who is allowed to post a comment on a content object and the 'Review comments' permission to control who is allowed to review comments. -1) **Permission to post a comment**: +1. **Permission to post a comment**: The permission to post a comment is controlled by the 'Reply to item' permission. By default, this permission is granted to the 'Member', 'Reviewer', and 'Manager' role. -2) **Permission to review comments**: +2. **Permission to review comments**: The permission to review comments is controlled by the 'Review comments' permission. By default, this permission is granted to the 'Reviewer' and 'Manager' role. -Changing permissions --------------------- +### Changing permissions If you want to change the way plone.app.discussion allows users to post or review comments you can do that by changing which permissions are granted to @@ -49,24 +51,25 @@ comments, you have to grant the 'Reply to item' permission to the Or, if you don't want to allow 'Reviewers' to review comments anymore, you can just remove the 'Review comments' permission from the 'Reviewer' role. -.. note:: For a general introduction to permissions and roles in Plone see: +:::{note} +For a general introduction to permissions and roles in Plone see: - http://plone.org/documentation/kb/understanding-permissions/permissions-and-roles + - http://plone.org/products/dexterity/documentation/manual/developer-manual/advanced/permissions + +::: -Workflows -========= +## Workflows plone.app.discussion ships with a simple one-state workflow and a review workflow for comments: -1) **Comment Single State Workflow**: +1. **Comment Single State Workflow**: Essentially a workflow with no transitions, but it has a published state, so portlets and applications that expect that state will continue to work. -2) **Comment Review Workflow**: A simple review workflow for comments +2. **Comment Review Workflow**: A simple review workflow for comments A simple review workflow that comes with two states (pending and published) and a single transition (publish). @@ -76,31 +79,27 @@ workflow and a review workflow for comments: The 'publish' transition is protected by the 'Review comments' permission. - :: - - * --> [pending] -- {publish} --> [published]--> * - -.. note:: For a general introduction to workflows in Plone see: - http://plone.org/documentation/kb/creating-workflows-in-plone/ + ``` + * --> [pending] -- {publish} --> [published]--> * + ``` +:::{note} +For a general introduction to workflows in Plone see: + +::: -Custom comment workflow ------------------------ +### Custom comment workflow You can create and enable any custom workflow on the "comment" content type. Though, there are some special hooks in plone.app.discussion that check if the workflow that is enabled for the "comment" content type has a 'pending' state in order to do the following things: - 1) A portal message will be shown to the user after posting a comment, if - the comment just entered the 'pending' state. - - 2) A message is shown to the user if he/she accesses the bulk moderation view - and workflow is enabled for comments that does not implement a 'pending' - state. - - 3) A moderator will only be emailed when comment moderation is enabled in the - discussion control panel and the comment workflow contains a 'pending' - state. - - +> 1. A portal message will be shown to the user after posting a comment, if +> the comment just entered the 'pending' state. +> 2. A message is shown to the user if he/she accesses the bulk moderation view +> and workflow is enabled for comments that does not implement a 'pending' +> state. +> 3. A moderator will only be emailed when comment moderation is enabled in the +> discussion control panel and the comment workflow contains a 'pending' +> state. diff --git a/docs/workflow.md b/docs/workflow.md new file mode 100644 index 00000000..8a751e5d --- /dev/null +++ b/docs/workflow.md @@ -0,0 +1,105 @@ +--- +myst: + html_meta: + "description": "Permissions and Workflows - plone.app.discussion documentation" + "property=og:description": "Permissions and Workflows - plone.app.discussion documentation" + "property=og:title": "Permissions and Workflows" + "keywords": "Plone, Discussion, Comments, Documentation" +--- + +# Permissions and Workflows + +This document describes how plone.app.discussion handles permissions and +workflows. + +## Introduction + +plone.app.discussion uses permissions and workflows to control what a user is +allowed to do. It tries to use the default Plone permissions and workflow +engine as much as possible. + +## Permissions + +plone.app.discussion knows two permissions to control what a user is allowed to +do. The 'Reply to item' permission to control who is allowed to post a comment +on a content object and the 'Review comments' permission to control who is +allowed to review comments. + +1. **Permission to post a comment**: + + The permission to post a comment is controlled by the 'Reply to item' + permission. By default, this permission is granted to the 'Member', + 'Reviewer', and 'Manager' role. + +2. **Permission to review comments**: + + The permission to review comments is controlled by the 'Review comments' + permission. By default, this permission is granted to the 'Reviewer' and + 'Manager' role. + +### Changing permissions + +If you want to change the way plone.app.discussion allows users to post or +review comments you can do that by changing which permissions are granted to +which rules. In Plone permissions are always granted to roles, not to users +directly. + +For instance, if you want to allow users without the 'Member' role to post +comments, you have to grant the 'Reply to item' permission to the +'Authenticated' role. + +Or, if you don't want to allow 'Reviewers' to review comments anymore, you +can just remove the 'Review comments' permission from the 'Reviewer' role. + +:::{note} +For a general introduction to permissions and roles in Plone see: + + + + +::: + +## Workflows + +plone.app.discussion ships with a simple one-state +workflow and a review workflow for comments: + +1. **Comment Single State Workflow**: + + Essentially a workflow with no transitions, but it has a published state, + so portlets and applications that expect that state will continue to work. + +2. **Comment Review Workflow**: A simple review workflow for comments + + A simple review workflow that comes with two states (pending and published) + and a single transition (publish). + + The 'pending' state is the initial state. 'published' is the state where the + comment is visible to everyone and non-editable. + + The 'publish' transition is protected by the 'Review comments' permission. + + ``` + * --> [pending] -- {publish} --> [published]--> * + ``` + +:::{note} +For a general introduction to workflows in Plone see: + +::: + +### Custom comment workflow + +You can create and enable any custom workflow on the "comment" content type. +Though, there are some special hooks in plone.app.discussion that check if the +workflow that is enabled for the "comment" content type has a 'pending' state in +order to do the following things: + +> 1. A portal message will be shown to the user after posting a comment, if +> the comment just entered the 'pending' state. +> 2. A message is shown to the user if he/she accesses the bulk moderation view +> and workflow is enabled for comments that does not implement a 'pending' +> state. +> 3. A moderator will only be emailed when comment moderation is enabled in the +> discussion control panel and the comment workflow contains a 'pending' +> state. From 17a99b252c1e34cac28f984b3c9ca61355bc773c Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 8 Jun 2025 14:06:44 -0700 Subject: [PATCH 4/4] Remove project meta files for now. We can address these in a separate PR, where we do project maintenance, including adding Python 3.13 support, `.meta.toml` configuration, and other tasks. This PR should focus solely on documentation in the `docs/` directory. --- CHANGES.md | 1541 ----------------------------------------------- CONTRIBUTING.md | 1 - README.md | 43 -- 3 files changed, 1585 deletions(-) delete mode 100644 CHANGES.md delete mode 100644 CONTRIBUTING.md delete mode 100644 README.md diff --git a/CHANGES.md b/CHANGES.md deleted file mode 100644 index f8accb7e..00000000 --- a/CHANGES.md +++ /dev/null @@ -1,1541 +0,0 @@ -# Changelog - -% You should *NOT* be adding new change log entries to this file. -% You should create a file in the news directory instead. -% For helpful instructions, please see: -% https://github.com/plone/plone.releaser/blob/master/ADD-A-NEWS-ITEM.rst - -% towncrier release notes start - -## 5.1.0 (2025-05-02) - -New features: - -- Implement auto_approve_admin_comments based on specified roles @rohnsha0 (#261) - -Bug fixes: - -- Fix improper handling of logic for showing delete button @rohnsha0 (#182) - -Internal: - -- Update configuration files. - [plone devs] - -## 5.0.0 (2025-02-06) - -Internal: - -- Make final release, no changes. [maurits] (#610) - -## 5.0.0a3 (2025-01-23) - -Bug fixes: - -- Do not depend on `plone.api`. [ale-rt] (#188) -- Fix DeprecationWarnings. [maurits] (#4090) - -## 5.0.0a2 (2024-10-23) - -New features: - -- Update robot framework tests to use - `robotframework-browser` (`playwright` integration on robotframework). - [gforcada] (#3813) - -## 5.0.0a1 (2024-09-05) - -Breaking changes: - -- Move this package in the space of Plone Core add-ons. - It now depends on Products.CMFPlone and is no longer installed by default. - It is still available in the default Plone distribution, but can be omitted in customizations. - Installing this in the Add-ons control panel will enable comments globally. - [jensens] (#211) - -Bug fixes: - -- Fix redirection after comment edit to main content, preventing NotFound. [@jensens] (#211) -- Add missing icon on comments' `view` action - Register contenttype icon for comments. - [gforcada, maurits] (#222) - -## 4.1.2 (2024-04-16) - -Internal: - -- Add capture screen in robot tests to debug. @wesleybl (#235) -- Fix robot test `Add a Comment to a Document and bulk delete it`. @wesleybl (#237) -- Fix robot test `Add a Comment to a Document and bulk delete it` 2. @wesleybl (#238) -- Fix robot test `Add a Comment to a Document and bulk delete it` 3. @wesleybl (#239) - -## 4.1.1 (2024-03-22) - -Bug fixes: - -- Apply validation for all captchas. @ksuess (#234) - -## 4.1.0 (2024-03-19) - -New features: - -- Provide HCaptcha if plone.formwidget.hcaptcha is installed. @ksuess (#230) - -Internal: - -- Fix test "Add a Comment to a Document and bulk delete it". @wesleybl (#228) - -## 4.0.5 (2024-03-15) - -Bug fixes: - -- Fix test "Add a Comment to a Document and bulk delete it". @wesleybl (#226) - -Internal: - -- Fix test "Add a Comment to a Document and bulk delete it" 2. @wesleybl (#227) - -## 4.0.4 (2024-02-21) - -Bug fixes: - -- Report the upgrade steps progress, - really useful for sites with lots of comments. - [gforcada] - -## 4.0.3 (2024-02-13) - -Bug fixes: - -- Do not autofocus on the comments form. - [maurits] (#3623) - -## 4.0.2 (2023-07-14) - -Internal: - -- Update configuration files. - [plone devs] (cfffba8c) - -## 4.0.1 (2023-04-14) - -Internal: - -- Remove translations folder, - for ages they are coming from p.a.locales. - [gforcada] (#1) -- Update configuration files. - [plone devs] (#47959565) - -## 4.0.0 (2022-11-11) - -Bug fixes: - -- Set timezones for creation and modification dates of comments [instification] (#204) - -## 4.0.0b3 (2022-10-11) - -Bug fixes: - -- Fix password used in tests. [davisagli] (#203) - -## 4.0.0b2 (2022-09-30) - -Bug fixes: - -- Use longer passwords in tests. [davisagli] (#203) - -## 4.0.0b1 (2022-06-23) - -Bug fixes: - -- Test-only fix: normalize white space when comparing output of `comment.getText()`. - Needed to not fail with newer `plone.outputfilters`. - [maurits] (#49) - -## 4.0.0a7 (2022-05-14) - -Breaking changes: - -- Code style black & isort. Remove six usage. Use plone.base and move annotation key over to here. - [jensens] (#195) - -Bug fixes: - -- Make compatible with robotframework 3-5. - [maurits] (#5) -- Grant Site Administrators the same workflow permissions as Managers. - They were missing permissions on pending comments. - [maurits] (#199) -- Removed z3c.autoinclude.plugin entrypoint. [maurits] (#3188) - -## 4.0.0a6 (2022-04-28) - -Bug fixes: - -- Replaced use of `plone.api`. That should not be done in Plone core. - [maurits] (#188) - -## 4.0.0a5 (2022-04-04) - -New features: - -- Moved JS to Mockup control panel patterns (ES6) [MrTango] (#190) - -## 4.0.0a4 (2022-03-23) - -New features: - -- Added 'View comments' permission. [@razvanMiu] (#180) - -## 4.0.0a3 (2021-10-16) - -Bug fixes: - -- Add missing i18n:translate tags - [erral] (#189) - -## 4.0.0a2 (2021-09-15) - -New features: - -- Refactor templates and styling for comments and controlpanel. - [santonelli] (#169) -- Implement events for Comment (ICommentModifiedEvent) and Reply(IReplyModifiedEvent) modification [ericof] (#183) - -Bug fixes: - -- Fix tests with Products.MailHost 4.11. - [maurits] (#174) -- Remove cyclic dependency with Products.CMFPlone - [ericof] (#186) - -## 4.0.0a1 (2021-04-21) - -New features: - -- Refactor templates and styling for comments and controlpanel. - [santonelli] (#169) -- Cleanup template and move message to python code. - [santonelli] (#177) - -Bug fixes: - -- Fix tests with Products.MailHost 4.11. - [maurits] (#174) - -## 3.4.4 (2020-10-09) - -New features: - -- Update templates markup to Bootstrap 4. - [andreesg] - -## 3.4.3 (2020-09-28) - -Bug fixes: - -- Fix tests with Products.MailHost 4.10. - [maurits] (#3178) - -## 3.4.2 (2020-06-30) - -Bug fixes: - -- Close input tags properly in moderation.pt to avoid an error with i18ndude find-untranslated - [vincentfretin] (#171) - -## 3.4.1 (2020-06-26) - -Bug fixes: - -- Reuse existing translation for the "Save" button in the Edit comment form. - [vincentfretin] (#170) - -## 3.4.0 (2020-04-20) - -New features: - -- Extended existing review workflow by state `rejected` and `spam` - Moderation view extended to handle four workflow states. - [ksuess and precious input of agitator] (#164) - -Bug fixes: - -- Fix tests failing for Plone 6, deprecate Plone 4 and older. - [tschorr] (#168) - -## 3.3.2 (2019-12-10) - -New features: - -- Notification for moderator: show email address of commentator. (#163) -- Link to the commented page for editing, approving, deleting comment instead of linking to `/@@moderate-publish-comment` and `@@moderate-delete-comment`. - [ksuess] (#163) - -Bug fixes: - -- `/@@moderate-publish-comment`: publish only pending comment, else show status message "comment already approved". - [ksuess] (#163) - -## 3.3.1 (2019-11-25) - -Bug fixes: - -- Use the shared 'Plone test setup' and 'Plone test teardown' keywords in Robot tests. - [Rotonen] (#155) - -## 3.3.0 (2019-10-12) - -New features: - -- Additional view for approved comments - [ksuess] (#159) - -Bug fixes: - -- Load zcml of `plone.resource` for our use of the `plone:static` directive. - [maurits] (#2952) - -## 3.2.1 (2019-06-28) - -Bug fixes: - -- Fix reply to comment by adding old-school js-resources to legacy-bundle. Fix #157 - [pbauer] (#157) - -## 3.2.0 (2019-04-29) - -New features: - -- Index/reindex/unindex the comment itself, do not defer to `ICommentingTool`. - This way it can be integrated into collective.indexing and Solr (or any other indexing tool). - [gforcada] (#77) - -Bug fixes: - -- Fixed DeprecationWarning for ObjectEvent. [jensens] (#153) - -## 3.1.1 (2019-02-08) - -Bug fixes: - -- Changed \$(window).load with \$(document).ready in moderation.js because in - some version of FF and IE doesn't work. [eikichi18] (#144) -- a11y: Added role attribute for portalMessage [nzambello] (#145) -- Do not depend on the `meta_type` metadata in the catalog. [jensens] (#146) - -## 3.1.0 (2018-10-30) - -New features: - -- Added notification about the publishing or elimination of a comment. - [eikichi18] - -Bug fixes: - -- Fix location of controlpanel events. - [jensens] -- Fixed tests when IRichText behavior is used. - IRichText -> IRichTextBehavior - This is a follow up to [issue 476](https://github.com/plone/plone.app.contenttypes/issues/476). - [iham] -- Fix commenting and tests in python 3. - [pbauer, jensens] - -## 3.0.6 (2018-06-18) - -Bug fixes: - -- Fix tests to work with merges plone.login. - [jensens] -- More Python 2 / 3 compatibility. - [pbauer, hvelarde] - -## 3.0.5 (2018-02-04) - -Bug fixes: - -- Add Python 2 / 3 compatibility - [pbauer] - -## 3.0.4 (2017-11-24) - -Bug fixes: - -- Make sure the effects of the robotframework REMOTE_LIBRARY_ROBOT_TESTING fixture - are not accidentally removed when tearing down the PLONE_APP_DISCUSSION_ROBOT_TESTING fixture. - [davisagli] - -## 3.0.3 (2017-08-27) - -Bug fixes: - -- Show email in moderation view [ksuess] -- Remove plone.app.robotframework extras (reload and ride). - They are not needed and they are not Python 3 compatible. - [gforcada] - -## 3.0.2 (2017-07-03) - -New features: - -- Validate that author_email values are emails. - [ksuess] - -## 3.0.1 (2017-05-31) - -Bug fixes: - -- Remove unittest2 dependency - [kakshay21] - -## 3.0.0 (2017-02-12) - -Bug fixes: - -- Fixed tests with newer testbrowser. - [mauristvanrees] -- Remove deprecated \_\_of\_\_ calls on BrowserViews - [MrTango] -- Improve English on a couple of field descriptions - [djowett] -- Fix some easy pep8 issues - [djowett] - -## 2.4.20 (2017-01-17) - -Bug fixes: - -- Make comment on private content not publicly available in search results. - Part of PloneHotfix20161129. [vangheem, maurits] - -## 2.4.19 (2017-01-02) - -New features: - -- Reindex comments when they are modified. - [gforcada] - -## 2.4.18 (2016-09-20) - -Bug fixes: - -- Apply security hotfix 20160830 for redirects. [maurits] -- Update Traditional Chinese translation. - [l34marr] - -## 2.4.17 (2016-08-17) - -Bug fixes: - -- Use zope.interface decorator. - [gforcada] - -## 2.4.16 (2016-06-27) - -Bug fixes: - -- Cleaned code from flake8 errors. [maurits] -- Removed `comment-migration` view. This did not work anymore on - Plone 5. If you still need to migrate from old-style comments, so - from Plone 4.0 or earlier, please upgrade to Plone 4.3 first. - [maurits] - -## 2.4.15 (2016-06-12) - -Bug fixes: - -- Reset the required setting of the author_email widget each time. - Otherwise, the email field might get set to required when an - anonymous user visits, and then remain required when an - authenticated user visits, making it impossible for an authenticated - user to fill in the form without validation error. Or when in the - control panel the field is set as not required anymore, that change - would have no effect until the instance was restarted. [maurits] - -## 2.4.14 (2016-06-06) - -New features: - -- Make tests work with lxml safe html cleaner - -Bug fixes: - -- Fixed possible cross site scripting (XSS) attack on moderate comments page. [maurits] - -## 2.4.13 (2016-05-04) - -Fixes: - -- Removed docstrings from some methods to avoid publishing them. From - Products.PloneHotfix20160419. [maurits] - -## 2.4.12 (2016-04-13) - -Fixes: - -- Mark 'Edit' button for translation. - - [gforcada] - -## 2.4.11 (2016-03-31) - -New: - -- For the discussion controlpanel, change base URLs from portal URL to what getSite returns, but don't change the controlpanels context binding. - This allows for more flexibility when configuring it to be allowed on a sub site with a local registry. - [thet] - -Fixes: - -- fixed translate translation plone-ru.po - -## 2.4.10 (2016-02-08) - -New: - -- Added russian translations. [serge73] - -Fixes: - -- Get rid of the monkey patch on Products.CMFPlone's CatalogTool. - Issue - [staeff, fredvd] -- Cleanup code according to our style guide. - [gforcada] - -## 2.4.9 (2015-11-25) - -Fixes: - -- Update Site Setup link in all control panels (fixes ) - [davilima6] -- In tests, use `selection.any` in querystrings. - Issue - [maurits] -- Move translations to plone.app.locales - - [gforcada] - -## 2.4.8 (2015-09-20) - -- Use registry lookup for types_use_view_action_in_listings - [esteele] -- Remove discussion.css - [pbauer] -- Fix reply button not showing up since it uses a hide class which needs - to be removed instead of a display value - [ichim-david] - -## 2.4.7 (2015-09-15) - -- Tweak discussions.css styles to better live with plonetheme.barcelonata - [ichim-david] - -## 2.4.6 (2015-09-14) - -- Fix editing comments in Plone 5. - [pbauer] -- Move anonymous_email_enabled after anonymous_comments in controlpanel. - [pbauer] - -## 2.4.5 (2015-09-11) - -- Updated basque translation - [erral] - -## 2.4.4 (2015-07-18) - -- Change the category of the configlet to 'plone-general'. - [sneridagh] -- Updated links for the renamed 'Types' control panel. - [sneridagh] -- Updated Spanish translation. - [Caballero] - -## 2.4.3 (2015-06-05) - -- Update Spanish translation. - [macagua] -- Only use edit overlay if available for editing comments - [vangheem] - -## 2.4.2 (2015-05-04) - -- Update Japanese translation. - [takanory] -- Update Japanese translation. - [terapyon] -- Sort imports as per plone.api styleguide. - [gforcada] -- Fix flake8 errors reported by jenkins.plone.org. - [gforcada] - -## 2.4.1 (2015-03-26) - -- i18n for ICaptcha interface. - [davidjb] - -## 2.4.0 (2015-03-12) - -- use requirejs if available - [vangheem] -- Rename @@discussion-settings to @@discussion-controlpanel - [maartenkling] -- Add permission to allow comment authors to delete their own comments if - there are no replies yet. - [gaudenz] -- Updated portuguese pt-br translation. - [jtmolon] -- Read mail settings from new (Plone 5) registry. - [timo] -- Remove @property from Conversation.total_comments as @property and - Acquisition don't play well together. - [gforcada] - -## 2.3.3 (2014-10-23) - -- Don't execute createReplyForm js if there is no in_reply_to button. - [vincentfretin] -- Register events as Content Rules Event Types if plone.contentrules is present - [avoinea] -- Trigger custom events on comment add/remove/reply - [avoinea] -- Replace \$.live with \$.on for jQuery >= 1.9 compatibility. This works on - jQuery >= 1.7 (Plone 4.3 onwards). - [gaudenz] -- Update Traditional Chinese translations. - [marr] -- Make comments editable. - [pjstevns, gyst] -- Provide 'Delete comments' permission to handle comments deletion - [cekk] -- Fixed Italian translations [cekk] - -## 2.3.2 (2014-04-05) - -- bugfix: according to IDiscussionSettings.anonymous_email_enabled (cite): - "If selected, anonymous user will have to give their email." - But field - was not required. Now it is. - [jensens] -- bugfix: anonymous email field was never saved. - [jensens] -- updated german translations: added some missing msgstr. - [jensens] -- added i18ndude and a script `update_translations` to buildout in order - to make translation updates simpler. - [jensens] -- Fix reindexObject for content_object in moderation views. - Now reindex only "total_comments" index and not all the indexes - [cekk] -- Fix comments Title if utf-8 characters in author_name - [huub_bouma] -- use member.getId as author_username, so membrane users having different id - then username still have there picture shown and author path is correct. - [maartenkling] - -## 2.3.1 (2014-02-22) - -- 2.3.0 was a brown bag release. - [timo] - -## 2.3.0 (2014-02-22) - -- Remove DL's from portal message in templates. - - [khink] -- Execute the proper workflow change when using the moderation buttons instead - of hardcoding the workflow action to always publish - [omiron] -- Corrections and additions to the Danish translation - [aputtu] - -## 2.2.12 (2014-01-13) - -- Show author email to Moderator when it is available in anonymous comment. - [gotcha, smoussiaux] -- Put defaultUser.png instead of old defaultUser.gif - [bsuttor] -- Remove bbb directory. bbb was never really implemented. - [timo] -- Replace deprecated test assert statements. - [timo] -- Remove portal_discussion tool. - [timo] -- Refactor tests to use the PLONE_APP_CONTENTTYPES_FIXTURE instead of - PLONE_FIXTURE. - [timo] -- Fix ownership of comments. - [toutpt] - -## 2.2.10 (2013-09-24) - -- Revert "Refactor tests to use the PLONE_APP_CONTENTTYPES_FIXTURE instead of - the PLONE_FIXTURE." that has been accidentally introduced into the 2.2.9 - release. - [timo] - -## 2.2.9 (2013-09-24) - -- Portuguese translation added. - [Rui Silva] -- Rename CHANGES.txt to CHANGES.rst. - [timo] -- Fix ajax form submit for delete comment action: add 'data' to the request. - [toutpt] - -## 2.2.8 (2013-08-20) - -- Re-release 2.2.7 with .mo files. Seems like 2.2.7 has been released twice on - two different dates. The first release seems to be made without a github - push. - [timo] -- Fix comments viewlet's get_replies for non-annotatable objects. - [witsch] - -## 2.2.7 (2013-07-04) - -- making sure .mo files are present at release - [garbas] -- Revert change that silently added mime_type attribute values - to old discussion items that had none. - [pjstevns] - -## 2.2.6 (2013-05-23) - -- Fix migration to not fail when member has been deleted. - [datakurre] - -## 2.2.5 (2013-04-06) - -- Update pt_BR translation [ericof] -- Do not raise an error when no workflow is assigned to the comment type. - [timo] -- Add a conversation property public_commentators that only lists - commentators of comments that are public. - The commentators indexer indexes this field now. - The behavior of the conversation property commentators is - unchanged. - [do3cc] -- The last comment date now only returns the date of the newest - published comment. - [do3cc] - -## 2.2.4 (2013-03-05) - -- Check for 'checked' attribute in a way that work also for jQuery 1.7 - [ichimdav] -- Better fix for #13037 by removing submit event trigger altogether - [ichimdav] -- Added Romanian translation - [ichimdav] -- Updated Ukrainian translation - [kroman0] - -## 2.2.3 (2013-01-13) - -- add anonymous_email_enabled settings to really let integrator activate - the email field on comment add form when anonymous. - [toutpt] - -## 2.2.2 (2012-11-16) - -- first check if captcha is installed before we open browsers zcml - files that depend on these packages, fixes #12118 and #12774 - [maartenkling] - -## 2.2.1 (2012-11-16) - -- Make conversation view not break when comment-id cannot be converted to - long. This fixes #13327 - [khink] -- fix insufficient privileges when trying to view - the RSS feed of a comment collection - [maartenkling] -- removed inline border=0 and move it to css - [maartenkling] -- For migrations of comments without a valid old_status, apply the 'published' - state. - [thet] -- Re-apply eleddy's "Revert modification date since this is fixed in - p.a.caching now." as her commit was lost later on due to some git magic. - [thet] -- Remove submitting the controlpanel form again after removing disabled tags - fixes #13037 and #12357 - [maartenkling] -- Remove inline styles, fixes #12399 - [maartenkling] -- add fallback border color for i8, fixes #11324 - [maartenkling] -- Replace discussionitem_icon.gif with png version. - [timo] -- Fix catalog updates for IObjectMovedEvent - [gaudenz] -- Fix non-functioning user_notification feature - [izak] - -## 2.2.0 (2012-08-30) - -- Refactor the comment creator/author_name to comply with the Plone core - convention to store the username on the creator attribute and not the - fullname. - [timo] -- Rename the id of the text widgets because there can be css-id clashes with - the text field of documents when using TinyMCE in overlays or multiple - instances of TinyMCE on a single page. - [timo] -- text/html added to the possible mime types for comments. - [timo] -- Make 'text/plain' the default mime type for comments and make sure the - default type is set properly when creating a new comment. - [timo] -- Fix handling of comments with invalid transforms. Write an error msg - to the log and just return the untransformed text. - [timo] - -## 2.1.8 (unreleased) - -- Support for Dexterity added. The conversation enabled method now detects and - supports Dexterity-based content types. - [timo] -- No more recursive came_from redirection after logged_in. - [kcleong, huubbouma] -- Danish translation updated. - [stonor] -- Documentation and howtos updated. - [timo] -- Remove development buildout files and directories. - [timo] - -## 2.1.7 (2012-06-29) - -- Prune duplicated test code. - [pjstevns] -- Update version in buildout.cfg to allow development. - [pjstevns] -- Conversation.total_comments only counts published comments. - Fixes bug #11591. - [pjstevns] -- Set workflow status of comments during migration based on - the state of the Discussion Item. - [pjstevns] - -## 2.1.6 (2012-05-30) - -- Add Site Administrator role to Review comments permission. - [gaudenz] -- Fix excessive JS comment deletion. - [gaudenz] -- Hide Conversation objects from breadcrumb navigation. The breadcrumbs - navigation is also used in the search results view. This lead to Conversation - objects showing up if 'Discussion Items' are searchable. - [gaudenz] -- No longer depend on zope.app packages. - [hannosch] - -## 2.1.5 (2012-04-05) - -- Redirect to "/view" for Image, File and anything listed as requiring - a view in the url to properly display comments. - [eleddy] -- Make comments and controlpanel views more robust, so they don't break if no - workflow is assigned to the 'Discussion Item' content type. - [timo] -- Warning message added to discussion control panel that shows up if there are - unmigrated comments. - [timo] -- Make topic/collection tests pass when plone.app.collection is installed. - [timo] - -## 2.1.4 (2012-02-29) - -- Revert modification date since this is fixed in p.a.caching now. - [eleddy] -- Add missing meta_typ to "Review comments" portal action. - [batlock666] - -## 2.1.3 (2012-01-24) - -- Set modified date of object receiving comments so that caching works - correctly (304s) - [eleddy] - -## 2.1.2 (2011-12-21) - -- Fixed language code error in Ukrainian translation. The message - catalog was erroneously set to "English". - [chervol] -- Do not raise an error if the comment text is None. - [timo] -- Updated Spanish translation. - [hvelarde] -- Fix that catalog rebuild breaks the path attribute on comments. This fixes - . - [pjstevns] - -## 2.1.1 (2011-11-24) - -- Include mo files in the distribution. - [vincentfretin] -- Fix various text typos. - [timo] -- Fix control panel help text typos. - [jonstahl] -- Documentation about overriding the comments viewlet js added. - [timo] -- Corrected location of Japanese po file. - [tyam] - -## 2.1.0 (2011-08-22) - -- Avoid error when moving objects that are contentish but not annotatable. - [davisagli] -- New feature: Markdown syntax added to possible comment text transforms. - [timo] -- Make sure the comment brains are updated properly when the content object is - renamed. - [hannosch, timo] -- Make sure only comments to the content object are removed from the catalog - when the content object is moved. - [hannosch, timo, davisagli] -- Make sure the conversation.getComments method returns acquisition wrapped - comments. - [timo] -- Ukrainian translation added. - [chervol] -- Remove one_state_workflow customizations. - [timo] - -## 2.0.9 (2011-07-25) - -- Make sure the creator index always stores utf-8 encoded strings and not - unicode. - [timo] - -## 2.0.8 (2011-07-25) - -- Automatically reload batch moderation page if no comments are left. This - fixes . - [timo] -- Use Plone's safe_encode method instead of encode() for the creator index to - make sure unicode encoded strings can be indexed too. - [timo] - -## 2.0.7 (2011-07-15) - -- Fix discussion control panel submit for Google Chrome. This fixes - . - -## 2.0.6 (2011-07-04) - -- Update comment brains in zcatalog when moving a content object with comments. - This fixes . - [timo] -- Plone 3 specific exclusion of plone.app.uuid removed. - [timo] - -## 2.0.5 (2011-06-16) - -- Simplify CSS and JS registrations. CSS will now be imported using the - standard link and so can be merged, inserted after forms.css. JS will now be - imported after collapsibleformfields.js. - [elro] -- Enable the left-menu on the configlet, to be more consistent with all other - configlets. Related to - [WouterVH] -- Do not render/update the comment form in CommentViewlets if commenting is - disabled, since this slows down the page rendering. This fixes - - [fafhrd] - -## 2.0.4 (2011-05-28) - -- Refactor/clean up the handleComment method. - [timo] -- Make handleComment method store comment attributes from form extenders. This - allows us to extend the comment form with external add-ons. See - - for details. - [timo] - -## 2.0.3 (2011-06-19) - -- Updated Simplified Chinese translation - [jianaijun] -- Italian translation review. - [gborelli] - -## 2.0.2 (2011-05-12) - -- Moderation should be enabled only if there is a workflow set for Discussion - Item. - [erico_andrei] - -## 2.0.1 (2011-04-22) - -- Translations updated. German translations for notifications added. - [timo] -- Add links to delete/approve a comment in the moderator notification email. - [timo] -- Remove the unnecessary workflow_action parameter from the PublishComments - request. - [timo] -- Make sure the email settings in the control panel are disabled when commenting - is disabled globally. - [timo] -- Enable/disable moderator_email setting dynamically as mail settings or - discussion settings change. - [timo] -- Remove ImportError exceptions for Plone < 4.1 code and plone.z3cform < 0.6.0. - [timo] -- Provide the comment body text in the email notification. - [timo] -- Fix comment link in email notification. This fixes - . - [timo] -- Redirect to the comment itself when notifying a user about a new comment. - [timo] - -## 2.0 (2011-04-21) - -- No changes. - -## 2.0b2 (2011-04-21) - -- Added Japanese translation. - [tyam] -- Move all tests from testing layer to plone.app.testing. - [timo] -- Move some policy out of the conversation storage adapter into a - view, specifically "enabled()". Prevents having to replace/migrate - persistent objects to change policy which really only concerns the - context and possibly the request, not the conversation storage. - Fixes #11372. - [rossp] -- Fix unindexing of comments when deleting content resulting from - iterating over a BTree while modifying it. Fixes #11402. - [rossp] -- Fix Missing.Value for Creator in the catalog. Fixes #11634. - [rossp] -- Don't add the annotation unless a comment is actually being added. - Fixes #11370. - [rossp] -- Fixed i18n of the "Commenting has been disabled." message. - [vincentfretin] -- Add a moderator_email setting to control where moderator notifications are - sent. - [davisagli] - -## 2.0b1 (2011-04-06) - -- Make discussion.css cacheable when registering it. - [davisagli] -- Fix issue where GMT datetimes were converted into local timezone DateTimes - during indexing. - [davisagli] -- Handle timezones correctly while converting dates during the migration of - legacy comments. - [davisagli] -- When returning a comment's title, give preference to its title attribute - if set. - [davisagli] -- Use the cooked text of legacy comments when migrating. - [davisagli] -- Make sure that comment text is transformed to plain text when indexing. - [davisagli] -- Move logic for transforming comment text to the Comment class's getText - method. Use a comment instance's mime_type attribute in preference to the - global setting for the source mimetype. Use text/x-html-safe as the target - mimetype to make sure the safe HTML filter is applied, in case the source is - untrusted HTML. - [davisagli] -- Provide a filter_callback option to the migration view, so that a custom - policy for which comments get migrated can be implemented. - [davisagli] -- Fixed RoleManager import to avoid deprecation warning on Zope 2.13. - [davisagli] -- French translations. - [thomasdesvenain] -- Fixed internationalization issues. - [thomasdesvenain] -- Added Afrikaans translations - [jcbrand] - -## 2.0a3 (2011-03-02) - -- Fixed test failure for the default user portrait, which changed from - defaultUser.gif to defaultUser.png in Products.PlonePAS 4.0.5 - [maurits] - -## 2.0a2 (2011-02-08) - -- Fixed test failure for the default user portrait, which changed from - defaultUser.gif to defaultUser.png in Products.PlonePAS 4.0.5. - [maurits] -- Remove "Plone 3 only" code. - [timo] -- Do not monkey patch the BAD_TYPES vocabulary or plone.app.vocabularies - anymore. - [timo] - -## 2.0a1 (2011-02-07) - -- Split up development into two branches. The 1.x branch will be for Plone 3.x - and Plone 4.0.x and the 2.x branch will be for Plone 4.1 and beyond. - [timo] -- Import Owned from OFS.owner to avoid deprecation warnings. - [timo] -- Disable discussion by default. - [timo] -- Enable ajaxify comment deletion again ([thomasdesvenain]). This has been - disabled in 1.0b12 because of problems with Plone 3. - [timo] -- Remove collective.autopermission dependency that has become unnecessary in - Plone 4.1. - [timo] - -## 1.0 (2011-02-07) - -- Do not check for a comment review workflow when sending out a moderator email - notification. This fixes . - [timo] -- Check if the current user has configured an e-mail address for the email - notification option. This fixes . - [timo] - -## 1.0RC2 (2011-01-24) - -- Remove moderation_enabled setting from registry to avoid migration problems - to 1.0RC1. This fixes . - [timo] - -## 1.0RC1 (2011-01-22) - -- Always show existing comments, even if commenting is disabled. - [timo] -- Fix CSS for commenter images with a width of more than 2.5em. This fixes - . - [timo] -- Show a 'Comments are moderated.' message next to the comment form if comments - are moderated. - [timo] -- Make sure plone.app.registry's ZCML is loaded, so that its import step will run - when plone.app.discussion is installed. - [davisagli] -- Avoid sending multiple notification emails to the same person when - he has commented multiple times. - [maurits] -- Move discussion action item from actionicons.xml to actions.xml to avoid - deprecation warning. - [timo] -- Fix cancel button on edit view when using Dexterity types. This fixes - . - [EpeliJYU] -- Assigning the 'Reply to item' permission to the 'Authenticated' role. The old - commenting system allowed 'Authenticated' users to post comments. Also, OpenID - users do not possess the 'Authenticated' role. - [timo] -- Make sure the handleComment method checks for the 'Reply to item' permission - when adding a comment. - [timo] -- Make the mail-setting warning message show up in the discussion control panel. - [timo] -- Link directly to the "Discussion Item" types control panel in the moderation - view. - [timo] -- Show "moderate comments" link in the admin panel only if a moderation - workflow is enabled for comments. - [timo] -- Do not allow to change the mail settings in the discussion control panel, if - there is no valid mail setup. - [timo] -- Disable all commenting options in the discussion control panel if comments - are disabled globally. -- Check for the 'review comments' permission instead of 'manage' to decide - if the user should see a 'this comment is pending' message. - [timo] -- Move "moderate comments" site action above the logout action. - [timo] -- Moderator notification description updated. - [timo] -- Redirect back to the discussion control panel when the discussion control - panel form is submitted. - [timo] -- Fix document_byline bottom margin if commenter images are disabled. - [timo] -- Dynamically show the comment formatting message dependent on the text - transform setting. - [timo] -- Description for text transform added to the discussion control panel. - [timo] -- Move the discussion control panel to the core Plone configuration. - [timo] -- Always set the effective date of a comment to the same value as the creation - date. - [timo] -- Fix SMTP exception when an email is send to the moderator. - [timo] -- Make sure comment UIDs in the catalog are always unique. This fixes - . - [timo] -- Fix 'check all' on batch moderation page. - [davisagli] -- Use safe_unicode to decode the title of the content. encode("utf-9") caused - Dexterity based content types to raise a unicode decode error. This fixes - - [dukebody] -- Spanish translation updated. - [dukebody] -- Catalan translation added. - [sneridagh] -- Convert anonymous-supplied name to unicode as done for authenticated members. - [ggozad] -- Catch SMTP exceptions when sending email notifications. - [timo] -- Updated italian translation. - [keul] - -## 1.0b12 (2010-11-04) - -- Remove AJAX comment deletion binding. This function relies on the nextUntil() - selector introduced by jQuery 1.4 and therefore breaks in Plone 3 - (that currently uses jQuery 1.3.2). - [timo] - -## 1.0b11 (2010-11-03) - -- Fix Dutch and Czech language code and name. - [timo] -- Re-add the CommentsViewlet can_manage method. This method has been removed - in version 1.0b9 and added again in 1.0b11 because we don't want to change - the API in beta releases. - [timo] -- Declare z3c.form and zope.schema as minimum version dependencies in setup.py - in case people use a different KGS. - [timo] -- Add and update es and eu l10ns. - [dukebody, on behalf of erral] -- Ajaxify comment deletion and approval. - [thomasdesvenain] -- New feature: As a logged-in user, I can enable/disable email notification of - additional comments on this content object. - [timo] -- Disable the plone.app.registry check on schema elements, so no error is - raised on upgrades. This fixes . - [timo] -- Remove the too generic id attribute of the comment form. - [timo] -- Fixed handling of non-ascii member data, like fullname and email. - [hannosch] - -## 1.0b10 (2010-10-15) - -- Fixed "global name 'WrongCaptchaCode' is not defined" if norobots captcha, - but no other validation package is installed. - [naro] -- Check if there is a 'pending' review state in the current workflow for - comments instead of just checking for the 'comment_review_workflow'. This - allows integrators to use a custom review workflow. This fixes - . - [timo] -- fixed plone-it.po (improper language code ('en' instead of 'it')) - [ajung] - -## 1.0b9 (2010-10-07) - -- Replace the can_manage method with a can_review method that checks the - 'Review comments' permission. This fixes - . - [timo] -- Fix moderation actions (publish, delete) in the moderation view with virtual - hosts. This is a replacement for . - [timo] -- Do not show two "login to add comments" buttons when there are no comments - yet. This fixes . - [timo] - -## 1.0b8 (2010-10-04) - -- Apply the comment viewlet template and styles to the new title-less comments. - This might require integrators to apply their custom templates and styles. - [timo] -- Remove title field from the comment form and replace it with an auto-generated - title ("John Doe on Welcome to Plone"). - [timo] -- Fix : "Comment byline shows login - name, not full name" - [kiorky] -- Make sure the \_\_parent\_\_ pointer (the conversation) of a comment is not - acquisition wrapped in conversation.addComment. This fixes - . - [timo] -- Revert r35608 since this was breaking the comment moderation bulk actions. - The BulkActionsView expects the absolute path of the comments without the - portal url (e.g. '/plone/doc1/++conversation++default/1285346769126020'). - This fixes . - [timo] -- Use "(function(\$) { /\* some code that uses \$ \*/ })(jQuery)" instead of - "\$(document).ready(function(){ /\* some code that uses \$ \*/ });" to invoke - jQuery code. - [timo] -- Finnish translation added. - [saffe] -- Italian translation updated. - [keul] - -## 1.0b7 (2010-09-15) - -- Captcha plugin support for collective.z3cform.norobots (version >= 1.1) added. - [saffe] -- Store dates in utc and not in local time. Display local time - [do3cc] -- Fetch context for the comment view with "context = aq_inner(self.context)". - [timo] -- Raise an unauthorized error when authenticated users try to post a comment - on a content object that has discussion disabled. Thanks to vincentfrentin - for reporting this. - [timo] -- Czech translation added. - [naro] -- Clean up code with PyLint. - [timo] -- Make Javascripts pass JSLint validation. - [timo] -- Put email notification subscribers into their own zcml file so it is easier - for integrators to override them. - [timo] -- Plain text and intelligent text options for comment text added to preserve - basic text structure and to make links clickable. - [timo] -- Rewrote all tal:condition in comments.pt. The authenticated user has - the reply button and the comment form if he has the "Reply to item" - permission And the discussion is currently allowed. - [vincentfretin] - -## 1.0b6 (2010-08-24) - -- Fixed the case where a folder has allow_discussion=False and - conversation.enabled() on a document in this folder returned False - instead of True because of allow_discussion acquisition. - [vincentfretin] -- Redirect to the comment form action instead of the absolute URL when a - comment is posted. This fixes the accidentally triggered file upload when a - comment is posted on a file content object. - [timo] -- We need five:registerPackage to register the i18n folder. - [vincentfretin] -- Added Traditional Chinese (zh_TW) translation. - [TsungWei Hu] -- Added French translation. - [vincentfretin] -- Renamed legend_add_comment to label_add_comment to have the translation from - plone domain. - [vincentfretin] -- label_comment_by and label_commented_at are not in Plone 4 translation - anymore, so these two messages moved to plone.app.discussions i18n domain. - [vincentfretin] -- Translate "Warning" shown in @@moderate-comments in the plone domain. - [vincentfretin] -- Fixed i18n markup of message_moderation_disabled. - [vincentfretin] -- Catch Type errors in indexers if object can not be adapted to IDiscussion - [do3cc] -- Call the CaptchaValidator even when no captcha data was submitted. This is - necessary to ensure that the collective.akismet validator is called when - installed. - [timo] -- Spanish translation added. Thanks to Judith Sanleandro. - [timo] - -## 1.0b5 (2010-07-16) - -- Use self.form instead of CommentForm for the CommentsViewlet update method so - integrators don't have to override the viewlet's update method. - [matous] -- Make sure the form fields in the reply form are always placed under the field - labels. - [timo] -- Fix CSS overflow bug that occurs with the new Plone 4.0b5 comment styles. - [timo] -- Unnecessary imports and variables removed. - [timo] -- Added norwegian translation. - [ggozad] -- Protect against missing canonical in conversationCanonicalAdapterFactory. - [hannosch] -- Documentation for Captcha plugin architecture and email notification added. - See . - [timo] -- Use sphinx.plonetheme for plone.app.discussion documentation. - [timo] -- Avoid deprecation warning for the Globals package. - [hannosch] -- Remove the hard coded check for title and text when the comment form is - submitted. This allows integrators to write schema extenders that remove the - title from the comment form. - [timo] -- Move captcha registration to its own captcha.zcml file. - [timo] -- Akismet () spam protection plugin (collective.akismet) - support added. - [timo] -- Simplify the CaptchaValidator class by dynamically adapting a view with the - name of the captcha plugin (e.g. recaptcha, captcha, akismet) for the - validator. - [timo] -- Dutch translation added. - [kcleong] -- Enable caching and merging for comments.js to save some requests. - [pelle] -- Design notes for the Captcha plugin architecture added. - [timo] -- Make IDiscussionLayer inherit from Interface again. Remove IDefaultPloneLayer, - since Plone 4.0b1 and plone.theme 2.0b1 are out now. - [timo] -- Clean up Javascript code. - [timo] -- Fix encoding error in migration procedure, otherwise migration procedure - breaks on joining output list in case we have there any non-ascii characters. - [piv] -- plone.z3cform 0.6.0 compatibility (fix maximum recursion depth error which - appears with plone.z3cform higher than 0.5.10). - [piv] -- Removed moderation.js from js registry and include it only in moderation.pt as - that is the only place where it is used. - [ggozad] - -## 1.0b4 (2010-04-04) - -- New feature: As a moderator, I am notified when new comments require my - attention. - [timo] -- Sphinx-based developer documentation added. See - . - [timo] -- Rename "Single State Workflow" to "Comment Single State Workflow". - [timo] -- Rename 'publish comment' to 'approve comment'. This fixes #1608470. - [timo] -- Show a warning in the moderation view if the moderation workflow is disabled. - [timo] -- Move 'Moderate comments' link from site actions to user actions. - [timo] -- Fix #662654: As an administrator, I can configure a Collection to show recent - comments. Comment.Type() now correctly returns the FTI title ('Comment') - [chaoflow] -- German translation updated. - [juh] -- Fix #2419342: Fix untranslated published/deleted status messages. - [timo] -- Remove fixed width of the actions column of the moderation view. The - translated button titles can differ in size from the English titles. - [timo] -- Fix #2494228: Remove comments as well when a content object is deleted. - [timo] -- Fix unicode error when non-ASCII characters are typed into the name field of a - comment by anonymous users. - [regebro] -- Make p.a.d. work with the recent version of plone.z3cform (0.5.10) - [timo] -- Make p.a.d. styles less generic. This fixes #10253. - [timo] -- Added greek translation. - [ggozad] -- A bug in the moderator panel meant you couldn't delete items in a virtual - host, if your portal was named "plone". - [regebro] - -## 1.0b3 (2010-01-28) - -- Added an i18n directory for messages in the plone domain and updated scripts - to rebuild and sync it. - [hannosch] -- Added an optional conversationCanonicalAdapterFactory showing how to share - comments across all translations with LinguaPlone, by storing and retrieving - the conversation from the canonical object. - [hannosch] -- Play by the Plone 3.3+ rules and use the INavigationRoot as a base for the - moderation view. - [hannosch] -- Added a commentTitle CSS class to the comment titles. - [hannosch] -- Update message ids to match their real text. - [hannosch] -- Set CSS classes for the comment form in the updateActions method. - [timo] -- Respect the allow_comments field on an object and avoid calculations if no - comments should be shown. - [hannosch] -- Automatically load the ZCML files of the captcha widgets if they are - installed. - [hannosch] -- Fixed i18n domain in GenericSetup profiles to be `plone`. Other values - aren't supported for GS profiles. - [hannosch] -- Provide our own copy of the default one state workflow. Not all Plone sites - have this workflow installed. - [hannosch] -- Register the event subscribers for the correct interfaces in Plone 3. - [hannosch] -- Factored out subscriber declarations into its own ZCML file. - [hannosch] -- Bugfix for #2281226: Moderation View: Comments disappear when hitting the - 'Apply' button without choosing a bulk action. - [timo] -- Allow to show the full text of a comment in the moderation view. - [timo] -- German translation added. - [timo] -- Italian translation added. - [keul] - -## 1.0b2 (2010-01-22) - -- Bugfix for #2010181: The name of a commenter who commented while not logged in - should not appear as a link. - [timo] -- Bugfix for #2010078: Comments that await moderation are visually distinguished - from published comments. - [timo] -- Bugfix for #2010085: Use object_provides instead of portal_type to query the - catalog for comment. - [timo] -- Bugfix for #2010071: p.a.d. works with plone.z3cform 0.5.7 and - plone.app.z3cform 0.4.9 now. - [timo] -- Bugfix for #1513398: Show "anonymous" when name field is empty in comment - form. - [timo] -- Migration view: Dry run option added, abort transaction when something goes - wrong during migration, be more verbose about errors. - [timo] - -## 1.0b1 (2009-12-08) - -- Fix redirect after a adding a comment - [timo] -- Replace yes/no widgets with check boxes in the discussion control panel - [timo] -- Make comments viewlet show up in Plone 4 - [timo] -- Apply Plone 4 styles to comment form - [timo] -- Simplify moderation view by removing the filters - [timo] - -## 1.0a2 (2009-10-18) - -- Plone 4 / Zope 2.12 support - [timo] -- Comment migration script added - [timo] -- Pluggable plone.z3cform comment forms - [timo] -- Captcha and ReCaptcha support added - [timo] - -## 1.0a1 (2009-06-07) - -- Basic commenting functionality and batch moderation. - [timo] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 9fddb8cd..00000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1 +0,0 @@ -Please see diff --git a/README.md b/README.md deleted file mode 100644 index 5ff2c6a4..00000000 --- a/README.md +++ /dev/null @@ -1,43 +0,0 @@ -# Introduction - -plone.app.discussion is the commenting add-on for Plone. -It is part of the maintained Plone core. - -# Installation - -If your installation depends on the [Plone](https://pypi.org/project/Plone/) package, you can install it via the Plone control panel. -In case you do only depend on either the `plone.volto`, `plone.classicui` or `Products.CMFPlone` package, you need to add it to your requirements file. -After adding it and installing the requirement, you can install it via the Plone control panel. - -# Spam protection - -These days it is essential to protect your site from commenting spam. -The following add-ons can help to protect your site: - -- [plone.formwidget.captcha](https://pypi.org/project/plone.formwidget.captcha/) - (for Captcha spam protection) -- [plone.formwidget.recaptcha](https://pypi.org/project/plone.formwidget.recaptcha/) - (for ReCaptcha spam protection) -- [collective.z3cform.norobots](https://pypi.org/project/collective.z3cform.norobots/) - (provides a "human" captcha widget based on a list of questions/answers) -- [plone.formwidget.hcaptcha](https://pypi.org/project/plone.formwidget.hcaptcha/) - (for spam protection by [HCaptcha](https://www.hcaptcha.com/) ) - -# Documentation - -For further information, please refer to the [official Plone documentation](https://docs.plone.org/). - -# Credits - -This package was initially developed as part of the Google Summer of Code 2009 by Timo Stollenwerk (student) and Martin Aspeli (mentor). - -Many thanks to: - -- Jon Stahl (for acting as "the customer" during GSoC) -- David Glick (for technical expertise and advice during GSoC) -- Lennart Regebro (for writing the portal_discussion tool and initial unit tests) -- Carsten Senger (for fixing the comment z3c.form form and pizza) -- Hanno Schlichting (for making p.a.d work with Zope 2.12) -- Alan Hoey (for providing fixes) -- Maik Roeder (for providing and setting up a buildbot) -- Jens Klein (for ripping it out of core and making it a separate core-addon for Plone 6.1)