Composr Tutorial: Nuances of forum integration

Written by Chris Graham
Composr supports integration with a wide variety of forum systems through our forum driver system. Integration is seamless for the most part, but there are a few issues as described in this tutorial.

Composr draws upon the forum for features such as:
  • emoticons (aka smilies)
  • member management (aka user management, profile management)
  • (user)group management (the same as ranks, on some forums)
  • topic storage (aka thread [storage])
  • personal messaging (aka private messaging), or Private Topics

Table of contents

  1. Composr Tutorial: Nuances of forum integration
    1. Our own forum (Conversr)
    2. A further word of caution
    3. A note about character sets
    4. Comment topics
    5. Forum base URL
    6. Show forum within website
      1. Example of making the CSS work together
    7. A note about long_text custom profile fields (advanced)
    8. Cookie integration (advanced, non-supported)
    9. Forum specifics (advanced)
      1. SMF
      2. vBulletin
      3. phpBB3
      4. myBB
      5. Invision Power Board
      6. AEF
      7. None-forum
    10. See also

Our own forum (Conversr)

We strongly recommend the use of our own forum, Conversr, rather than a third-party one, if Composr is not being installed against a pre-established forum (although we strive to provide a number of tools to convert from your existing forum software).

There are many advantages to use Conversr, such as:
  • you'll be able to use Comcode for making forum posts and not see any difference in presentation between website and forum
  • the forum users-online and sessions features will be the same as the sites
  • you won't have to work between the Admin Zone and forum admincp – there will instead be a single Admin Zone
  • links will flow seamlessly from Composr to the forum
  • the forum will use the same theme and basic templates as Composr
  • there is no need to learn concepts from two pieces of software: Conversr has perfect integration on all levels
  • Conversr is full of innovative features that other forum systems do not have (such as Private Topics and in-post whispers) – it's actually a very powerful system in its own right

Frankly speaking, using a third-party forum is far too clunky for the modern user to tolerate, costly to maintain, and may give you a headache. If we were recreating Composr today we wouldn't include support for third-party forums. We only continue to maintain the functionality because it is sometimes necessary to connect to pre-established membership systems.

A further word of caution

Once you have installed Composr, you cannot easily switch forums, as the member and usergroup IDs referenced by Composr would lose their association. Please see the Importing data into Composr tutorial for more information on this.

Also: if you upgrade your forum after installing be sure to check Composr supports the version you are upgrading to before doing it.

A note about character sets

If your forum and Composr are not using the same character set there may be problems.
You can change Composr's character set if needed (see the Localisation and internationalisation tutorial for needed).
A good example – if your login password has weird symbols (ones that don't appear on most keyboards), those symbols may not be the same in Composr's character set, and thus that log in would not work.

Comment topics

Image

The configured special forums do actually exist... see! (our own forum actually configures it all like this by default)

The configured special forums do actually exist... see! (our own forum actually configures it all like this by default)

(Click to enlarge)

Image

Configuration of special forums

Configuration of special forums

(Click to enlarge)

Most resources in Composr that have commenting enabled create comment topics in the configured comment forum. If a forum stores posts in BBCode, then if Comcode features not supported in BBCode were used, they will be displayed unparsed when viewing from the forum.

You should moderate comments from the forum as you would any other forum topic. On some forum drivers, however, the forum "latest post" area may not update properly to show new posts. It is best to have the comment topic forums ("Website comment topics" and "Website support tickets", by default) located on the root of the forum-view, as Composr will never update "last post" areas for parent-forum trees.

The first post in comment topics is a special 'spacer post'. This is necessary because:
  1. To indicate what content the topic is for, and provide a link back to it
  2. To allow the first true post in the topic to be deleted (with ordinary forum topics the first post can not usually be deleted because it is considered as setting the grounds for the topic)

Forum base URL

It is very common for Composr users to install Composr with the forum base URL wrong. This can be easily corrected after installation by using the separate http://yourbaseurl/config_editor.php script (the one where you need to enter the maintenance password you chose upon install to change the installation environment). Once this is done, it is necessary to clean the Comcode page cache (go to: Admin Zone > Tools > Cleanup tools).

The forum base URL should not include a script name – it should be a URL-prefix to your forums. For example,
  • http://forums.example.com would be okay
  • http://forums.example.com/index.php would not have been correct, as Composr won't be able to find emoticon image URLs by using this as a prefix (imagine http://forums.example.com/index.php/styles/emoticons/smile.png – clearly that would be wrong)
  • http://forums.example.com/ would work – but the final slash is not required (we don't want to have double slashes in the generated URLs)

Show forum within website

Image

Configuring Composr to generate in-line forum links from:
Admin Zone > Setup > Configuration > Site options > Advanced

Configuring Composr to generate in-line forum links from:<br />Admin Zone &gt; Setup &gt; Configuration &gt; Site options &gt; Advanced

(Click to enlarge)

Image

...and this is how you should make it be

...and this is how you should make it be

(Click to enlarge)

Image

The default forum link before you fix it...

The default forum link before you fix it...

(Click to enlarge)

Composr has a feature for integration of your forum into the website (maintenance status), so that it fits between your menus, and your header and footer. For this to work, Composr loads up the forum on-server, and integrates its HTML code and CSS into the HTML code and CSS of Composr; it also relays cookies, to give the illusion that you are interacting directly with the forum code.

This feature can be turned on from the Admin Zone configuration module, and once on, any Composr generated forum link will be passed through the module (such as links to member profiles). You will also need to replace the forum link in the menu so as to pass through the 'forums' embedding module, as the menus are not managed by the configuration options. To do this, click the "edit menu" link underneath the menu, and make the change as identified in the screenshots.

Be aware that the forum and Composr both will look a bit weird because it will be running with two sets of CSS sheets that have not been designed to work together. It is up to you to make things look seamless.

Example of making the CSS work together

This example is for phpBB 3's default skin.

If will help a lot with the integration if you add this to Composr's global.css…

Code (CSS)

.global-middle #wrap {
        float: left;
        width: 100%;
        font-size: 7pt;
        direction: ltr;
}
 
