Ping SDKs

Step 5. Instantiate the widget

To use the Ping (ForgeRock) Login Widget in your app you must choose an appropriate place to mount it. Then, you need to choose which form factor to implement, either inline, or modal.

With those decisions made, you can instantiate the Ping (ForgeRock) Login Widget in your app, ready for your users to start their authentication or self-service journey.

Choose where to mount the Ping (ForgeRock) Login Widget

To implement the Ping (ForgeRock) Login Widget, we recommend you add a new element into your HTML file.

For most single page applications (SPA) this is your index.html file.

This new element should be a direct child element of <body> and not within the element where you mount your SPA.

Example HTML structure
<!DOCTYPE html>
<html lang="en">
<head>
<!-- ... -->
</head>
<body>
    <!-- Root element for main app -->
    <div id="root"></div>

    <!-- Root element for Widget -->
    <div id="widget-root"></div>

    <!-- scripts ... -->
  </body>
</html>

We recommend that you do not inject the element into which you mount the modal form factor in your app. This can cause virtual DOM issues.

Instead, manually hard-code the element in your HTML file.

To use the default Ping (ForgeRock) Login Widget modal form factor, import the modules into your app and instantiate the widget as follows:

Instantiate the modal form factor
// Import the Login Widget
import Widget, { configuration } from '@forgerock/login-widget';

// Configure SDK options
const myConfig = configuration();

myConfig.set({
  forgerock: {
    serverConfig: {
        baseUrl: 'https://openam-forgerock-sdks.forgeblocks.com/am',
        timeout: 3000,
    },
    // Optional but recommended configuration:
    realmPath: 'alpha',
    clientId: 'sdkPublicClient',
    redirectUri: window.location.href,
    scope: 'openid profile email address'
    },
  },
});

// Get the element in your HTML into which you will mount the widget
const widgetRootEl = document.getElementById('widget-root');

// Instantiate Widget with the `new` keyword
new Widget({
  target: widgetRootEl,
});

This mounts the Ping (ForgeRock) Login Widget into the DOM. The modal form factor is the default and is hidden when first instantiated.

Top open the modal, import the component module, assign the function, and call its open() method:

Open the modal
// Import the Login Widget
import Widget, { configuration, component } from '@forgerock/login-widget';

// Configure SDK options
const myConfig = configuration();

myConfig.set({
  forgerock: {
    serverConfig: {
        baseUrl: 'https://openam-forgerock-sdks.forgeblocks.com/am',
        timeout: 3000,
    },
    // Optional but recommended configuration:
    realmPath: 'alpha',
    clientId: 'sdkPublicClient',
    redirectUri: window.location.href,
    scope: 'openid profile email address'
    },
  },
});

// Get the element in your HTML into which you will mount the widget
const widgetRootEl = document.getElementById('widget-root');

// Instantiate Widget with the `new` keyword
new Widget({
  target: widgetRootEl, // Any existing element from static HTML file
});

// Assign the component function
const componentEvents = component();

// Call the open() method, for example after a button click
const loginButton = document.getElementById('loginButton');

loginButton.addEventListener('click', () => {
  componentEvents.open();
});

The modal form factor opens and displays a spinner graphic until you start a journey.

The modal form factor closes itself when a journey completes successfully.

You can also close it by calling componentEvents.close();

Instantiate the inline form factor

You override the default Ping (ForgeRock) Login Widget modal form factor and instead use the inline form factor. The inline form factor mounts within your application’s controlled DOM, so it is important to consider how your framework mounts elements to the DOM.

For example, the inline form factor cannot mount into a virtual DOM element, such as those used by React. In this scenario, you must wait until the element has been property mounted to the real DOM before instantiating the Ping (ForgeRock) Login Widget.

To use the inline form factor, instantiate the widget with a type: 'inline' property, as follows:

Instantiate the inline form factor
// Import the Ping (ForgeRock) Login Widget
import Widget, { configuration } from '@forgerock/login-widget';

import { useRef } from 'react';

// Configure SDK options
const myConfig = configuration();

myConfig.set({
  forgerock: {
    serverConfig: {
        baseUrl: 'https://openam-forgerock-sdks.forgeblocks.com/am',
        timeout: 3000,
    },
    // Optional but recommended configuration:
    realmPath: 'alpha',
    clientId: 'sdkPublicClient',
    redirectUri: window.location.href,
    scope: 'openid profile email address'
    },
  },
});

// Target needs to be an actual DOM element, so ref is needed with inline type
const widgetElement = useRef(null);

// Instantiate Widget with the `new` keyword
new Widget({
  target: widgetElement.current,
  props: {
    type: 'inline', // Override the default 'modal' form factor
  },
});

The inline form factor loads into the specified DOM element and displays a spinner graphic until you start a journey.

Next

Next, you can Step 6. Start a journey.