Magnolia 5.3 reached end of life on June 30, 2017. This branch is no longer supported, see End-of-life policy.

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

The Forum module installs the Forum app that allows you to create your forums.

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.

 Click for installation steps...

(warning) Create a backup of your system before you install a module. Uninstalling a module is not as simple as removing the .jar file. Modules add and change configurations and may change the content. Try new modules in a test environment first. A module consists of a JAR file and may include dependent JAR files. Modules are responsible for updating their own content and configurations across versions. Be sure to keep only one version of each module and its dependencies.

To install a module:

  1. Stop the application server.
  2. Copy the module JAR files into the WEB-INF/lib directory. The location of this directory depends on the application server.
    • Tomcat: /webapps/magnoliaAuthor/WEB-INF/lib
    • JBoss: /server/default/deploy/magnoliaAuthor/WEB-INF/lib
  3. Restart the server.
  4. Go to the AdminCentral URL.
  5. Start the Web update process.
  6. Click Start up Magnolia.

Repeat the steps for each author and public instance.

Uninstalling

 Click for uninstallation steps...

To uninstall a module, remove the module JAR file from the /WEB-INF/lib folder and restart Magnolia.

(warning) However, this is rarely enough. Modules add and modify configuration during installation. The use of a module also changes content. Removing all of these changes is difficult without knowing the installation tasks in detail.

To test a module, use the embedded Derby database and take a backup of your repositories folder. Install the module and try it. When you are done testing, remove the module JAR and restore the repositories folder from the backup. This way you can go back to square one.

We also recommend that you segregate the development and production environments. Take regular backups for disaster recovery so you can revert to a prior state in a routine fashion.

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.

Node nameValue

 modules

 

 forum

 

 config

 

 createRolesForNewForums

true

 displayedCharactersInForumTree

50

 messageNamePattern

yyyy-MM-dd-HH-mm-0 

 messagesPerPage

50

 repository

forum

 showingUnvalidatedMessages

true

 pages

 

 apps

 

 dialogs

 

 commands

 

 templates

 

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.

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

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.

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

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

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.
Node nameValue

 pages

 

 stkForum

 

 areas

 

 main

 

 areas

 

 content

 

 availableComponents

 

 forumList

 

 id

forum:components/forumList

 threadList

 

 threadView

 

 threadNew

 

 threadReply

 

 stkTextImage

 

 comments

 

 enabled

false

 intro

 

......

 

 extras

 

 areas

 

 extras1

 

 availableComponents

 

 stkForumLoginForm

 

 stkExtrasDownloadFile

 

 ....

 

......

 

 cssFiles

 

 forum-css

 

 farFutureCaching

true

 link

/.resources/forum/magnolia-forum-stk.css

 media

only screen and (min-width: 481px)

.....

 

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

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

 

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

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

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

ThreadViewthread-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.
forumIdThreadNewthread-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

ThreadReplythread-reply.html

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.

Node nameValue

 components

 

 forum

 

 stkForumLoginForm

 

 description

pur.paragraph.stkPURLoginForm.description

 dialog

standard-templating-kit:components/pur/stkPURLoginForm

 extends

../../pur/stkPURLoginForm

 renderType

stk

 templateScript

/templating-kit/components/forum/login.ftl

 title

pur.paragraph.stkPURLoginForm.title

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

Node nameValue

 test

 

 content

 

 0

 

 threadListPage

95010d8f-c448-45ee-91f2-6f80f2bb9b69

 00

 

 threadNewPage

817143d4-2754-49a4-bf83-4af3a6ae59a7

 threadViewPage

95010d8f-c448-45ee-91f2-6f80f2bb9b69

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

Node nameValue

 forum

 

 dialogs

 

 forumList

 

 threadList

 

 threadView

 

 threadNew

 

 threadReply

 

 forumAdd

 

 ...

 

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:

  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 nameValue

     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 nameValue

     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.

Node nameValue

 pop

 

 cssFiles

 

 styles

 

 forum

 

 farFutureCaching

true

 link

/.resources/forum/magnolia-forum-stk.css

 media

only screen and (min-width: 481px) 

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

WorkspacePermissionScopePath
ForumRead/WriteSelected and sub nodes/

Web access

PermissionPath
Get & Post/.magnolia/pages/forum*

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

WorkspacePermissionScopePath
ForumRead/WriteSelected and sub nodes/<forum name>

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.

Node nameValue

 modules

 

 forum

 

 apps

 

 forum

 

 permissions

 

 roles

 

 forum_ALL-admin

forum_ALL-admin

 forum_ALL-moderator

forum_ALL-moderator

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.

Node nameValue

 apps

 

 forum

 

 permissions

 

 chooseDialog

 

 subapps

 

 browser

 

 actions

 

 addForum

 

 availability

 

 access

 

 roles

 

 forum_ALL-admin

forum_ALL-admin

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.

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

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 template script and/or the ForumList model class.

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:

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.