|
A page for developers: how the Social Connect plugin enriches the Elgg API |
The Social Connect plugin does most of the work for you. But it still allows Elgg developers to interact with the authentication and registration processes so that customization is possible and easy. First of all we will look at a simple diagram to explain how the plugin interacts with the other elements involved in user access.
Following is a detailed explanation of how user access into Elgg unfolds when you have installed the Social Connect plugin
In any case, the pop-up window is closed and the Elgg page reloaded.
When a user decides to login or register with the Social Connect plugin, the authenticate.php
page is executed in a pop-up window and in the following diagram you can see a visual representation of what goes on inside that page. This diagram is basically a zoom into the "social connect" box from the high level overview picture seen above. The points at which developers can intervene by registering for the Social Connect hook and/or event are represented in solid blue colour.
This image can feel quite crowded, so here's a step-by-step description of what happens in it.
authenticate.php
script is invoked in a pop-up window. It checks that the provider requested is enabled and that the required configuration parameters are all there.mode
of 'login'
to allow developers to do something with the detected Elgg user and connected profile. Depending on the response from the hook, we may move on to either 8A1 or 8AX.mode
of 'connect'
to allow developers to do something with the connected profile. The Elgg user variable is set to null
. Depending on the response from the hook, we may move on to either 8B1, 8B2, 8B3, or 8BX.mode
is 'login'
:true
, the plugin logins the detected user, the popup is closed and the main Elgg page is refreshed. Plugin execution terminates here.false
, developers do not want login to continue or have handled login themselves. The popup is closed and the Elgg page is refreshed, but the plugin takes no further actions. Plugin execution terminates here.mode
is 'connect'
:true
, the plugin registers a new user for this profile. The 'social_connect','user' event is then triggered with a mode
of 'register'
to notify developers of the newly created Elgg user from the connected profile. After that, the popup is closed and the main Elgg page is refreshed. Plugin execution terminates here.'email'
, the plugin proceeds to verify the presence of an email address in the connected profile and can proceed to either 9A1 or 9A2 depending on whether an email address was found or not.'emailOnly'
, the plugin proceeds to verify the presence of an email address in the connected profile and can proceed to either 9B1 or 9BX depending on whether an email address was found or not.false
, developers do not want social connection to continue or have handled the connection themselves. The popup is closed and the Elgg page is refreshed, but the plugin takes no further actions. Plugin execution terminates here.'connect'
. Depending on the response from the hook and whether an email address was present in the connected profile, the following paths are possible:'email'
:mode
of 'register'
to notify developers of the newly created Elgg user from the connected profile. After that, the popup is closed and the main Elgg page is refreshed. Plugin execution terminates here.mode
of 'email'
to notify developers of the newly created connection between an Elgg user and the provider's profile. After that, the popup is closed and the main Elgg page is refreshed. Plugin execution terminates here.'emailOnly'
:mode
of 'email'
to notify developers of the newly created connection between an Elgg user and the provider's profile. After that, the popup is closed and the main Elgg page is refreshed. Plugin execution terminates here.If you are a developer who would like to interact with the functionality of the Social Connect plugin, you can develop your own Elgg plugin and register for the Social Connect hook and/or event like this
// register a handler for the social_connect event elgg_register_event_handler('social_connect', 'user', 'yourplugin_social_connect_event'); // register a handler for the social_connect hook elgg_register_plugin_hook_handler('social_connect', 'user', 'yourplugin_social_connect_hook'); |
Both the hook and the event receive an associate array from the Social Connect plugin with the following structure
// the arguments for social connect events and hooks $args = array( 'mode' => null, 'userid' => $user_uid, 'provider' => $provider, 'user' => null, 'profile' => $user_profile, ); |
The value of $args['userid']
is set to the unique identifier of the current profile in the provider directory.
The $args['profile']
value instead is the HybridAuth object representing the complete provider profile for the user. The amount of information available in the profile depends on the provider and is detailed in the HydridAuth documentation.
The key $args['provider']
finally contains the configuration array for the current provider the user is connecting with.
The above keys are always set in both hook and event invocations. The other values are populated into this structure according to the explanations below.
The hook is invoked when the provider has successfully returned a user profile and after the plugin has verified whether that profile has already been connected to Elgg.
The signature of the callback method is as follows
function yourplugin_social_connect_hook($event, $object_type, $proceed, $args) { } |
The $args
variable contains the data of the structure described above. The $proceed
variable is initially set to true
.
$args['mode']
value is set to 'login'
and $args['user']
is set to the associated ElggUser
instance.$args['mode']
value is set to 'connect'
and $args['user']
is null
.The method should return a boolean value. The $proceed
value is set to true
initially, but you can decide to return false
if you have handled the rest of the process yourself in this method or if you need to return an error for whatever reason.
true
, the plugin continues with the social connection process.false
, the plugin closes the popup window, refreshes the underlying Elgg page and terminates execution.When in 'connect'
mode, the handler can also return 'email'
or 'emailOnly'
instead of a boolean value. With either string, the plugin will check whether the profile has an email address instead of proceeding immediately with the registration of a new user. If an email address is provided and the email address is already registered with Elgg, then the plugin will associate the new provider profile with the existing Elgg user (the mode of the plugin switches to 'email'
). If an email address was not found or the retrieved email address does not exist in Elgg, then the outcome depends on the string.
'email'
, the plugin will proceed to register a new user as normal.'emailOnly'
, the plugin will terminate with an error (and close the popup window and refresh the Elgg page...)When it registers a new user, the plugin changes its mode to 'register'
, whether it's because the hook handler returned true
or because no registered email address matched the current profile.
The event handler is invoked only when the hook was in 'connect'
mode.
The signature of the callback method is as follows
function yourplugin_social_connect_event($event, $object_type, $args) { } |
The event is triggered after the hook has returned a non-false
value in 'connect'
mode. It tells the developer what happened in the connection process.
The mode in the $args
parameter can be one of the following
'register'
: a new Elgg user has been registered into the system. The new user is available in the $args['user']
variable.'email'
: an existing Elgg user has been connected to the current profile because they have the same email address. The associated user is available in the $args['user']
variable.You can use this event to populate the Elgg user object with more information from the provider profile or any other source. The plugin itself will only populate the following fields out of the box