SocialConnect

System requirements


Below are the system requirements for SocialConnect:

  • PHP version 5.1.2 or later. It won’t work under PHP 4.
  • PHP cURL library.
  • PHP JSON.
  • PHP HMAC. This function is used by the Twitter authentication process and was introduced in PHP 5.1.2.
  • Joomla! 1.5, Joomla! 2.5 or Joomla! 3.x.
You can check anytime the system requirements by visiting the SocialConnect Dashboard page:

sc-system-requirements

Further requirements


SocialConnect integrates the most popular social networks in your Joomla! website. These networks require some setup on their side to allow you to use their services:

  • Facebook integration: In order to allow users to login to your site using their Facebook account you need to create a Facebook application. Read the “Creating a Facebook Application” section of this document for more information. Since version 1.5 SocialConnect can also integrate Facebook comments in your site and in addition, it can be configured to post your site data to a specified Facebook account ( or page ) wall. In order to enable this features you need to give your existing Facebook application the appropriate permissions. This process can be done through SocialConnect. The section named "Authorizing your Facebook application" of this document describes the process in detail.
  • Twitter integration: In order to allow users to login to your site using their Twitter account you need to create a Twitter application. Read the “Creating a Twitter Application” section of this document for more information. In addition, since version 1.5, SocialConnect allows you to create tweets of your site content to a specified Twitter user timeline. In order to enable this feature you need to authorize your Twitter application. You can read the “Authorizing your Twitter application” section of this document for more information.
  • Google/Google+ integration: In order to allow users to login to your site using their Google/Google+ account you need to create a Google application. Read the “Creating a Google Application” section of this document for more information.
  • LinkedIn integration: In order to allow users to login to your site using their LinkedIn account you need to create a LinkedIn application. Read the “Creating a LinkedIn Application” section of this document for more information.
  • GitHub integration: In order to allow users to login to your site using their GitHub account you need to create a GitHub application. Read the “Creating a GitHub Application” section of this document for more information.
  • WordPress.com integration: In order to allow users to login to your site using their WordPress.com account you need to create a WordPress application. Read the “Creating a WordPress Application” section of this document for more information.
  • Microsoft integration: In order to allow users to login to your site using their Microsoft account (this includes Outlook.com, Hotmail, Windows Live, SkyDrive, Windows Phone and Xbox Live accounts) you need to create a Microsoft application. Read the “Creating a Microsoft Application” section of this document for more information.
  • Ning integration: This does not have any further requirements. If you have a Ning network, you can enable sign in for users of this network to your site. For further information on enabling Ning integration to your site please read the "Settings" section of this document.
  • DISQUS integration: In order to integrate DISQUS comments to your site you need to have a DISQUS account. Read the “Creating a DISQUS account” section of this document for more information.
The SocialConnect Dashboard page can provide you with information about the social networks you have already setup:
sc-dashboard

Installation - Upgrade

To install SocialConnect simply use Joomla! Extension installer and install it like any other extension. If you already running an older version of SocialConnect just install the new version without uninstalling the previous one.

Settings

All SocialConnect settings are located under the administration component. Settings are divided in the following groups:

  • Social Login Settings
  • Social Comments Settings
  • Social Auto Post Settings
  • System Settings
  • Permissions

Social Login Settings

Facebook

In order to enable Facebook login to your site you need to create a Facebook application and provide SocialConnect the following settings:

  • App ID. This is the Facebook application ID.
  • App Secret. This is the Facebook application secret.
Both of the above can be found on your Facebook application page. If you are not familiar with Facebook Applications then read the following section which provides a step-by-step process for creating one. Note that these settings are also required if you enable Facebook comments or content auto-post features of SocialConnect.

Creating a Facebook Application

