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.

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.

Installing

<dependency>
  <groupId>info.magnolia</groupId>
  <artifactId>magnolia-module-forum</artifactId>
  <version>3.5</version>
</dependency>

• magnolia-module-forum.jar

Creating a forum

Set up forums in the Forum app

The Forum app allows you to create and moderate forums. 

Creating forums

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.

Create as many forums as you like. All forums render in the components but this can be controlled throught permissions.

Creating threads

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:

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

A thread requires at least one message.

This is how the forum content displays:

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

Moderating

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

Create a forum page template

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.

Make components available

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

Add CSS

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.

table.threadList, table.forumList {
    border-collapse: collapse;
    margin: 0;
    padding: 0;
}

table.threadList td,
table.threadList th,
table.forumList td,
table.forumList th {
    padding: 2px 1em;
    text-align: left;
}

table.threadList td,
table.forumList td {
    border: 1px solid #666666;
}

table.forumList .lastMessageCreationDate,
table.threadList .lastMessageCreationDate,
table.threadList .firstMessageCreationDate {
    display:block;
}

tr.forum-odd, tr.thread-odd {
    background-color: #c4c4c4;
}

tr.forum-even, tr.thread-even {
    background-color: #f6f6f6;
}

ul.messages {
    margin: 0;
    padding: 0;
    list-style: none;
}

ul.messages li.message {
    margin: 0 0 0.5em 0;
    padding: 0;
    border: 1px solid #666666;
}

ul.messages li.message-odd {
    background-color: #f6f6f6;
}

ul.messages li.message-even {
    background-color: #f6f6f6;
}

ul.messages li h5 {
    margin: 0;
    padding: 0.5em 0.5em 0.5em 0.5em;
    color: #666666;
    font-size: 110%;
}

ul.messages li p.messageContent {
    margin: 0;
    padding: 0 0.5em 2em 0.5em;
}

ul.messageMeta {
    margin: 1px;
    padding: 0 0.5em 3px 0.5em;
    list-style: none;
    background-color: #e0e0e0;
    /* fixing IE issues */
    overflow: auto;
    _height: 1%;
}

ul.messageMeta li {
/*font-style: italic;*/
    display: inline;
}

ul.messageMeta li.messageAuthor {
    font-weight: bold;
}

ul.messageMeta span.messageAnonymousPost {
    color: #666666;
    font-weight: normal;
    font-style: italic;
}

ul.messageMeta li.messageCreationDate {
    float: right;
}

ul.messageMeta li.messageUUID {
    display: none;
}

/* form */
form.forum-form {
    margin: 0;
    padding: 1em 0 0 0;
    border: 1px solid #666666;
    font-size: 100%;
    background-color: #e0e0e0;
}

.forum-form fieldset {
    margin: 0;
    padding: 0;
    border: none;
}

.forum-form label {
    font-size: 100%;
    width: 6em;
    display: block;
    float: left;
    text-align: right;
    margin: 0;
    padding: 0 5px;
}

.forum-form input, .forum-form select, .forum-form textarea {
    font-family: Tahoma, Arial, sans-serif;
    font-size: 100%;
    margin: 0 0 1em 0;
    padding: 0;
    width: 30em;
}

.forum-form textarea {
    overflow: auto;
    height: 10em;
}

.forum-form button-wrapper {
    margin-left: 7em;
}

.forum-form fieldset.buttons input {
    padding: 0 1.5em;
    width: auto;
}

.forum.warning {
    font-style: italic;
    color: Maroon;
}

div.pageLinks {
    margin: 0 0 5em 0;
    padding: 3px 0.5em 3px 0.5em;
    border: 1px solid #666666;
    font-size: 100%;
    background-color: #e0e0e0;
}

div.pageLinks * {
    display:inline;
}

div.pageLinks p {
    font-weight: bold;
}

ul.pageLinks {
    margin: 0;
    padding: 0;
}

Create a page script

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 forum pages

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.

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

    

Link forum components

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.
  

Example: Content added in the app on the forum pages.

Creating 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" 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:

1. Make the threadList and threadView components available in any area of a non-forum template.
2. Link to the forum styles in the template script.
3. To create a fixed forum:
   1. Add the threadList component to a page. 
   2. 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.
      
      
4. To create a fixed thread:
   1. Add the threadView component to a page
   2. Select the thread in the Fixed thread field.
      
      
      
      

Forum components

The Forum component and dialog definitions are in /modules/forum/templates/components and /dialogs.

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.

Data storage

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. 

Setting forum options

The config node of the the module configuration provides a number of global options that apply to all forums.

Properties:

Commands

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.

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

Security

You can control access to the Forum app as well as public access to forums.

Default roles

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

Web access

The admin and moderator roles are used to control access to the Forum app. The user role is for setting anonymous forum access.

Automatic role creation

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.

 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.

App permissions

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.

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.

Setting anonymous permissions

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:

• Provide full forum access to public users by assigning the forum_ALL-user role to anonymous.
• Provide full access to specific forums only, by assigning the automatic user roles individually to anonymous. You can use this method to hide the pagecomments forum.
• Allow public users to view, but not post, on forum pages, by changing the permissions of the forum_ALL-user role to Read only and assigning it to anonymous. Use the Public User Registration module to register new users.

Best practices for creating 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 permissions 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: