HTML Logo by World Wide Web Consortium ( Click to learn more about our commitment to accessibility and standards.

Moving forward with Composr

ocPortal has been relaunched as Composr CMS. ocPortal 9 is superseded by Composr 10.

Head over to for our new site, and to our migration roadmap. Existing ocPortal member accounts have been mirrored.

How to setup the Facebook Addon Feature for ocPortal versions 8 and 9

There are many steps to follow to insure a successful installation of this carefully crafted addon which will offer a quick and simplified option to join and login to your member based website.  I have written the following tutorial as a guide with enough details I hope to alleviate the apprehension  of a malfunction for skipping an important step.

Before proceeding with the installation of this addon, know that It is crucial to create a new administrator account for use as a Facebook login. Subsequently logout of the current one and log back in with the newly created account for Facebook login.  If you otherwise ignore this advice , you may find yourself locked-out of your site if it is presently closed or when you eventually need to close it for admin purposes. For obvious security reasons, a Facebook associated account cannot login to a closed-down website. You should always have a Master Administrator Account not associated with any third party login method.

NOTE: This is the TEXT-ONLY Instruction followed by the Illustrated version of this tutorial:

How to setup the Facebook Addon Feature
for ocPortal versions 8 and 9
Important Information, please read carefully before proceeding

It is crucial to create a new administrator account for use as a Facebook login. Subsequently logout of the current one and log back in with the newly created account for Facebook login.  If you otherwise ignore this advice , you may find yourself locked-out of your site if it is presently closed or when you eventually need to close it for admin purposes. For obvious security reasons, a Facebook associated account cannot login to a closed-down website. You should always have a Master Administrator Account not associated with any third party login method.

Step-1:From Admin Zone---->Structure----->Addons-->
Step-2:Import non-bundled addons
Step-3:Check Download -->Select Third Party Integration--> select "Facebook Support"
Step-4: Finalize selection by clicking on bottom Blue Button:  Import non-bundled addon(s)
Step-5: on next screen Click on Blue Button:  Proceed
Step-6: Notice that the Facebook Support tar file is now listed on the Addon page-->Click Action checkmark button to install-->Click on bottom Install non-bundled addon(s) button (yes this is a two step installation; first, the Import process and second, installation.
Step-7: Select from-->Home-->Status-->Setup-->Facebook syndication / login
Step-8: Click on get an API Key link for Facebook Developers Apps Page
Step-9: Click on right upper corner  "Create a New App" Button
Step-10: on Popup Form: Type a unique name for your application - Use small caps, no spaces, keep it short. That's it, nothing else need to be filled at this time. Click on the "Continue" button.
Step-11:  Make sure to properly fill the Basic info Fields:
·         Display Name
·         Contact Email
·         App Domain
·         Category
·         Add your Website URL on the Website with Facebook Login Field. 
·         Finish by clicking the "Save Changes" Button.
Step-12:  Copy/paste the App ID and App Secret Codes back to ocPortal's Facebook Configuration Panel (step 7) Fields (It should still be there behind this page). The Facebook Page ID field will be automatically filled the next time you click on the Facebook Syndication button.
Step-13:  You will click again on the “Facebook syndication / login button (found on step 7), making sure that you are already logged in Facebook and that your website is open. Doing so will generate a Facebook authorization Confirmation Screen.

Step-14:  IMPORTANT! DO NOT PERFORM THIS FINAL TEST IF YOU onLY HAVE onE ADMINTISTRATION USERNAME - CREATE A SECOND onE JUST FOR FACEBOOK. Finally, to test your Facebook login, logout,  type the site’s URL and use your Facebook login button.  If you have administrator rights, you should be able to login to the site zone or the adminzone while the website is in opened status.


Facebook addon tutorial

There are no pages beneath this page

Submitted by AndrewMorgan
OOPS, I goofed and need help...

How can I get back to the Facebook Configuration screen?

I followed all directions, selected the SETUP - FACEBOOK SYNDICATION / LOGIN and added the APP ID and APP SECRET...

Hit the "save" button and revisited the SETUP - FACEBOOK SYNDICATION / LOGIN only to see a Facebook ERROR "An error occured try again later"

THEN I happened to visit my Facebook APPPS to find I had already set up a previous APP for my domain so I DELETED THE NEW onE...

NOW IO can't seem to find where I can restart the installation configurations where I can add a NEW APP ID and SECRET...

I have searched all files in my cpanel and nowhere do I see where I can exchange an old ID and SECRET for a new one and the SETUP - FACEBOOK SYNDICATION / LOGIN won't allow me to use it for that again because it is trying to connect to Facebook w/o regard to my needing to change APP ID and SECRET...

I attempted un-installing the Facebook Support Addon and re-installed to no avail.

PLEASE advise!


P.S. I went to purchase credits for paid support but because it uses PayPal exclusively I can't make a payment. Who knows of another way to buy some support credits?
Submitted by Jean

Andrew said

NOW I can't seem to find where I can restart the installation configurations where I can add a NEW APP ID and SECRET…

You can always reconfigure the Facebook Syndication values after installation by going directly to the setup configuration:
Admin Zone-->Setup-->Configuration-->Feature options-->Facebook syndication / login 

See attached image:

Submitted by thelocalmc
Thanks for the step-by-step. I have the Facebook support installed and working perfectly! I love ocPortal.

- The LocalMC
Submitted by Chris Graham
I have some additional notes regarding our Facebook support.

  1. Jean mentioned that you could lose admin access. I don't think that's quite true, but what is true is that your admin account will become associated with Facebook, i.e. have a Facebook login. This is because the admin authorisation mirrors the login process; for Facebook, they are kind of the same thing. You shouldn't lose any admin privileges, and even if you logged out of your Facebook account, it should be possible to use Facebook connect to log into a closed site, if you're admin. If you want to disassociate your account with Facebook you can – just run a password reset on your account.
  2. Step '13' (repeating the authorisation) should not actually be required. Maybe it was in the past due to a bug, but after you save the config, it should take you to authorise all in one go.
  3. A common confusion is why content may not be syndicated always, even if you tell it to (either personally, or on a site level). ocPortal maintains a security rule - syndication only happens if something is accessible to guests (because essentially syndication is automatically announcing and linking to content, that might otherwise have been private). That means, the zone, page, and category, for the content must all be guest accessible. Whether the site is closed is not a consideration. For news, category permissions aren't checked. (This also applies to the Twitter addon)
  4. People often wonder why you can syndicate everything personally, but not everything on a site level. Essentially we think of these things differently. A site syndicates headline things, while a person syndicates more personal things. If something is a headline thing, it's going to have an associated news post, or calendar event, regardless of what other kinds of content may be involved. So, site syndication is focused on those news posts and calendar events. You can always manually post to Facebook if there is something else you want to draw attention to. (This also applies to the Twitter addon)
  5. It's crucial that Facebook has been given the correct base URL to your site. It absolutely will not allow things to integrate if it does not match exactly. Make sure you have the same case (i.e. all lower case) and the same use or non-use of 'www.' in the domain name.
  6. You must use a domain name, not an IP address. You can actually test without a REAL domain name though, on a test server (e.g. your local development machine). Use your 'hosts' file to make a fake domain, make sure ocPortal's base URL matches it, and that the Facebook app matches it. This works great.
  7. When setting up the app on Facebook, ignore everything about 'Hosting URL'. This is not relevant to you, it's to do with Facebook's web hosting partners.
  8. Facebook's apps are intended for developers. We're helping people getting ocPortal integrated, even when you're not a developer, but bear in mind that it can be tricky sometimes. Facebook is in flux, and ocPortal has to play catchup quite a lot. All the standards involved in the integration are also in flux. Things are a lot better than they were, but still not always ideal. Facebook will email notices about changes in functionality and has a phased 'opt in' system before it forces everyone to update; we try and track these, usually they only affect a minority of Facebook apps though and not ocPortal. We do not have any guarantee on maintaining smooth Facebook support across changes on Facebook's end, but we do try.
  9. Nowadays we try and keep the Facebook integration in step with ocPortal patch releases. Fixes to Facebook support are often released as hot-fixes, even though Facebook support is not a bundled ocPortal feature. When we make a new ocPortal patch release, we often push updated non-bundle addons at the same time. This is us attempting to bring some organisation, considering how important Facebook is to people, even though Facebook is not an officially supported part of ocPortal (because it doesn't meet our non-partisan rules).
  10. People may wonder how you can logout once you've logged into a site using Facebook. Facebook actually has rules saying that sites must enforce automatic logins, so legally logout is not really allowed. However, if you logout of Facebook, you log out of all websites you've logged into using Facebook. If you want to stop a site auto-logging you in, you do it by blocking the site's app on Facebook's account settings (i.e. on Facebook's end, not the site's end).
  11. If users return to your site, it will refresh once, then act normally. This is because the Facebook login is maintained with Javascript, and the refresh lets the server refresh the login (necessary, as it needs to check security against an active Facebook session, it can't do it on trust).
  12. Users may occasionally get a "Could not login, probably due to restrictive cookie settings." error. This can be a bit random, but can happen if multiple pages are being loaded at once. It can be ignored if it only happens occasionally.
  13. ocPortal supports 'OpenGraph'. Content should automatically be marked up with it, and therefore links to your site on Facebook (including syndicated ones) should have fairly reasonable titles and choices of image.
Submitted by Chris Graham
If you need to add someone else to your Facebook app, to help development of it/debug:

  1. Go to Facebook developer apps section
  2. Click the "Edit App" button
  3. Click "Developer roles" under the "Settings" menu
  4. Click "Add" over the Administrators section
  5. Type their Facebook ID (the one they chose, not the numeric one) – or, if they are your Facebook friend, just their name will work
Submitted by Chris Graham
Note that syndication requires the non-bundled Activity Feed addon to be installed.
Submitted by Chris Graham
Another warning from me about Facebook logins…

If you are prone to log in as different users, do not use Facebook connect. For one thing, you'll have a hard-time actually logging out. But also, Facebook Connect aggressively associates with any account you're logged into, binding it to your Facebook account. ocPortal theoretically only allows one account to be associated with any one Facebook account, but it's not worth getting confused over. Only use Facebook Connect to login if you strictly use one account, and stay logged into it.
Submitted by Chris Graham
Note that if you have your site closed (or protected from Guests), Facebook cannot access your pages in order to read your OpenGraph data. This means Facebook OpenGraph will not work correctly until your site is open, and various Facebook features may be limited due to Facebook's servers not being able to read the pages fully.
Submitted by Chris Graham
The Facebook addon intentionally removes the posts tab of member profiles. See:
View topic: "Posts" tab on member profile -
Submitted by Chris Graham
If you want to customise the icons that come up on Facebook for syndicated activity, you need to change the OpenGraph tags that ocPortal puts out.

The ocPortal code hints what images to use for various content screens. Where possible, a natural image is used. For example, when viewing a gallery image, the thumbnail will be the OpenGraph image. However, for content types with no natural image, often an icon is used.

This example shows how to change the topic syndication to use a custom theme image, rather than the bigicons/forums theme image.

1) Theme image…

Add a theme image called opengraph_defaults/forums to the default theme.

Either do this via ocPortal's interface, or create a themes/default/images_custom/opengraph_defaults/ directory and upload a forums.png file to it.

2) Template…

Edit the HTML_HEAD template in the default theme (ignore the warning)…



{+START,IF_NON_EMPTY,{$META_DATA,image}}<meta property="og:image" content="{$META_DATA*,image}"/>{+END}{+START,IF_EMPTY,{$META_DATA,image}}<meta property="og:image" content="{$IMG*,logo/trimmed_logo}"/>{+END}




      <meta property="og:image" content="{$IMG*,opengraph_defaults/forums}" />

      <meta property="og:image" content="{$META_DATA*,image}" />
{+START,IF_EMPTY,{$META_DATA,image}}<meta property="og:image" content="{$IMG*,logo/trimmed_logo}" />{+END}

Our new code detects if the OpenGraph image was set as bigicons/forums and performs a substitution to our custom one.

Our change won't reflect on Facebook for existing syndications until Facebook refreshes it's caching. But eventually it will, i.e. it will work retroactively. This reflects on the algorithm Facebook uses: Facebook is not sent the image, Facebook looks at the syndicated link, and finds the image via OpenGraph.
Submitted by Chris Graham
When testing log in, make sure you're not starting a login from a URL with &refreshed_once=1 or &keep_refreshed_once=1 in it. That is an indicator to the addon that auth has happened once. It is necessary to stop nasty refresh loops that can happen when various kinds of security barrier are in place (e.g. cookie limits, or inter-server communication blocks, or just if sites are down). If you navigate back to such a URL in your history, or are logging out and in and letting that propagate, the Facebook button will not refresh for you when you login.
Submitted by Chris Graham
Facebook login differs from normal signup in the following ways…
  • Password or username restriction rules will not apply, as the user does not choose these on your site
  • Rule acceptance will not happen (so make sure you link to your rules somewhere); Facebook login is generally designed as one-click, so extra steps are the antithesis of this
  • There is only one step, unless there are required CPFs configured (in which case a profile completion step is required)
  • E-mail address confirmation is not required
  • The following details are taken from Facebook profiles: Date-of-birth, e-mail address, timezone (rough conversion from a time offset), username, photo, language (if a direct match is found)
Submitted by Chris Graham
The Facebook comments block will only work if placed somewhere where Guest access is allowed.
Submitted by Chris Graham
Note that the Facebook login does not populate the default "Facebook profile" CPF. This CPF may be deleted if you wish, as the Facebook Connect support automatically inserts a link back elsewhere on the profile.
Submitted by Chris Graham
As there are so many notes here, we will move it into a proper tutorial. Here is some stuff from the addons description, which will be removed from that and put into the tutorial (so that the description doesn't pretend to be documentation, when clearly it is not)…

To use the Facebook login support your Facebook app needs to be told the domain name you are using. This is for security reasons and because it saves login cookies to this domain. It can't be a domain like 'localhost' or 'mycomputer', so if you are testing on a local computer you will need to create an imaginary domain name and link it into via your computers 'hosts' file.

How to use the Facebook friends block

The Facebook friends block adds a list of your facebook fans to your website.
Example Comcode to use it:


[block stream="1" fans="10" logobar="1" param="80430912569" show_fanpage_link="1" fanpage_name="ocPortal Fans"]main_facebook_friends[/block]

'stream' is either "1" or "0" – 1 is you would like the stream to display, 0 means you don't.

'fans' is the number of fans you want the block to display.

'show_fanpage_link' is either "1" or "0" – 1 is you would like to display a link to the fan page, 0 means you don't.

'fanpage_name' is the name you want to display on the link to the page.

'logobar' is either "1" or "0" – 1 is you would like to display a facebook logo on within the block, 0 means you don't.
Submitted by Chris Graham
Some notes about how the login process actually works...

Facebook login is achieved via Javascript and cookies, which is the standard integration Facebook provide. It is also possible to do it on the server directly, which is where I'd like to take things in the future, but it means major rewriting.

Because it happens in Javascript, if there is no ocPortal session anymore, the page will be served as Guest until Facebook's Javascript code sets a new Facebook session, then we refresh, then ocPortal turns it into an ocPortal session.

You could increase the ocPortal session length, but it's not really advisable, as it lowers security (longer sessions = greater risk of attack by someone trying to steal session IDs).

ocPortal shouldn't take you somewhere else. Our refresh code only takes you to the website front page if you were actually logging in from a URL with 'login' in it (i.e. the login page). I suppose you could have something like a forum topic with 'login' in the URL moniker which could be erroneously triggering that, or there could be a bug. If you can report clearly where the original link was and where you ended up (obfuscated if required) I might be able to spot something.

I use Facebook login myself extensively and it tends to be pretty solid.
Submitted by Chris Graham

Binding existing logins to Facebook

If you are logged in, but your account is not attached to Facebook, ocPortal will show the login button to let you bind your account.

The login button is placed there within an overridden version of the BLOCK_SIDE_PERSONAL_STATS.tpl template.

If you do not want this, edit the template, remove this code:


         <div class="fb-login-button" data-scope="email,user_birthday{+START,IF,{$CONFIG_OPTION,facebook_auto_syndicate}},publish_stream,offline_access{+END}"></div>

This will not affect the version of the block shown to guests, which is a different template.
Submitted by Chris Graham
Facebook is particularly aggressive at maintaining its logins: you can't directly logout from individual sites as such. We can't workaround that within ocPortal's code.

A user who wishes to delink Facebook to your site has two choices:

1) Log out of Facebook entirely (probably undesirable)

2) Remove your website from the allowed apps, via Facebook's privacy settings.

I've attached screenshots for '2'.

Submitted by Chris Graham
A customer asked about why the 3rd party TwitterFeed service kept stopping posting. Our answer also has bearing on our own Facebook addon…


These cross-service integrations have been rather unreliable over the years, as the technology has changed rapidly without much coordination. Additionally these services have turned out rather niche and loss-making, so a lot of the companies investing them have not really maintained/polished/supported them well.

From a Facebook manual page:
"Facebook's SDKs will get long-lived access tokens, good for about 60 days."

If you reconnect it again, it should work again for another 60 days.

Facebook did not used to auto-expire its tokens, but they probably implemented it for security and when realising they don't make any money from these background apps so they are too much of a hassle/risk for them.

Not very helpful, I know. I think even our official Facebook addon for news syndication would have this problem as everyone is restricted to what Facebook's APIs allow. It wouldn't be as bad though, as the token would refresh each time the authorising Facebook user re-visited the ocPortal site. So it wouldn't expire as long as the Facebook user visited the ocPortal site at least every 60 days.

I typed all this up and I thought to myself "this is really such a fatal flaw with Twitterfeed, I'd like to get a second opinion". Confirmed, you can hear it straight from the horses mouth:
Twitterfeed, An easier way to re-connect Facebook accounts
Submitted by Chris Graham
The Facebook share buttons don't transfer the image/title to Facebook. Instead, Facebook comes back at the URL, and looks at the OpenGraph meta tags. Therefore for Facebook image/title sharing to work, the page must have public access.
CEDI change-log Post