Magnolia 5.4 reached end of life on November 15, 2018. This branch is no longer supported, see End-of-life policy.

Page tree
Skip to end of metadata
Go to start of metadata

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.

Installing

Maven is the easiest way to install the module. Add the following dependency to your bundle:

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

Pre-built jars are also available for download. See Installing a module for help.

Creating a forum

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.

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.

(warning) 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.

/my-module/templates/pages/forum.yaml
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 nameValue
 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

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.

magnolia-forum.css
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;
}

 If you use a site definition, you can link to the CSS in your theme.

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

forum-page-script.ftl
[#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).

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.

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.

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.

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.

Node nameValue

 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. (warning) Model classes reside in the info.magnolia.module.forum.frontend.action package.

ComponentDescriptionallowedParametersmodelClasstemplateScript
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
-

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

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

Node nameValue

 forum

 

 thread-list

 

 thread-view

 

 thread-new

 

 main

 

 0

 

 threadListPage

ba8bbea6-bc03-4bcd-9d33-5cc73783345b

 title

Tech Forums

 title

Forum

Setting forum options

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

Node nameValue

 modules

 

 forum

 

 config

 

 createRolesForNewForums

true

 displayedCharactersInForumTree

50

 messageNamePattern

yyyy-MM-dd-HH-mm-0 

 messagesPerPage

50

 repository

forum

 showingUnvalidatedMessages

true

Properties:

repository

required, default is forum

Workspace used to store forum data.

createRolesForNewForums

optional, default is true

Automatically create user role for each forum. See Automatic role creation.

displayedCharactersInForumTree

optional, default is 50

Number of characters displayed in Content column of the Forum app. Messages are displayed in this column.

messageNamePattern

optional, default is yyyy-MM-dd-HH-mm-0

Date pattern used to generate message node names.

messagesPerPage

optional, default is 50

Maximum number of messages per page.

showingUnvalidatedMessages

optional, default is true

Whether new messages display immediately or after moderation.

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.

Node nameValue

 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

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

WorkspacePermissionScopePath
ForumRead/WriteSelected and sub nodes/

Web access

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

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.

 

WorkspacePermissionScopePath
ForumRead/WriteSelected 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.

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.

Node nameValue

 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, editForumdeleteForum and confirmDeleteForum actions.

Node nameValue

 apps

 

 forum

 

 subapps

 

 browser

 

 actions

 

 addForum

 

 availability

 

 access

 

 roles

 

 forum_ALL-admin

forum_ALL-admin

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.

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.

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:

Best practice

  1. 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. Publish pages and templating changes to public instance.
  2. Public instance:
    1. Set up your forums and initial threads and messages in the Forum app. Forum-specific roles will be created automatically in the Security app.
    2. Set anonymous, moderation and administration permissions. You can use the default roles and/or automatically created user roles.
    3. Exclude the forum pages from caching while you test your permissions. You can also flush the cache in the Cache tools app.
    4. Test your pages.