First go to https://developers.facebook.com/ and sign in using your Facebook account. After that click the “Apps” button and then the “Create new app” button. Then Facebook will ask you for an “App Name”. For simplicity reasons we recommend to give your site name or your site URL, but you can give whatever name you like. Note that this is what users see when they will prompted to login to your site. After submitting the form you are going to be transferred in the basic settings of your application. There, look for the section titled “Select how your app integrates with Facebook” and click on “Website with Facebook Login”. There you need to fill in your site URL. Once you do that click “Save changes” and you are ready to use Facebook login to your site! The last thing required to do is provide the Facebook parameters to SocialConnect. SocialConnect needs two parameters, the Facebook App ID and the Facebook App Secret. Copy them from your Facebook application page and provide them to SocialConnect. Below is a typical Facebook application setup for SocialConnect:
sc-facebook

Twitter

In order to enable Twitter login to your site you need to create a Twitter application and provide SocialConnect the following settings:

  • Consumer key. This the consumer key of your Twitter application.
  • Consumer secret. This is the consumer secret of your Twitter application.
Both of the above can be found on your Twitter application page. If you are not familiar with Twitter Applications then read the following section which provides a step-by-step process for creating one. Note that you also need to provide these settings if you want to use SocialConnect auto-post feature for Twitter.

Creating a Twitter Application

First go to https://dev.twitter.com/ and sign in using your Twitter account. After that go to your account icon in the upper right corner and in the expanded sub-menu click the “My applications” link. In the next screen you are going to see the “Create new application” button. Click on it and you will be transferred in the “Create an application” page. There you need to fill in all the fields:

  • Name. Your application name. Give something like your site URL or your site name.
  • Description. Give a short description of your application.
  • WebSite. Give your website URL.
  • Callback URL. Give again your website URL.
Once you fill the above fields, you need to accept the terms and fill in the capcha. When you have finished click on the “Create your Twitter application” button and you are done! All you need to do now is to spot the “Consumer key” and the “Consumer secret” in your application page and provide them to SocialConnect. Below is a typical Twitter application setup for SocialConnect:
sc-twitter

Google/Google+

In order to enable Google/Google+ login to your site you need to create a Google application and provide SocialConnect the following settings:

  • Client ID. This the client ID of your Google application.
  • Client secret. This is the client secret of your Google application.
Both of the above can be found on your Google application page. If you are not familiar with Google Applications then read the following section which provides a step-by-step process for creating one.

Creating a Google Application

First go to https://code.google.com/apis/console/ and sign in using your Google account. If the browser redirect to the new "Cloud Console" then click on the "Go back" link to get the standard interface. After that click the “Create project...” button.Then you will be asked to give a name to your project. After you do so, click the “Create an OAuth 2.0 client ID...” button. Then you will be provided with the “Create Client ID” wizard. On the first step give a product name. The rest fields there are not required. After that click “Next” button to proceed to the “Client ID Settings”. Choose “ Web application” on the “Application type” and provide your site URL to the “Your site or hostname”. Right after that click on the “more options” link and on the field named “Authorized Redirect URIs” provide the following one :

YOUR_SITE_URL/index.php?option=com_socialconnect&view=login&task=googleoauth.

If you wish to integrate Google+ sign in to your site, then you need to enable Google+ API for your application. To do so, first click the "Services" button from the menu on the left and then set the "Google+ API" switch to on. Finally, in the "Authorized Redirect URIs" you need to provide the following one:

YOUR_SITE_URL/index.php?option=com_socialconnect&view=login&task=googleplusoauth

Now just click on the “Create client ID” button to complete the process. You are ready to go now. Just provide the Client ID and Client secret of your application to SocialConnect.

Below is a typical Google application setup for SocialConnect:
sc-google

LinkedIn

In order to enable LinkedIn login to your site you need to create a LinkedIn application and provide SocialConnect the following settings:

  • API key. This the API key of your LinkedIn application.
  • API secret. This is the API secret of your LinkedIn application.
Both of the above can be found on your LinkedIn application page. If you are not familiar with LinkedIn Applications then read the following section which provides a step-by-step process for creating one.

Creating a LinkedId Application

