Skip to content

Embedding API

The Embedding API can be used to embed a {{ shortProductName }} form directly in another webpage without using an <iframe>. The {{ shortProductName }} form will be inserted into the DOM of the hosting page and can be interacted with using the {{ shortProductName }} JavaScript API or any custom JavaScript. Additionally, the style of items in the {{ shortProductName }} form can be customized by the CSS of the hosting page.

Example 1 - Declarative

<html> 
…  
<body>
   … 
   <div id="myLeapDiv"> <!-- {{ shortProductName }} form will go here --> </div> 
   …
   <script src="https://leap.example.com/apps/api/leap.js" 
    data-leap-config="{launch: {appId: 'e9ec1ed3-c12b-4b5c-8f5e-7a6ff4800a55', formId: 'F_Form1', targetId: 'myLeapDiv'}}">
   </script> 
</body> 
</html>

Example 2 - Programmatic

<html> 
… 
<body> 
  …
  <div id="myLeapDiv"> <!-- {{ shortProductName }} form will go here --> </div> 
  …
  <script src="https://leap.example.com/apps/api/leap.js"></script> 

  <script> 
    function onLeapFormSubmitted (BO) 
    { 
      alert ("submitted record id: " + submittedBO.getDataId());       
    } 

    function onLeapFormLoaded (app, launchParams) 
    { 
      app.getForm(launchParams.formId).connectEvent("afterSave", onLeapFormSubmitted); 
    } 

    Leap.onReady = function() { 
      var launchParams =  
      { 
      appId: 'e9ec1ed3-c12b-4b5c-8f5e-7a6ff4800a55', 
      formId: 'F_Form1', 
      target: document.getElementById("myLeapDiv"), 
      locale: 'fr-FR' 
      callback: onLeapFormLoaded 
      }; 
      Leap.launch(launchParams);  
    }; 

  </script> 

</body> 
</html>

Loading the {{ shortProductName }} Embedding UI { .section}

<script src="https://leap.example.com/apps/api/leap.js" data-leap-config="[leap configuration]" id="leapJS'"></script>
  • id (optional) - fallback for older browsers; the value should always be "leapJS"
  • data-leap-config (optional) - JSON or the name of an existing JavaScript object. Properties:
    • locale (optional) - indicates the preferred locale to the {{ shortProductName }} API. For example, "fr-FR"
    • launch (optional) - equivalent to calling Leap.launch({…}) function with respective parameters (see below for more details)
    • overwriteExistingDojoConfig (optional) - In some environments, such as HCL Digital Experience or IBM WebSphere Portal, the djConfig or dojoConfig object may be defined on a page and not used. Set the value of this property to true to override it.

Loading the {{ shortProductName }} API will result in the creation of global object named Leap.

After initial load of the leap.js, you can define a Leap.onReady() function which will be called when the necessary {{ shortProductName }} resources have been loaded into the page and the API is ready to be used.

Embedding a form programmatically

To embed a {{ shortProductName }} form programmatically, call Leap.launch({launch_params});

{launch_params} properties:

Property Required? Description
appId Yes The {{ shortProductName }} application UUID.
For example, 'e9ec1ed3-c12b-4b5c-8f5e-7a6ff4800a55'
formId Yes The {{ shortProductName }} form ID.
For example, 'F_Form1'
recordId No The {{ shortProductName }} record ID.
For example, 'f7ab2ca2-c12b-4b5c-8f5e-7a6ff4800b69'
targetId Either target or targetId must be provided. The id of the HTML DOM element to embed the {{ shortProductName }} form within.
For example, 'myLeapFormDiv'
target Either target or targetId must be provided. The HTML DOM element to place the {{ shortProductName }} form within.
mode No Determines the mode for embedding. Possible values:
  • 'iframe': embeds the form in an <iframe> element. For complete isolation of the form, if necessary
  • 'embed' (default): embeds the form into the hosting page in a <div>
locale No Indicates the preferred locale for the embedded form.
For example, 'fr-FR'
prefSecMode No If the form supports both anonymous and authenticated usage, this property can be used to automatically choose the preferred security mode. Possible values:
  • 'anon': for anonymous usage
  • 'secure': for authenticated usage
callback No A callback function which will be called when the application launch completes successfully and the form is ready to be interacted with. The callback function will be passed the following parameters:
  • app: the {{ shortProductName }} JavaScript API application object.
  • launchParams: the original launch parameters object, for convenience

Known Limitations

  • Only one {{ shortProductName }} form can be embedded on the page at a time.
  • Once the {{ shortProductName }} form is embedded, it cannot be changed to a different form or reloaded.
  • The hosting page cannot contain any version of the Dojo JavaScript library. The {{ shortProductName }} Embedding API will load its own copy of the Dojo JavaScript library into the hosting page.
  • For authentication, it is expected that the hosting page and the {{ shortProductName }} server are configured with single sign-on (SSO). {{ shortProductName }}’s login UI will not display properly within the hosting page.
  • The embedding API cannot be set to an App Page

Cross-Domain Usage

If {{ shortProductName }} and the hosting page are in different domains, the {{ shortProductName }} front-end must be configured to return appropriate CORS headers.

Parent topic: Reference