Integrating with template overrides

Why template overrides?

Login buttons

This only applies on Joomla 3.

As noted in the overview, the default way for integrating Social Login buttons to your site is with the automatic button injection. While this is a good, simple start for basic sites it's not looking very clean and may outright break if you have more advanced login modules. For example, any kind of popup / dialog box login will be most likely broken with automatic button injection.

In these more advanced use cases we strongly recommend using template overrides. If you are not sure what this means, check out the official documentation on template overrides. This page assumes you know how to use this fundamental Joomla! customisation feature.

Link / Unlink buttons

As noted in the overview, our system plugin extends the XML form of the user profile page rendered by Joomla's com_users (Users) component to display a section with the SocialLogin link/unlink buttons.

If you are using a third party extension to display a user profile page this may not be possible, depending on how the third party extension is written. As a result, you will need to display these buttons through a template override.

A very important note on overrides

You will see that all of the code snippets below start with code similar to if (class_exists(. While technically not necessary we VERY STRONGLY recommend that you always include it. This bit makes a big difference if the Akeeba Social Login system plugin is accidentally unpublished or Joomla! cannot load it (e.g. a file got deleted, wrong file permissions, ...).

If that code bit is present and the system plugin cannot load properly or is disabled nothing will happen. You will simply not see the Social Login buttons.

If, however, you do not include that but and the system plugin cannot load properly your site will die with an PHP Fatal Error. Usually this results in a blank page. Since there's a login module in most pages of your site and your site's administrator login page this can lock you out of your site until you disable all of your template overrides which include Social Login code.

For this reason we recommend that you'd better be safe than sorry and always include that bit of code. Don't file a bug report about this because it is NOT a bug, it's how PHP works (when you ask it to use code which hasn't loaded it throws a Fatal Error because, well, the code isn't loaded, remember?).

Adding login buttons

Joomla 3

Login buttons need to be added to the login modules and the login pages of your site.

IMPORTANT! Remember to set Add buttons to login page to No in the system plugin's configuration.

In the template override of your module you need to add the following code wherever you want the login buttons to appear:

<?php if (class_exists('Akeeba\\SocialLogin\\Library\\Helper\\Integrations')) echo \Akeeba\SocialLogin\Library\Helper\Integrations::getSocialLoginButtons() ?>

If your login module defines a custom URL to redirect to after logging in, let's say $this->successURL, modify the line above to read

<?php if (class_exists('Akeeba\\SocialLogin\\Library\\Helper\\Integrations')) echo \Akeeba\SocialLogin\Library\Helper\Integrations::getSocialLoginButtons($this->successURL) ?>

If your login module also defines a custom URL to redirect to if there's an error logging in, let's say $this->failureURL, modify the line above to read

<?php if (class_exists('Akeeba\\SocialLogin\\Library\\Helper\\Integrations')) echo \Akeeba\SocialLogin\Library\Helper\Integrations::getSocialLoginButtons($this->successURL, $this->failureURL) ?>

WARNING! Replace $this->successURL and $this->failureURL with the actual variable names used by your module. Most likely it's something different. If unsure, check its documentation or consult its developer.

Joomla 4 and later

As noted, our code DOES NOT render the login buttons in Joomla 4. Our code simply responds to the onUserLoginButtons event which was added in Joomla 4. Plugins responding to this event convey all the information Joomla needs to render additional login buttons such as WebAuthn (included in Joomla), SocialLogin etc.

If your extension does not render these buttons please talk to its developer. They need to update its code for Joomla 4. There is nothing you can do with an override.

Adding link / unlink buttons

Joomla 3

These buttons are normally rendered by injecting a sub-form into the com_users profile edit page. This is the best way to do it for Joomla's com_users. However, if you're using a different software for managing user profile editing you will need to do a template override and add the following code:

<?php if (class_exists('Akeeba\\SocialLogin\\Library\\Helper\\Integrations')) echo \Akeeba\SocialLogin\Library\Helper\Integrations::getSocialLinkButtons() ?>

If your third party software allows you to edit other users' profiles you will also need to pass the JUser object of the user account being edited. For example, if that object is in the $this->user variable you should change the line to:

<?php if (class_exists('Akeeba\\SocialLogin\\Library\\Helper\\Integrations')) echo \Akeeba\SocialLogin\Library\Helper\Integrations::getSocialLinkButtons($this->user) ?>

If, instead, you are only given a numeric user ID, let's say $this->user_id, you should instead pass \JFactory::getUser($this->user_id). Therefore the line above becomes:

<?php if (class_exists('Akeeba\\SocialLogin\\Library\\Helper\\Integrations')) echo \Akeeba\SocialLogin\Library\Helper\Integrations::getSocialLinkButtons(\JFactory::getUser($this->user_id)) ?>

Joomla 4 and later

These buttons are normally rendered by injecting a sub-form into the com_users profile edit page. This is the best way to do it for Joomla's com_users. However, if you're using a different software for managing user profile editing you will need to do a template override and add the following code:

<?php if (class_exists(\Akeeba\Plugin\System\SocialLogin\Library\Helper\Integrations::class)) {
echo \Akeeba\Plugin\System\SocialLogin\Library\Helper\Integrations::getSocialLinkButtons()
} ?>

If your third party software allows you to edit other users' profiles you will also need to pass the User object of the user account being edited. For example, if that object is in the $this->user variable you should change the line to:

<?php if (class_exists(\Akeeba\Plugin\System\SocialLogin\Library\Helper\Integrations::class)) {
echo \Akeeba\Plugin\System\SocialLogin\Library\Helper\Integrations::getSocialLinkButtons($this->user)
} ?>

If, instead, you are only given a numeric user ID, let's say $this->user_id, you should instead pass \Joomla\CMS\Factory::getContainer()->get(UserFactoryInterface::class)->loadUserById($this->user_id ?: 0). Therefore the line above becomes:

<?php if (class_exists(\Akeeba\Plugin\System\SocialLogin\Library\Helper\Integrations::class)) {
echo \Akeeba\Plugin\System\SocialLogin\Library\Helper\Integrations::getSocialLinkButtons(
    \Joomla\CMS\Factory::getContainer()->get(UserFactoryInterface::class)->loadUserById($this->user_id ?: 0)
)
} ?>

Upgrading from earlier versions

In version 1 the Integrations class used to display buttons was named SocialLoginHelperIntegrations. In version 2.0.0 it was namespaced and got renamed to \Akeeba\SocialLogin\Library\Helper\Integrations. You will need to change your code, otherwise the buttons will not display at all.

In version 4 the namespace prefix changed from \Akeeba\SocialLogin to \Akeeba\Plugin\System\SocialLogin, following Joomla 4's extension namespace conventions. If you have existing template overrides you just need to change this namespace prefix. Moreover, please remember that the getSocialLoginButtons method no longer exists.