First go to https://developer.linkedin.com/ and sign in using your LinkedIn account. After that click the “API keys” button which can be found under your account name and in the next screen click on the “Add New Application”.Fill in the form and click on the “Add application” button in the bottom of the page. Finally grab the generated API key and Secret key and provide them to SocialConnect. Below is a typical LinkedInapplication setup for SocialConnect:

sc-linkedin

GitHub

In order to enable GitHub login to your site you need to create a GitHub application and provide SocialConnect the following settings:

  • Client ID. This the client ID of your GitHub application.
  • Client secret. This is the client secret of your GitHub application.
Both of the above can be found on your GitHub application page. If you are not familiar with GitHub Applications then read the following section which provides a step-by-step process for creating one.

Creating a GitHub Application

First go to https://github.com and sign in using your GitHub account. After that click the “Account settings” icon on the upper right menu. This will navigate you to your account settings page. Then you need to click the "Applications" link of the menu on the left and in the next screen you will see a button named "Register new application". Once you click it you will see the application page. You are asked there to give a name to your application. You can give whatever name you want. This is what users will see when they attempt to sign in to your site using GitHub. Next you need to provide a "Homepage URL" and an "Authorization callback URL" . Type in both these inputs the URL of your site. Finally click the "Register application" button to complete the proccess. Below is a typical GitHub application setup for SocialConnect:
sc-github

WordPress

In order to enable WordPress login to your site you need to create a WordPress application and provide SocialConnect the following settings:

  • Client ID. This the client ID of your WordPress application.
  • Client secret. This is the client secret of your WordPress application.
Both of the above can be found on your WordPress application page. If you are not familiar with WordPress Applications then read the following section which provides a step-by-step process for creating one.

Creating a WordPress Application

First go to http://developer.wordpress.com/apps/ and sign in using your WordPress account. Once you do so click the button named "Create New Application". In the form that appears type the name of your site in the field "Name". You also need to fill in the "Website URL" and the "Redirect URI" fields. Type there the URL of your site and ensure that the type of the application is set to "Web". Finally click the "Create" button. Your application should be ready now. Below is a typical WordPress application setup for SocialConnect:
sc-wordpress

Microsoft

In order to enable Microsoft login to your site you need to create a Microsoft application and provide SocialConnect the following settings:

  • Client ID. This the client ID of your Microsoft application.
  • Client secret. This is the client secret of your Microsoft application.
Both of the above can be found on your Microsoft application page. If you are not familiar with Microsoft Applications then read the following section which provides a step-by-step process for creating one.

Creating a Microsoft Application

First go to https://account.live.com/developers/applications/index and sign in using your Microsoft account. Once you do so click the link named "Create application" and in the next screen type a name for your application in the field named "Application name" ( you can type your site name here). After accepting the terms of use you will be redirected to the applicationsetup page. There you need to enter the URL of your site to the field named "Redirect domain". In the form that appears type the name of your site in the field "Name". Ensure that the radio button "Mobile client app" is set to "no" and click the "save" button. Your application should be ready now. Below is a typical Microsoft application setup for SocialConnect:
sc-microsoft

Ning

Ning setttings are quite straitforward for someone that has created a network on Ning:

  • Ning 'Default Domain': Enter the domain of the Ning Community you wish to integrate with your Joomla! website. Use the 'something.ning.com' format which you can find if you navigate to: http://youNingCommunityDomain.com/main/admin/editDomainMapping.
  • Ning 'CNAME Domain': Enter the network name of the Ning Community. This is usually the URL used to access your community.
  • Ning 'Network Name': Enter the network name of the Ning Community. This is usually the name of your community. It will be used by SocialConnect to let users know in which community they are logging in.
  • Ning login form pre-text: This is a text that is displayed to the users right before the Ning login form on your site.
  • Ning login form post-text: This is a text that is displayed to the users right after the Ning login form on your site.

Social Comments Settings

Here you can find options regarding the comments integration. The first option is named " Comments Service " and it allows you to select one of the available comments services. Each of those services require extra setup which is detailed below:

