Magnolia 5.4 reached end of life on November 15, 2018. This branch is no longer supported, see End-of-life policy.
In Magnolia CORE 5.5+ the functions of this module cannot be used anymore. The module remains present in the bundles but its function is taken over by the commenting
module.
The Forum module allows you to add a discussion forum to your site. The module includes all resources necessary to manage forums, threads and messages.
Forums are managed in the Forum app and components display forum content on pages. You can choose where the components should be placed and integrate them into content pages, deciding how each page relates to other pages. Data is stored in the JCR.
Magnolia Community Forums are powered by this module.
Forum content is user generated and your forums should ideally be created and moderated on the public instance. You can activate forums if you prefer to work initially on the author instance. See Best practice for creating forums for more information.
The Forum app allows you to create and moderate forums.
To create a forum:
Create as many forums as you like. All forums render in the components but this can be controlled throught permissions.
Once you have created forums, create threads to get the conversation started. The components allow users to create new threads and post messages on pages.
To create a thread:
A thread requires at least one message.
This is how the forum content displays:
In the Moderation subapp you can edit, delete, approve, reject and reply to messages. Changes made in the app display in the components.
The module provides ready-to-use components that you can add to any page template template. There is also a CSS sheet to get you started.
Create a new page definition and make the forum components available in any area. Alternatively, add the components to an area of an existing template.
Example: Making components available in main
area of a new template.
templateScript: /my-module/templates/pages/forum-page-template.ftl renderType: freemarker visible: true title: Forum Template dialog: my-module:pages/properties areas: main: availableComponents: forumList: id: forum:components/forumList threadNew: id: forum:components/threadNew threadView: id: forum:components/threadView threadList: id: forum:components/threadList threadReply: id: forum:components/threadReply
Node name | Value |
---|---|
my-module | |
templates | |
pages | |
forum | |
areas | |
availableComponents | |
forumList | |
id | forum:components/forumList |
threadNew | |
id | forum:components/threadNew |
threadView | |
id | forum:components/threadView |
threadList | |
id | forum:components/threadList |
threadReply | |
id | forum:components/threadReply |
dialog | my-module:pages/properties |
renderType | freemarker |
templateScript | /my-module/templates/pages/forum-page-template.ftl |
title | Forum Template |
templateScript | /my-module/templates/pages/home.ftl |
visible | true |
The module provides a CSS sheet, magnolia-forum.css
(Git), that you can use as a guide to style forum components. The sheet is on the classpath in /src/main/resources/mgnl-resources/forum/magnolia-forum.css
.
Save the styles to your preferred resource location. If you are working in a light module, save the styles on the file system in the folder in which you store template resources.
If you use a site definition, you can link to the CSS in your theme.
Create a new page script to render the components or add the area where you made the components available to an existing script, and link to the CSS sheet.
Example: Simple new page script
[#assign title = content.title!] <!DOCTYPE html> <html> <head> <title>${title}</title> <link rel="stylesheet" href="${ctx.contextPath}/.resources/my-module/webresources/css/my-sheet.css"> <link rel="stylesheet" href="${ctx.contextPath}/.resources/my-module/webresources/css/forum-module-styles.css"> [@cms.page /] </head> <body> <div class="container"> <div class="main"> [@cms.area name="main"/] </div> </div> </body> </html>
Add pages based on the new forum template.
The components, and the links between them, provide forum functionality, and the page structure is basically irrelevant.
A typical forum page structure looks like this.
forumList
component).threadList
component).threadView
component).threadNew
component).You can use a combination of page components on a single page. For example you can have forumList
and threadList
on the same page. The treadList
component will not display until the user clicks a link in the forumList
component, then it renders below it.
To function correctly the forumList
, threadList
and threadView
components need to be linked internally. Link fields are available in the component dialogs for this. Linking is done by linking to the page on which the target component resides.
forumList
links to the page on which the threadList
component resides.threadList
links to the pages on which the threadView
, and optionally the threadNew
, components reside.threadNew
links to the page on which the threadView
component resides.The threadView
dialog has a link field for a Thread reply page. This option can be used if the threadReply
component resides on it's own page. As the reply form forms part of the threadView
component this is seldom necessary.
Example: Content added in the app on the forum pages.
The forum components have their own navigation. User navigation determines which forum threads are displayed on the page. The links that display in the components point to the appropriate target content. For this reason it is best to hide all pages, except the main forum page, from the site navigation.
Fixed forums allow you to display a single forum or thread anywhere on the site outside of the standard "forum > thread > message" pattern. Here the process begins with the threadList
component. Fixed threads additionally exclude the threadList
component and only the threadView
component is displayed.
Use fixed forums and threads to associate a discussion with related content on the site. For example, you could display a baseball forum in the sports section, or a thread about a current event next to a related news article. When visitors post new messages or threads on the page, both the forum components on standard forum pages and these components are updated with the new content.
To create a fixed forum or thread:
threadList
and threadView
components available in any area of a non-forum template.threadList
component to a page. threadNew
and threadView
pages, i.e. pages that these components reside on. You can use the pages that your actual form uses. threadView
component to a pageThe Forum component and dialog definitions are in /modules/forum/templates/components
and /dialogs
.
Node name | Value |
---|---|
forum | |
templates | |
components | |
forumList | |
threadList | |
allowedParameters | forumId |
description | paragraph.threadList.description |
dialog | forum:threadList |
i18nBasename | info.magnolia.module.forum.messages |
modelClass | info.magnolia.module.forum.frontend.action.ThreadList |
renderType | freemarker |
templateScript | /info/magnolia/module/forum/frontend/thread-list.html |
title | paragraph.threadList.title |
threadView | |
threadNew | |
threadReply |
Each component has its own model class to provide business logic for the interlinked components. All components, except forumList
have an additional, non-standard property, allowedParameters
. This property is made available by the model classes and used by the scripts to render the correct target content. Scripts (GIT) are written in HTML. Model classes reside in the
info.magnolia.module.forum.frontend.action
package.
Component | Description | allowedParameters | modelClass | templateScript |
forumList |
| - | ForumList | forum-list.html |
threadList |
|
| ThreadList | thread-list.html |
threadView |
|
| ThreadView | thread-view.html |
threadNew |
| forumId | ThreadNew | thread-new.html |
threadReply |
|
| ThreadReply | thread-reply.html |
Forum data is stored in the forum
workspace. Only the UUIDs to the pages that the components reside on is stored in the website
workspace. You can verify this in the JCR browser.
Node name | Value |
---|---|
forum | |
thread-list | |
thread-view | |
thread-new | |
main | |
0 | |
threadListPage | ba8bbea6-bc03-4bcd-9d33-5cc73783345b |
title | Tech Forums |
title | Forum |
The config
node of the the module configuration provides a number of global options that apply to all forums.
Node name | Value |
---|---|
modules | |
forum | |
config | |
createRolesForNewForums | true |
displayedCharactersInForumTree | 50 |
messageNamePattern | yyyy-MM-dd-HH-mm-0 |
messagesPerPage | 50 |
repository | forum |
showingUnvalidatedMessages | true |
Properties:
| required, default is Workspace used to store forum data. |
| optional, default is Automatically create user role for each forum. See Automatic role creation. |
| optional, default is Number of characters displayed in Content column of the Forum app. Messages are displayed in this column. |
| optional, default is Date pattern used to generate message node names. |
| optional, default is Maximum number of messages per page. |
| optional, default is Whether new messages display immediately or after moderation. |
The module includes a number of custom commands that are used for actions in the Forum app.
Commands are configured in /modules/forum/commands/forum
.
Node name | Value |
---|---|
forum | |
commands | |
forum | |
activate | |
lockForum | |
lockThread | |
deleteForum | |
unlockForum | |
unlockThread | |
deleteThread | |
deleteMessage | |
validateMessage | |
invalidateMessage |
Class names:
info.magnolia.module.activation.commands.ActivationCommand
(included in forum
catalog for specific itemTypes
: mgnl:message
, mgnl:thread
)info.magnolia.module.forum.admin.command.LockForumCommand
info.magnolia.module.forum.admin.command.LockThreadCommand
info.magnolia.module.forum.admin.command.DeleteForumCommand
info.magnolia.module.forum.admin.command.UnlockForumCommand
info.magnolia.module.forum.admin.command.UnlockThreadCommand
info.magnolia.module.forum.admin.command.DeleteThreadCommand
info.magnolia.module.forum.admin.command.DeleteMessageCommand
info.magnolia.module.forum.admin.command.ValidateMessageCommand
info.magnolia.module.forum.admin.command.InvalidateMessageCommand
You can control access to the Forum app as well as public access to forums.
The module installs three default roles in the Security app: forum_All-user
, forum_All-admin
and forum_All-moderator
. The roles have identical permissions but are used for different purposes.
Access control lists
Workspace | Permission | Scope | Path |
Forum | Read/Write | Selected and sub nodes | / |
Web access
Permission | Path |
Get & Post | /.magnolia/pages/forum* |
The admin and moderator roles are used to control access to the Forum app. The user role is for setting anonymous forum access.
If the createRolesForNewForums
configuration property is set to true
, user roles are created automatically in the Security app for each forum set up in the Forum app. The format of the automatic roles is forum-<forum name>-user
.
Workspace | Permission | Scope | Path |
Forum | Read/Write | Selected and sub nodes | /<forum name> |
Use these roles to set anonymous access to specific forums on the public instance. For example you can give public users (anonymous
) access to all forums except the pagecomments
forum.
Access to the Forum app is limited to users assigned the forum_All-admin
and forum_All-moderator
roles. Only superuser
is assigned the forum_All-admin role
.
App permissions are configured in /modules/forum/apps/forum/permissions/roles
.
Node name | Value |
---|---|
forum | |
apps | |
forum | |
permissions | |
roles | |
forum_ALL-admin | forum_ALL-admin |
forum_ALL-moderator | forum_ALL-moderator |
In the Forum app, only users assigned the forum_ALL-admin role
(superuser
by default) can create, edit and delete forums. This is controlled by limiting access to actions.
Action permissions are configured in /modules/forum/apps/forum/subapps/browser/actions/<action name>/availability/access/roles
. There are identical configurations for the addForum
, editForum
, deleteForum
and confirmDeleteForum
actions.
Node name | Value |
---|---|
apps | |
forum | |
subapps | |
browser | |
actions | |
addForum | |
availability | |
access | |
roles | |
forum_ALL-admin | forum_ALL-admin |
The purpose of the default and automatically created user roles is to set anonymous permissions on the public forum. The roles give Read/Write
access.
Most Internet forums require registration to post, but anonymous forums do have benefits.
Here are a few scenarios:
forum_ALL-user
role to anonymous
.anonymous
. You can use this method to hide the pagecomments
forum.forum_ALL-user
role to Read only
and assigning it to anonymous
. Use the Public User Registration module to register new users.If you need both page commenting and forums and still want to hide the Page Comments forum from the forum list, customize the forum-list.html
(Git) template script and/or
ForumList
model class.
Here's the rationale behind our recommended procedure for creating forums:
Here's our recommended procedure for creating forums: