[title sub="Written by Chris Graham, ocProducts"]ocPortal Tutorial: Nuances of forum integration[/title]

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

ocPortal 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

Once you have installed ocPortal, you cannot easily switch forums, as the member and usergroup IDs referenced by ocPortal would lose their association. Please see the 'Importing from other software' tutorial for more information on this.

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

[contents]decimal,lower-alpha[/contents]

[title="2"]A note about character sets[/title]

If your forum and ocPortal are not using the same character set there may be problems.
You can change ocPortal's character set if needed (see the 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 ocPortal's character set, and thus that log in would not work.

[title="2"]Comment topics[/title]

[exp_thumb="Configuration of special forums" float="right"]nuances_2[/exp_thumb]
Most resources in ocPortal 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 ocPortal will never update "last post" areas for parent-forum trees.

The first post in comment topics is a special 'spacer post'. This is necessary for two reasons...
 - To indicate what content the topic is for
 - 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)

[exp_thumb="The configured special forums do actually exist... see! (our own forum actually configures it all like this by default)" float="right"]nuances_1[/exp_thumb]

[title="2"]Super-members[/title]

Super-members are an ocPortal concept for advanced members that have access to extra facilities and are given greater trust. There is no constraint on how you might implement super-membership on your site, but most users would do as follows:
 - Create a super-member usergroup, and add all the desired users who aren't already staff
 - Give the super-member usergroup access to the collaboration zone
 - Turn on additional privileges for the super-member usergroup as desired

[title="2"]Forum base URL[/title]

It is very common for ocPortal users to install the portal, but get the forum base URL wrong. This can be easily corrected after installation by using the separate [tt]config_editor.php[/tt] script (the one where you need to enter the admin 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 section, Cleanup Tools icon).

The forum base URL should not include a script name -- it should be a URL-prefix to your forums. For example,
 - [tt]http://forums.ocportal.com[/tt] is what we used to use for ocportal.com's forum base URL
 - [tt]http://forums.ocportal.com/index.php[/tt] would not have been correct, as ocPortal won't be able to find emoticon image URLs by using this as a prefix
 - [tt]http://forums.ocportal.com/[/tt] would have been over-specified -- the final slash is not required

[title="2"]Show forum within website[/title]

[exp_thumb="Configuring ocPortal to generate in-line forum links" float="left"]nuances_3[/exp_thumb]
[exp_thumb="The default forum link before you fix it..." float="right"]nuances_forum_menu_1[/exp_thumb]
ocPortal supports integration of your forum into the portal, so that it fits between your menus, and your header and footer. For this to work, ocPortal loads up the forum on-server, and integrates its XHTML code and CSS into the XHTML code and CSS of ocPortal; 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 ocPortal 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.

[exp_thumb="...and this is how you should make it be" float="right"]nuances_forum_menu_2[/exp_thumb]

Be aware that the forum and ocPortal 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.

[title="3"]Example of making the CSS work together[/title]

This example is for phpBB 3's default skin.

If will help a lot if you add this to ocPortal's [tt]global.css[/tt]...
[code]
.global_middle #wrap {
	float: left;
	width: 100%;
	font-size: 7pt;
	direction: ltr;
}
[/code]
This will make them rest will together in terms of spacing, and set phpBB to have a good base font size.

And then you can make changes like this to the phpBB's CSS...
[code]
h4 {
	/* Forum and topic list titles */
	font-family: "Trebuchet MS", Verdana, Helvetica, Arial, Sans-serif;
	font-size: 1.3em;
}
[/code]
to
[code]
#wrap h4 {
	/* Forum and topic list titles */
	font-family: "Trebuchet MS", Verdana, Helvetica, Arial, Sans-serif;
	font-size: 1.3em;
}
[/code]
because putting "#wrap" before things will make it apply to stuff inside phpBB, not to ocPortal.

"#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.

[title="2"]Cookie integration[/title]

ocPortal, where possible, will allow you to use the same cookies for logging into ocPortal as you do for your forum. However this is difficult to set-up as:
 - it requires cookie domain and path consistency between ocPortal 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, ocProducts does 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 portal exist underneath. A blank path will not work
 - That the cookie domain is valid for both the forums and the portal. If your portal and forum are on different sub-domains, then blank will not work. For example '.forums.ocportal.com' would not cover a portal on 'ocportal.com'. '.ocportal.com' would cover both -- and hence that should be used for the cookie domain. The proceeding 'dot' has a special meaning. Preferably, forum and portal 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 ocPortal use will be based on the real cookie names, whilst forums may ask you just to define a stub
 - That you clear cookies from the ocPortal/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

[title="2"]Forum specifics[/title]

[title="3"]SMF[/title]

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

For SMF cookies to work you must disable local cookies in the SMF configuration and set the cookie name correctly in ocPortal:
[list="1"]
[*]Disable "Enable local storage of cookies" option in SMF > Admin > Configuration > Server settings > Cookies and Sessions
[*]The Cookie Name is configurable in the same place as above. Let's assume it is set as [tt]SMFCookieXXX[/tt]. We would need to have the cookie names configured as follows in ocPortal's [tt]info.php[/tt] file:
[code]
$SITE_INFO['user_cookie']='SMFCookieXXX:0';
$SITE_INFO['pass_cookie']='SMFCookieXXX:1';
[/code]
[/list]

[title="3"]vBulletin[/title]

If you use vBulletin 3.5 or earlier put:
[code]
$SITE_INFO[vb_version]=3.5;
[/code]
into [tt]info.php[/tt].

(this flipped around in ocPortal 4 -- previously you had to change info.php for 3.6 to work)

[title="3"]phpBB2[/title]

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

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

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

[title="3"]Invision Power Board[/title]

OpenID, LDAP, and Facebook connect integration is not supported via the IPB forum driver.

If you use IPB stronghold cookies (version 2.2 and later) put:
[code]
$SITE_INFO['stronghold_cookies']=1;
[/code]
into [tt]info.php[/tt].

ocPortal 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. ocPortal uses usergroups to control access.

In order for ocPortal to perfectly display forum posts in the ocPortal '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 ocPortal [tt]global.css[/tt] 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 ocPortal -- 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 ocPortal outputs and see what CSS classnames are being referenced -- then copy over any styles that apply to these classnames.

[title="3"]AEF[/title]

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

[box="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, '/');
[/box]

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

[title="3"]None-forum[/title]

Using the none-forum driver, many ocPortal features will either be disabled or made useless. This includes the guestbook, 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 OCF rather than no forum and simply restricting access to the forum zone, join module, and personal zone.

[title="2"]Our own forum (OCF)[/title]

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

There are many advantages to use OCF, such as:
 - you'll be able to use Comcode for making forum posts and not see any difference in presentation between portal 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 ocPortal to the forum
 - the forum will use the same theme and basic templates as ocPortal
 - there is no need to learn concepts from two pieces of software: OCF has perfect integration on all levels
 - OCF is full of innovative features that other forum systems do not have (such as Private Topics and in-post whispers), regardless of its association to ocPortal

[concepts
 1_key="OCF"   1_value="The powerful forum and member system that comes with ocPortal. OCF is only used if a third-party forum isn't."
]Concepts[/concepts]

[title="2"]See also[/title]

 - [page caption="Importing data into ocPortal"]tut_importer[/page]
 - [page caption="The staff/member divide"]tut_staff[/page]