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 Forum app 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 that includes the Forum template. 

Magnolia Community Forums are powered by this module.

Download

The Forum module is bundled with Magnolia and typically already installed. You can download it from our Nexus repository

Installing

Forum is a Community Edition module and typically already installed. Launch the Configuration app and go to /modules/forum to check.

Uninstalling

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 of the Forum app. 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 are used in the Forum app to execute the necessary actions. Commands are configured in /modules/forum/commands/forum.

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

Forum app

The Forum app allows you to create and moderate forums. The app is accessible in Edit > 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 information.

There are two subapps:

• Forum: 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:

1. Click Add forum.
2. Provide a title, short name (internal name) and optionally select the Allow nesting messages option.
3. Save.

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

Creating threads

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

To create a thread:

1. Click Add thread.
2. Provide a thread title, message title and text.
3. Save.

A thread requires at least one message.

The forum content displays as follows:

• <forum name> <forum title>
  
  • <thread name> <thread title>
    
    • <message date> <message title> <message text>

Once a thread has been created you can edit, delete, lock, publish and unpublish it.

Moderation

In the Moderation subapp you can edit, delete, approve, reject and reply to messages. Changes made in the app render in the components.

Forum pages

The Forum template makes the forum components available. Each page uses the appropriate component in content area to render the correct content from the Forum app. 

Forums typically require four pages:

• Forum page displays a list of all forums created in the app (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 are the pages for the example forum 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 the app rendered on the demo-features/modules/forum page and subpages.

Forum template

The module adds the stkForum template to the STK. The template is configured at STK > Template Definitions /pages/stkForum:

• 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.

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

Components

Forum module components

The Forum module component definitions are configured at Configuration > /modules/forum/templates/components. All components, except ForumList have an additional, non-standard property, allowedParameters, that 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 all extend AbstractThreadAction. The scripts are written in HTML and you can view them in GIT.


The module also adds a forum login component to the STK that allows registered users to login. By default anonymous users cannot see the forum content, post messages or create threads. See Security for more information.

The login component is configured at STK > Template Definitions /components/forum/stkForumLoginForm. The component extends the stkPURLoginForm component but uses its own script, login.ftl that you can access at STK > Templates /components/forum/login.ftl.

Adding components

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 display a warning message 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 by the Forum module. 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 at Configuration > /modules/forum/dialogs. The names of the component and dialog definitions that are used on pages correspond. The other dialog definitions are used by the app. 

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:

1. Add the threadList and threadView components to content area of the page template. The example configuration adds the components to the stkSection template configured at STK > Template Definitions > /pages/stkSection.

   Node name	Value
   pages
   stkSection
   areas
   main
   floating
   areas
   content
   availableComponents
   threadList
   id	forum:components/threadList
   threadView
   id	forum:components/threadView

2. Add the CSS to the template. You can duplicate and move 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.

   Node name	Value
   pages
   stkSection
   areas
   cssFiles
   farFutureCaching	true
   link	/.resources/forum/magnolia-forum-stk.css
   media	only screen and (min-width: 481px)

3. 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 that these components reside on. 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. In this way it will be available on all templates that use the forum components. The following configuration at STK > Themes > /pop/cssFiles/forum adds magnolia-forum-stk.css to the pop theme.

Security

Default roles

The module installs three default roles in the Security app, forum_All-user, forum_All-admin and forum_All-moderator.These roles have identical permissions 

Access control lists

Web access

The forum_All-admin and forum_All-moderator roles are used in the app configuration to differentiate user permissions. The forum_All-user role is not assigned to any user and grants permission to view and post on all forums.

Default users

In the Security app the default users have the following forum permissions:

• Systems users (author and public):
  
  • superuser: Full Read/Write permissions to forum workspace (superuser role) and the forum_All-admin role. superuser can do everything.
  • anonymous:  No ACL permissions to the forum workspace (anonymous role) and none of the default roles mentioned above. anonymous can do nothing.  anonymous is assigned the forum-pagecomments-user role that allows public users to view and post comments. See Automatic roles below.
• Users (author and public):
  
  • eric: forum_All-admin role. Eric (Example Editor) has full access to the Forum app (administration and moderation).
  • peter: forum_All-moderator role. Peter (Example Publisher) can access the Forum app, read content in the browser subapp, and do everything in the moderation subapp.

Automatic role creation for new forums

If the createRolesForNewForums configuration property is set to true, a user role is created automatically for each forum created in the Forum app.

You can use these roles to grant and deny 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. See Setting anonymous permissions below.

App permissions

Access to the Forum app is configured at Configuration > /modules/forum/apps/forum/permissions/roles. See App permissions for more information. Access is limited to users assigned the forum_All-admin and forum_All-moderator roles, by default superuser, eric and peter.

Permission to actions in the browser subapp is limited to users with the forum_All-admin role. This restricts peter's access in the app. He can view, publish and unpublish forums, but cannot edit and create them. Action permissions in the browser subapp are configured at Configuration > /modules/apps/forum/subapps/browser/actions/<action name>/availability/access/roles. Here's the configuration for the addForum action. You will find similar configurations for the deleteForum, confirmDeleteForum and editForum actions.

Setting anonymous permissions

Nearly all internet forums require registration to post, but anonymous forums do have some benefits. In the Security app you can define suitable access permissions for public forum users.

The scenarios below ignore the pagecomments forum. The forum-pagecomments-user role is not granted to the anonymous systems user.

Here are a few scenarios:

• To grant full forum access to public users, assign the forum_ALL-user role to anonymous. Here's what a public user with full access and with no access sees on the main forum page.
   
• To grant full access to specific forums only, assign the automatic user roles individually to anonymous. You can use this method to hide the pagecomments forum. Here's what a public user sees on the main forum page with all automatic roles, except forum-pagecomments-user and forum-webdevelopment-user, assigned to anonymous.
  
• To grant permission to view, but not post, on forum pages, change the permissions of the forum_ALL-user role to Read only, assign it to anonymous and use the functionality of the Public User Registration module to register new users.
  
  

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 anonymous are different on author and public.
• Page creation belongs on the author instance:
  • Templates, pages and components are best managed on the author instance.

Here's our recommended procedure for creating forums: