Forum 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 in Magnolia.

Forums are managed in the AdminCentral in Forums and components are used to render 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. The forum can be used independently or with the STK.

Magnolia Community Forums are powered by this module.

Download

Download the Forum module from Magnolia Store or Nexus repository.

Installing

Forum is a community module and typically already installed. Go to Magnolia Store > Installed modules in AdminCentral to check. To install the module individually, see the general module installation instructions.

Uninstalling

See the general module uninstalling instructions and advice.

Configuration

The Forum module is ready to use and configured in modules/forum. In the /config node you can set options applicable to all forums. These properties are supported by the ForumConfiguration class.

Properties:

createRolesForNewForums: Creates a user role for each forum. Default: true.
displayedCharactersInForumTree: Number of characters displayed in Content column in Forums. Messages are displayed in this column. Default: 50.
messageNamePattern: Date pattern used to generate message node names. Default: yyyy-MM-dd-HH-mm-0.
messagesPerPage: Maximum number of messages per page. Default: 50.
repository: Workspace used to store forum data. Default: forum.
showingUnvalidatedMessages: Whether new messages display immediately or after moderation. Default: true.

Commands

The module includes a number of custom commands that execute the actions in Forums. Commands are configured in /modules/forum/commands/forum.

Class names:

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

Forums

Forums allows you to create and moderate forums. 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.

There are two work areas:

Forums: To administer forums, threads and message nodes.
Moderation: To moderate messages.

Creating forums

You can create as many forums as you like. All forums render in the components but this can be controlled by setting permissions.

To create a forum:

Click New Forum.
Provide a title, short name (internal name) and optionally select the Allow nesting messages option.
Save.

Once a forum has been created you can add threads and edit, delete, lock, activate and deactivate forums and threads.

Creating threads

Once you have created a forum you can create any number of threads to get things started. The components allow users to create new threads and post messages on pages.

To create a thread:

Click New Thread
Provide a title
Save.

Threads require at least one message. Messages are also useful to get the conversation going. When you create a thread, a message child node is created automatically. Select it and click Edit to enter message content.

The forum content displays as follows:

<forum title>
- <thread title>
  - <message title> <message text>

Once a thread has been created you can edit, delete, lock, activate and deactivate it.

Forum pages

The forum components components provided by the module are not available in the STK by default. You can download configurations.zip that includes all configuration examples used in this document. The zip includes the stkForum page template, stkForumLoginForm component template and script, and the template availability configuration. Import these configuration to replicate the examples.

The content in Forums is rendered by the forum components. Each page uses the appropriate component in content area to render the correct content.

Forums typically require four pages.

Forum page displays a list of all forums created in Forums (forumList component).
- Thread list page displays a list of all threads in a forum. (threadList component).
- Thread view page displays all messages in a thread (threadView component).
- Thread new page allows users to create new threads (threadNew component).

Here's an example page structure at /demo-features/modules/forum.

To function correctly the forumList, threadList and threadView components need to be linked internally. Fields are available in the dialogs for this purpose. 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.

Here's the content we added in Forums rendered on the demo-features/modules/forum page and subpages.

The forum components have their own navigation. User navigation determines which forum threads are displayed on the page. The links that render automatically 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.

Forum template

Here are the relevant configurations in the stkForum template used in our examples. Download configurations.zip to use this template.

The template is configured in STK > Template Definitions /pages/stkForum:

In main area:
- The forumList, threadList, threadView, threadNew and threadReply components are made available in content area.
- comments area is disabled.

stkForumLoginForm component is made available in extras1 area.

Component-specific CSS is added in the /cssFiles/forum-css node. You can view magnolia-forum-stk.css in GIT.

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.

Here's the /demo-features/modules/forum page with dummy content.

Components

Forum module components

The Forum module component definitions are configured in /modules/forum/templates/components.

All components, except ForumList have an additional, non-standard property, allowedParameters. This property is made available by the model class and used by the scripts to render the correct target content. Each component has it's own model class and template script (see table below).

Model classes reside in the info.magnolia.module.forum.frontend.action package. With the exception of forumList they extend AbstractThreadAction. The scripts are written in HTML and you can view them in GIT.

Component	Description	allowedParameters	modelClass	templateScript
`forumList`	Renders a list of all forums in a table with columns for: Forum: Name of form Last Message: `lastMessageAuthor` and date Threads: Number of threads Status: null or locked Renders alternative text if user does not have required permissions	none	ForumList	`forum-list.html`
`threadList`	Renders a list of all threads in a selected forum in a table with columns for: Subject: Thread title Author: `firstMessageAuthor` and date Last Message: `lastMessageAuthor` and date Replies: Number of messages Status: null or locked Adds a link to the `threadNew` page. Renders alternative text if user does not have required permissions	`threadId` `page`	ThreadList	`thread-list.html`
`threadView`	Renders all messages in a thread as a `ContentMapList` in ascending order. Renders message title, text, author and date for each message. Assigns a `replyLinkUrl` to each message. Uses JavaScript to hide the message title field if a user clicks "Reply to this link" in a message. Includes the `form.inc.html` script that renders the Reply to form..	`threadId` `page`	ThreadView	`thread-view.html`
`threadNew`	Renders a form that allows users to create a new thread. Form includes title and message fields. A link to the page that this component resides on is rendered automatically at the bottom `threadList` component.	`forumId`	ThreadNew	`thread-new.html`
`threadReply`	Renders a form that allows a user to reply to a message. This component renders automatically at the bottom of the `threadView` component. It is typically not used as a stand-alone component.	`threadId` `inReplyTo`	ThreadReply	`thread-reply.html`

STK Login Form component

The STK Login Form component is an STK component that allows registered users to log in to forums. The component definition and script are included in the configurations.zip download.

By default anonymous users cannot see the forum content, post messages or create threads. See Security for more information.

Here's the component definition in Templating Kit > Template Definitions /components/forum/stkForumLoginForm. The component extends the stkPURLoginForm component but uses its own script, login.ftl. Import the script XML into Templating Kit > Templates /components/forum/login.ftl.

Adding components to pages

The components are interlinked and have their own navigational structure.

When you add the components to pages:

The ForumList component displays the forum content.

The threadList and threadView components throw a Template Error because they can only render the content of a selected forum or thread . Navigate from the forumList component in preview mode to see the content. The warning messages are displayed only to developers during the initial setup of the components. The visitor who uses the forum will see no errors.

Website data storage

Component content is rendered from the forum workspace. In the website workspace the only stored properties are UUIDs to the pages that the different components reside on. Here's a test page we created, with both the forumList and threadList components in content area in the website JCR browser, accessible in Tools > JCR.

Dialogs

Dialog definitions are configured in /modules/forum/dialogs. The names of the component and dialog definitions that are used on pages correspond.

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. The reply form forms part of the threadView component, so this is seldom necessary.

Fixed forums and threads

Fixed forums allow you to display a single forum or thread anywhere on the site outside of the standard "forum > thread > message" structure. 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 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

Here's the procedure to create a fixed forum or fixed thread on non-forum pages:

Add the threadList and threadView components to content area of the page template. The example configuration adds the components to the stkSection template configured in Templating Kit > Template Definitions > /pages/stkSection.
Add the CSS to the template. You can copy the cssFiles node in the stkForum template. The example configuration adds magnolia-forum-stk.css to the stkSection template. See Adding theme CSS for an alternative method.
Add the components to a page.
1. For fixed forums add the threadList component, select the forum in the Fixed forum field, and link to valid threadNew and threadView pages, i.e. pages on which these components reside. You can use the pages that your actual form uses. Here's the component and dialog on the /demo-project/news-and-events page.
2. For fixed threads add threadView component and select the thread in the Fixed thread field. Here's the component and dialog on the /demo-project/news-and-events page.

Adding theme CSS

If you use the forum components on multiple templates you can add the forum-specific CSS sheet at a theme level, instead of a page template level. This way it will be available on all templates that use the forum components. The following configuration in Templating Kit > Themes > /pop/cssFiles/forum adds magnolia-forum-stk.css to the pop theme.

Security

See Security for more information.

Default roles

The Forum module installs four forum roles in the Security > Roles. These roles have the following permissions:

Role	Workspace	Permission	Scope	Path
All	URL	Get & Post	n/a	`/.magnolia/pages/forum*`
`forum-base`	Forum	Read only	Selected and sub nodes	`/`
`forum_All-user`	Forum	Post/Write	Selected and sub nodes	`/`
`forum_All-moderator`	Forum	Moderate and Delete	Selected and sub nodes	`/`
`forum_All-admin`	Forum	Administer (Moderate, Delete and Activate)	Selected and sub nodes	`/`

Besides superuser who is assigned the forum_All-admin role, these roles are not assigned to any user.

The default roles do not provide access to the Forums menu. Grant the following permission to provide access.

Workspace	Permission	Scope	Path
Config	Read only	Selected and sub nodes	`/modules/adminInterface/config/menu/forum`

Automatic role creation for new forums

If the createRolesForNewForums configuration property is set to true, a user, moderator and administer role is created automatically for each forum you create.

Setting anonymous permissions

Nearly all internet forums require registration to post, but anonymous forums do have benefits.

Anonymous public users cannot view forums by default, because the anonymous role does not have permissions to read the forum workspace. You can verify this by logging out of the public instance. This is what the public user sees.

To allow public users to:

View, but not post, on forum pages, assign the forum-base role to the anonymous user on the public instance. You can use the functionality of the Public User Registration module to register new users.
View and post, assign the forum_All-user role to the anonymous user.

You can use the automatically created roles to provide Post(Write) permissions to individual forums. Use these if you want to provide selective access to individual forums.

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 the ForumList model class.

Best practice for creating your forums

Here's the rationale behind our recommended procedure for creating forums:

Forum creation, administration and moderation belongs on the public instance.
- This is where the majority of the content will be generated.
- While you can publish forums and their content, after the initial publication, activation tends to be problematic because nodes may have been changed on public.
- You cannot easily import user generated content from public to author to manage it.
- Default permission for the anonymous user are different on author and public.
Page creation belongs on the author instance:
- Templates, pages and components are best managed on the author instance.

Best practice forum creation procedure:

Author instance:
1. Set up simple dummy forums on the author instance to test your pages and components.
2. Make any desired changes to templates, themes etc.
3. Create your pages and add forum components.
4. Test your pages.
5. Activate pages and templating changes to public instance.
Public instance:
1. Set up your forums and initial threads and messages in Forums. Forum-specific roles will be created automatically in Security.
2. Set anonymous, moderation and administration permissions. You can use the default roles and/or automatic user roles.
3. Exclude the forum pages from caching while you test your permissions. You can also flush the cache in the Tools > Cache tools.
4. Test your pages.

Page tree