Facebook

  • Facebook comments application ID: You need to type here the ID of your Facebook application. If you have already setup a Facebook application in the Social Login Settings you can use the same here. Just copy the Facebook application ID here. If you have not setup a Facebook application, you need to do it. Read the section "Creating a Facebook Application" of this document.
  • Facebook comments width: The width of the Facebook comments block in pixels.
  • Facebook comments Color Scheme: The color scheme of the Facebook comments block.
  • Facebook number of comments: The number of comments to show when the Facebook comments block is loaded.
  • Facebook comments ordering: The ordering of the comments in the Facebook comments block.

DISQUS

  • DISQUS shortname: The shortname of your DISQUS account. In order to enable DISQUS comments on your system you need to have a DISQUS account. Visit https://disqus.com/ for more information.
  • DISQUS Developer mode: This tells DISQUS to render in developer mode. This is usefull while developing in a local environment like a local web server which is not accessible from the web. In production environments you need to set this to "Disabled".

Social Auto Post Settings

In this section you will find options affecting the auto post features of SocialConnect.

  • AutoPost layout: This allows you to select the layout of SocialConnect auto post widget. The auto post widget is displayed when editing a K2 item or a Joomla! article and allows you to share the content of the item ( or article ) being edited to one or more of the supported social networks. Currently SocialConnect auto post supports Facebook and Twitter only.

Facebook

  • Post content to Facebook: Set this to "Enabled" if you want to enable the Facebook option to the auto post widget. This requires that you have authorized your Facebook application to post content.
  • Post on behalf of: Here you can authorize your Facebook application to post content using the auto post widget to a Facebook account timeline or to a Facebook page. Click the link named "authorize" and follow the steps as guided by Facebook. Once you complete the process the authorization pop up window will close and you will get a list of the available accounts you can use with auto post widget. Note that in order to be able to authorize your Facebook application you need to already have setup a Facebook application in the "Social Login Settings".

Twitter

  • Post content to Twitter: Set this to "Enabled" if you want to enable the Twitter option to the auto post widget. This requires that you have authorized your Twitter application to post content.
  • Post on behalf of: Here you can authorize your Twitter application to post content using the auto post widget to a Twitter account. Click the link named "authorize" and follow the steps as guided by Twitter. Once you complete the process the authorization pop up window will close and you will see the screen name of the Twitter account you authorized. Note that in order to be able to authorize your Twitter application you need to already have setup a Twitter application in the "Social Login Settings".


Advanced Settings

  • For social logins only, generate usernames from:
    • The user's full name. The account of the user will be created using his full name as username. Note that the full name is the name provided by the social network used to sign in.
    • The user's email address. The account of the user will be created using his email address as username. Note that the email is the email provided by the social network used to sign in.
    • The user's email address encrypted. The account of the user will be created using a hash of his email address as username. Note that the email is the email provided by the social network used to sign in.
    • A unique number plus a social network identifier. The account of the user will be created using a generated username based on the social network name and the identifier of the user in that network. For example, users that sign in using a Facebook account will get a username like "xxxxxx@facebook".
Note that SocialConnect does not create any user accounts. SocialConnect just signs in the user. However,  Joomla! is creating a user account for every user that signs in. If you want to change that behavior you can edit the plugin "User - Joomla!" and set the setting named "Auto-create Users" to "No".


System Settings

Here you can find settings regarding the general behavior of SocialConnect.

  • StopForumSpam.com integration for user logins: If you enable this, every time a user signs in to your site will be checked for spam activity using the stopforumspam.com API. For more information on this you can visit http://www.stopforumspam.com/ .
  • cURL connect timeout: The number of seconds PHP cURL wait while trying to connect. Use 0 to wait indefinitely. This is an advanced setting and usually should not be changed unless you are facing issues while using SocialConnect. You can read the section of this document titled “Troubleshooting” for more information.
  • cURL timeout: The maximum number of seconds to allow PHP cURL functions to execute. This is an advanced setting and usually should not be changed unless you are facing issues while using SocialConnect. You can read the section of this document titled “Troubleshooting” for more information.