This will make them rest well together in terms of spacing, and set phpBB to have a good base font size.

#wrap is used internally to phpBB, and is not used in Composr. It is therefore a good way to target only the embedded phpBB layout with additional styling rules.

And then you can make changes like this to the phpBB's CSS…

Code (CSS)

h4 {
        /* Forum and topic list titles */
        font-family: "Trebuchet MS", Verdana, Helvetica, Arial, Sans-serif;
        font-size: 1.3em;
}
 
to

Code (CSS)

#wrap h4 {
        /* Forum and topic list titles */
        font-family: "Trebuchet MS", Verdana, Helvetica, Arial, Sans-serif;
        font-size: 1.3em;
}
 

"#wrap" is specific to phpBB but most forums will have something similar you can bind your CSS to, or otherwise you can add something via changing a forum template.

A note about long_text custom profile fields (advanced)

When using a third-party forum driver, custom profile fields which would normally be of type LONG_TEXT will instead be TEXT, which translates to the database type varchar(16377) (or your database adapter's equivalent type). This is to work around a MySQL limitation of the longtext type where a default value is not supported (see MySQL bug #21532), resulting in the inability to create new member accounts on the forum itself due to database errors. We also had to work around the possibility a forum is using InnoDB, which has a default page_size of 16,384 bytes (though 7 of those bytes are reserved).

This does not affect most people as custom profile fields cannot be managed manually when using a third-party forum driver. However, when developing addons that utilize custom profile fields, this is important to remember as fields cannot hold more than 16,377 characters of data.

It is not recommended to explicitly use the TEXT field type for custom profile fields; use LONG_TEXT as you normally would. The Composr software will automatically use TEXT when using a third-party forum driver.

Cookie integration (advanced, non-supported)

Composr, where possible, will allow you to use the same cookies for logging into Composr as you do for your forum. However this is difficult to setup as:
  • it requires cookie domain and path consistency between Composr and the forum
  • if mistakes are made during configuration, they may block the success of reconfigurations, by the unsuccessful cookies being dominant over the correct ones
  • web browsers can behave differently with respect to cookies, especially when they are configured differently
  • cookie format may change between forum versions, and we might not always track such changes as it is not obvious (no error messages are provided)
Due to all these problems, we do not support this functionality officially.

Make sure:
  • That the forum cookie path is set to '/', or at least a URL path that both the forum and the website exist underneath. A blank path will not work
  • That the cookie domain is valid for both the forums and the website. If your website and forum are on different sub-domains, then blank will not work. For example '.forums.example.com' would not cover a website on 'example.com'. '.example.com' would cover both – and hence that should be used for the cookie domain. The proceeding 'dot' has a special meaning. Preferably, forum and website will be on the same exact domain, so to avoid any confusion
  • That the cookies have the same names. For most forums this will be auto-detected. The names Composr use will be based on the real cookie names, while forums may ask you just to define a stub
  • That you clear cookies from the Composr/forums sites and reload your web browser between configuration changes. Please note that clearing all cookies indiscriminatingly is likely to be annoying for you because you will have to re-enter many passwords on Internet sites, and you may not remember them all

Forum specifics (advanced)

SMF

Super-administrator membership is determined by membership of the 'Administrator' usergroup (#1).
Super-moderator membership is determined by membership of the 'Global Moderator' usergroup (#2).

When running an SMF version below 2.0, in order for frame-embed of SMF to work ("Show forum within website"), you need to remove this line from SMF's index.php file:

Code (PHP)

header('X-Frame-Options: SAMEORIGIN');
 

When using a Gravatar, for privacy reasons, the Composr software does not support a custom e-mail address like SMF does. Therefore, if a custom Gravatar e-mail address is specified in SMF, it will be ignored and instead the member's account e-mail address will be used.

Cookie log-in (“Remember me”) is not implemented in the Composr software for SMF; members must log in separately both in the Composr site and in SMF. SMF encodes lots of data into their cookie which would be too complex and fragile to replicate in the Composr software. See tracker issue #5258.

When using the “Show forum within website” option, the log-in form in SMF will throw an unauthorized error. It is unknown if this issue exists on other forms. See tracker issue #5259.

vBulletin

If you use vBulletin 3.5 or earlier put:

Code (PHP)

$SITE_INFO['vb_version'] = 3.5;
 
into _config.php.

phpBB3

phpBB3 is unlike the other supported forums when it comes to determining who is a member of staff or not. phpBB stores this as a user-level for each user, rather than encoding it in the properties of a usergroup.

Composr uses the user level to define admin membership, but in order to make staff show up on the staff module, you will need to create a new usergroup named 'Administrators' and put all staff into it. The reason for this is that Composr uses usergroup membership to list all the staff.

Because of this no-group issue, the staff filter feature is disabled for phpBB: it can't synchronise when it is turned on, and thus would lock existing staff out.

myBB

To determine which usergroups are moderators, we check for the myBB usergroup permission “Yes, users of this group are super moderators”.

Invision Power Board

LDAP, and OAuth integration is not supported via the IPB forum driver.

If you use IPB stronghold cookies (version 2.2 and later) put:

Code (PHP)

$SITE_INFO['stronghold_cookies'] = 1;
 
into _config.php.

Composr doesn't support IPB permission masks. This is because IPB permission masks are used to define which forums a member may moderate, not a user's overall user-level. Composr uses usergroups to control access.

In order for Composr to perfectly display forum posts in the Composr 'forum news' block in the same way as IPB would display them, it's necessary to take some CSS from IPB and place it in the Composr global.css file. This particular applies to posts that contain quotes. Invision Board stores all its posts in HTML format, which is fine, except the CSS styles of IPB are internal to IPB and thus not in Composr – the cause of this problem.

The particular styles that would need copying would depend on the skin that IPB was using. If you are experiencing this problem, look at the HTML Composr outputs and see what CSS classnames are being referenced – then copy over any styles that apply to these classnames.

AEF

As AEF does not support configurable cookie paths, it is necessary to modify the code to get it to correctly share cookies…

Code changes

[AEF installation directory/folder]/main/login.php need the following changes:
- line 324: @setcookie($globals['cookie_name'].'[loguid]', $row['id'], (time()+(60*60*24*365)));
 to be changed to: @setcookie($globals['cookie_name'].'[loguid]', $row['id'], (time()+(60*60*24*365)), '/');

- line 327: @setcookie($globals['cookie_name'].'[logpass]', $logpass, (time()+(60*60*24*365)));
 to be changed to: @setcookie($globals['cookie_name'].'[logpass]', $logpass, (time()+(60*60*24*365)),'/');

[AEF installation directory/folder]/main/logout.php need the following changes:
- line 66: @setcookie($globals['cookie_name'].'[loguid]', "", (time()-(60*60*24*365)));
 to be changed to: @setcookie($globals['cookie_name'].'[loguid]', "", (time()-(60*60*24*365)), '/');

- line 69: @setcookie($globals['cookie_name'].'[logpass]', "", (time()-(60*60*24*365)));
 to be changed to: @setcookie($globals['cookie_name'].'[logpass]', "", (time()-(60*60*24*365)), '/');

[AEF installation directory/folder]/main/sessions.php need the following changes:
- line 148: @setcookie($globals['cookie_name'].'[aefsid]', $id);
 to be changed to: @setcookie($globals['cookie_name'].'[aefsid]', $id, 0, '/');


Composr will need a cookie path of "/" for this to work, and a blank cookie domain.

None-forum

Using the none-forum driver, many Composr features will either be disabled or made useless. This includes content commenting and points, and anything involving interaction between logged in users.

If using this driver, you should remove links and blocks from the menus that involve users (such as the forum link, the points links, and the personal-stats-block).

You are likely better off using Conversr rather than no forum and simply restricting access to the forum zone, join module, and personal zone.


See also


Feedback

Please rate this tutorial:

Have a suggestion? Report an issue on the tracker.