Embedding API

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

Example 1 - Declarative

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

Example 2 - Programmatic

<html> 
… 
<body> 
 
<div id="myVoltDiv"> <!-- Volt form will go here --> </div> 

<script src="https://volt.example.com/volt-apps/volt.js"></script> 

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

  function onVoltFormLoaded (app, launchParams) 
  { 
	 app.getForm(launchParams.formId).connectEvent("afterSave", onVoltFormSubmitted); 
  } 

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

</script> 
 
</body> 
</html>

Loading the Embedding UI

<script src="https://volt.example.com/volt-apps/volt.js" data-leap-config="[volt 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 Volt API. For example, fr-FR
    • launch (optional) - equivalent to calling Volt.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 API will result in the creation of global object named Volt.

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

Embedding a form programmatically

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

{launch_params} properties:

Property Required? Description
appId Yes

The Volt application UUID.

For example, e9ec1ed3-c12b-4b5c-8f5e-7a6ff4800a55
formId Yes

The Volt form ID.

For example, F_Form1
targetId Either target or targetId must be provided.

The id of the HTML DOM element to embed the Volt form within.

For example, myVoltFormDiv
target Either target or targetId must be provided.

The HTML DOM element to place the Volt 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 JavaScript API application object. For more details, see Interface objects
  • launchParams - the original launch parameters object, for convenience

Known Limitations

  • Only one Volt form can be embedded on the page at a time.
  • Once the Volt 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 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 Volt server are configured with single sign-on (SSO). Volt’s login UI will not display properly within the hosting page.

Cross-Domain Usage

If Volt and the hosting page are in different domains, the Volt server (or its front-end technology) must be configured to return appropriate Cross-Origin Resource Sharing (CORS) headers.

The typical technique for enabling a cross-domain solution is to ensure the appropriate Access-Control-* response headers are returned. These response headers inform the browser that the Volt server will allow requests to be made to it from a HTML page hosted in a different domain.

For example, with Apache HTTP Server, add the following to httpd.conf:
Header set Access-Control-Allow-Origin "https://volt-embed.example.com"
Note: For security reasons, only return the minimal set of CORS headers that are required your solution.

See Cross-Origin Resource Sharing (CORS) for more information.