Here you can find settings that can help you tweaking your system to avoid issues while using SocialConnect. For more information on this please read the section of this document titled “Troubleshooting”.

Permissions

SocialConnect integrates Joomla! 2.5/3.x permissions system providing the actions “Configure” and “Access Administration Interface”.

Usage

There are two ways for adding SocialConnect to your site. The first one is using SocialConnect module and the second one is creating a menu link to SocialConnect component. In both cases there are some settings that affect SocialConnect functionality. These settings are common and are covered later in this document.

SocialConnect Module

This is the most common way to add a login block to your site. In order to do this you need to create a module instance of the SocialConnect Login module.

SocialConnect Component

This is an alternative way for adding SocialConnect to your site. It may be useful when you want to have a dedicated login page instead of a login block. In order to do this you need to create a standard Joomla! menu link to the SocialConnect component.

Settings

Both of the above methods have identical settings. Lets see them in details:

  • Template. Here you can choose the template you wish for the rendering of SocialConnect. The available options here vary depending on the context (module or component) and the available templates to your system. You can learn more about SocialConnect templates by reading the section titled “Templates” of this document.
  • Introduction message. Using this option you can show an introduction message to the visitors of your site. Usually this is being displayed by the SocialConnect template in the beginning of the SocialConnect block. The available options here are:

    • None. Do not display the message at all.
    • Use Default. Display a default text message. The message is coming from the SocialConnect language file.
    • Use custom. Display a custom message. Use this so you can type your own message.
  • Custom Introduction message. Here you type the custom introduction message you wish. This field is a WYSIWYG editor under Joomla! 2.5/3.0 and a textarea under Joomla! 1.5. In order to display this message you need to set the “Introduction messagesetting to “Use custom”.
  • Registration message (SocialConnect component only). Using this option you can show a message to the visitors of your site to encourage them register. Usually this is being displayed by the SocialConnect template right before the registration button. The available options here are:

    • None. Do not display the message at all.
    • Use Default. Display a default text message. The message is coming from the SocialConnect language file.
    • Use custom. Display a custom message. Use this so you can type your own message.
    Custom Registration message (SocialConnect component only). Here you type the custom registration message you wish. This field is a WYSIWYG editor under Joomla! 2.5/3.0 and a textarea under Joomla! 1.5. In order to display this message you need to set the “Registration messagesetting to “Use custom”.
  • Sign in message (SocialConnect component only). Using this option you can show a message to the visitors of your site to encourage them sign in to your site. Usually this is being displayed by the SocialConnect template right before the sign inform. The available options here are:

    • None. Do not display the message at all.
    • Use Default. Display a default text message. The message is coming from the SocialConnect language file.
    • Use custom. Display a custom message. Use this so you can type your own message.
    Custom Sign in message (SocialConnect component only). Here you type the custom sign in message you wish. This field is a WYSIWYG editor under Joomla! 2.5/3.0 and a textarea under Joomla! 1.5. In order to display this message you need to set the “Sign in messagesetting to “Use custom”.
  • Footer message (SocialConnect module only). Using this option you can show a message to the visitors of your site. Usually this is being displayed by the SocialConnect template in the end of the SocialConnect module. The available options here are:

    • None. Do not display the message at all.
    • Use Default. Display a default text message. The message is coming from the SocialConnect language file.
    • Use custom. Display a custom message. Use this so you can type your own message.
    Custom Footer message (SocialConnect module only). Here you type the custom footer message you wish. This field is a WYSIWYG editor under Joomla! 2.5/3.0 and a textarea under Joomla! 1.5. In order to display this message you need to set the “Footer messagesetting to “Use custom”.
  • Login Redirection URL. Select a menu item of your site to redirect the user after a successful login.
  • Logout Redirection URL. Select a menu item of your site to redirect the user after a successful logout.
  • Encrypt Login Form. Submit encrypted login data (requires SSL). Do not enable this option if Joomla is not accessible using the https:// protocol prefix.
  • Render Menu. Select a Joomla! menu to be rendered when user is logged in.

