Coding the Widget Appearance

Available to:

For customers planning to build their own share widget, an API is provided to allow building the widget functionality into the website code. Implementing the widget in this way is a two-step process. First, build the widget into the website with the desired look and feel. Then, add the JavaScript code required to facilitate sign-in and sharing.

The Social Sharing Widget works by first authenticating the user, and then sending share data. The loginAndSend call is used in conjunction with an onClick event, or associated with a button to start the process.

The following simplified example provides an overview of the process and a generalized guide to how the API will work with your code.

When implementing the widget in code, use of the dashboard is still required to configure the Identity Providers, Share Mode, and widget code. After that configuration is complete (see thee Social Sharing Widget User’s Guide for more information), follow these steps:

Configuring the Widget — This step includes selecting Identity Providers and specifying the widget’s appearance.
Coding the Widget Interface — Code is generated to be placed into the website hosting the Social Sharing Widget.

The following sections describe these steps.

Configuring the Widget ¶

To prepare a widget for using code not designed in the Dashboard, you must first disable the settings set by the Dashboard. The custom call is used to turn off all settings, and allows only the login, send, and loginAndSend calls to work. For further information on these functions, see the Sharing Widget JavaScript API page.

Sign in to your application.
On the Configure Widget page, select the Embed this configuration in JavaScript code option.
Click Generate the Code.
On the Get the Code page, copy and paste the first snippet of code into the <head> section of the website.
Add the custom function to the settings code, set to “true”, in the editable area: janrain.settings.share.custom = true; See Code Example 1. There is no need to place the <div> code snippet.

Code Example: Adding the Custom Call to Override Settings

<script type="text/javascript">

(function() {
    if (typeof window.janrain !== 'object') window.janrain = {};
    if (typeof window.janrain.settings !== 'object') window.janrain.settings = {};
    if (typeof window.janrain.settings.share !== 'object') window.janrain.settings.share = {};
    if (typeof window.janrain.settings.packages !== 'object') janrain.settings.packages = ['share'];
    else janrain.settings.packages.push('share');

    /* _______________ can edit below this line _______________ */

    janrain.settings.share.custom = true;
    janrain.settings.share.providers = ["facebook, yahoo"];
    janrain.settings.share.providersEmail = ["yahoo"];
    janrain.settings.share.modes = ["broadcast"];
    ...

Coding the Widget Interface ¶

This step involves creating a button interface for the widget and then adding functionality with JavaScript and the loginAndSend function.

Creating the Interface for the Widget ¶

This example uses a simple HTML button interface, as shown in Figure 1.

<button id="shareFacebook">Click to post this message on Facebook!</button>

Figure 1: Basic Code and Interface

Using JavaScript with loginAndSend to Define the Button ¶

The next step is using loginAndSend to add widget functionality.

For Code Example 2, JavaScript is used to link the button ID shareFacebook with loginAndSend. The share information and behavior is set in the script. Place in the <head> of the website, under the existing widget code.

Code Example: Using loginAndSend

<script>
var janrainShareOnload = function() {
  var facebookButton = document.getElementById("shareFacebook");
  facebookButton.onclick = function() {
    janrain.engage.share.loginAndSend({
      "provider":"facebook",
      "mode":"broadcast",
      "contacts":[],
      "title":"AOL",
      "url":"http://aol.com",
      "description":"The best web service ever",
      "message":"You've got mail!",
      "image":"http://aol.com/logo.png",
      "media":"http://aol.com/promo.swf",
      "actionLink":{
        "name":"Instant Message",
        "link":"http://aim.com/"
      }
    });
  };
};
</script>

Creating More Complex Buttons ¶

The functionality of loginAndSend is also split into two separate calls called login and send.

login – Initiates the Engage sign-in process, authenticating the user with the webpage.
send – Initiates the sharing flow with providers.

By separating the functionality, the widget may have a button for signing in a user, and a button for sending data.

For more information on the API, refer to the Widget page.