Templates

Youcanuse HTML and CSS template overridesinsideyour Joomla! templateandcompletelychange the way SocialConnect elements display on your website! You can either choose to use the versatile base styling of the bundled SocialConnect templates or simply override them (boththe HTML and CSS code). Below are the instructions to make SocialConnect overrides depending on the SocialConnect usage (module or component).

Module Templates

Module templates resist in the directory /modules/mod_socialconnect/tmpl. SocialConnect module comes with two ready to use templates.

In order to override the built in module templates you can simple copy /modules/mod_socialconnect/tmpl/TEMPLATE folder within your Joomla! template's /templates/YOUR_JOOMLA_TEMPLATE/html/mod_socialconnect folder. Whatever changes yo udo from now on within this folder, will completely override the SocialConnect output, exactly as you would with any other MVC module.

Alternatively you can create your own template by placing your template folder to /templates/YOUR_JOOMLA_TEMPLATE/html/mod_socialconnect. There is no need to place your template to the module templates directory.

SocialConnect module uses two layouts one for guests and one for authenticated users along with one associated CSS file. You are able to override all files or selected files, as you would with any other MVC module, with the better exception that SocialConnect overrides CSS files as well!

Below you can see the file structure of a SocialConnect module template folder:

authenticated.php

default.php

/images

/css

/–– style.css

If you maintain this structure within /templates/YOUR_JOOMLA_TEMPLATE/html/mod_socialconnect/TEMPLATE you can override the entire module output!

Component Templates

Component templates resist in the directory /components/com_socialconnect/templates. SocialConnect component comes with three ready to use templates.

In order to override the built in component templates you can simple copy /components/com_socialconnect/templates/TEMPLATE folder within your Joomla! template's /templates/YOUR_JOOMLA_TEMPLATE/html/com_socialconnect folder. Whatever changes you do from now on within this folder, will completely override the SocialConnect output, exactly as you would with any other MVC component.

Alternatively you can create your own template by placing your template folder to /templates/YOUR_JOOMLA_TEMPLATE/html/com_socialconnect. There is no need to place your template to the component templates directory.

SocialConnect component uses four layouts one for guests and one for authenticated users, one for the ning login and one for the twitter login process. It also has one CSS file. You are able to override all files or selected files, as you would with any other MVC component, with the better exception that SocialConnect overrides CSS files as well!

Below you can see the file structure of a SocialConnect component template folder:

authenticated.php

default.php

ning.php

twitter.php

/images

/css

/–– style.css

If you maintain this structure within /templates/YOUR_JOOMLA_TEMPLATE/html/com_socialconnect/TEMPLATE you can override the entire component output!

Troubleshooting

In case you are facing issues with SocialConnect there are some simple steps you can take in order to resolve them. SocialConnect prints the error messages on the screen in order to help you identify the cause of the issue. In general there are two kind of issues that you may face while using SocialConnect.

Server/Network errors

The first kind of issues has to do with server/network setup that is preventing SocialConnect to communicate with the social networks it integrates. SocialConnect uses PHP's cURL functionality to make requests to the social networks. In case you get such an error (“Name lookup failed” for example) you can try to tweak PHP settings to resolve it. SocialConnect provides two settings under it's configuration:

  • cURL connect timeout. The number of seconds PHP cURL wait while trying to connect.
  • cURL timeout. The maximum number of seconds to allow PHP cURL functions to execute.
Try to set both of those values to a high enough value (100 for example) if you are facing server/network issues.

Social network errors

This is the other kind of issues you may face while using SocialConnect. If you get an error message like “401: Failed to validate oauth signature and token” then that means that you have not setup correctly the social network you are trying to authenticate with. In that case read again the corresponding section of this document regarding the setup of the specific network and check again that you have completed everything as it is required.