View Frameworks

View Frameworks in Songbird are ways to render a UI element for any product that does not provide its own presentation method. Generally, this means that any alternative payment brand, like Apple Pay or Visa Checkout will render their own UI, but things like CCA will need a mechanism to render the UI on their behalf. Only a single-view framework can be active at one time. For example, you cannot have CCA use a modal view framework and VTS use an inline framework because the UI Manager library has been designed to provide a single cohesive experience to the end user.


As the view engine completes different stages of its life cycle, it will trigger different events the merchant can subscribe to, allowing the merchant to be informed when the view engine changes its state. Most of these events are optional and provide no information to the merchant other than the information that the view engine is actively starting the specific stage. Some of these view events will only be used if specific features are enabled.

All UI events are passive events so you may use the Cardinal.on function to subscribe to them as seen below.

Example of Subscribing to UI event
Cardinal.on('ui.render', function(){
  // Complete an action when the UI element is rendered

Looking for available events?

Refer to the specific type of view framework for more details on what events are available for a given framework.

View Framework Types

Within Songbird, there are different types of view frameworks. A type refers to how the UI will be rendered. As of writing, there are only 2 types but more may be added as Songbird matures.

  • Modal - Lightbox like UI element that floats content above page
  • Inline - Merchant controlled UI where Songbird feeds the UI elements to render to the merchant. For more information on this type, refer to Inline in the implementation section below.

Modal Type

The modal type is the most commonly used UI type. A modal, also commonly known as a lightbox, is a box that appears to float above the page and is typically rendered with a drop shadow over the rest of the page to help draw attention to the content displayed inside the modal. For reference, a screen shot has been included below.

The modal view framework type is one of the more automated types Songbird has to offer. It requires little to no interactions with the merchant to display and clean up content. Generally, the only required interaction for the merchant is to inform Songbird when Songbird should use a specific library to render the modal screen, like Bootstrap.

Close Button

The close button feature will automatically enable a small close X in the top right corner of the modal window.  When this button is clicked, it will close the modal window and trigger the payments.validated event with an error response.  This feature requires the displayExitButton configuration option to be set to work properly.

From a reporting standpoint this will look to be an abandoned transaction. This is because we do not complete any messaging nor submit the authentication screen in any way. The modal is simply disposed of and the merchant informed the user canceled.

payments.validated response example
    "Validated": false,
    "ActionCode": "ERROR",
    "ErrorNumber": 10011
    "ErrorDescription": "Canceled by user"



A standard modal configuration will result in 2 events being triggered

  1. ui.render - Occurs when the modal window is opened
  2. ui.close - Occurs when the modal window is closed and torn down
With Loading Enabled

When using the loading window you will receive 2 additional events

  1. ui.loading.render - Occurs when the modal loading screen is rendered
  2. ui.loading.close - Occurs when the loading modal is closed
  3. ui.render - Occurs when the modal window is opened
  4. ui.close - Occurs when the modal window is closed and torn down

View Framework Implementations

This section reviews the different available view frameworks and how to use them.

Built In Engines

The built in view frameworks are designed and developed by CardinalCommerce, and all necessary files are included in Songbird. They require no additional work to use and can be set by simply configuring Songbird to use the appropriate engine. These view engines are the easiest to use and are recommended for smaller organizations that may not have a desire to customize every aspect of the checkout experience.



This is the default view framework. It is a Cardinal developed and styled simple modal window. You don't need to do anything to use this framework.

Cardinal View Framework
  payment: {
    framework: 'cardinal'


The inline view framework allows the merchant to receive the UI elements from Songbird and inject the elements directly into their page to appear as if their website has rendered the content. This view framework provides the most control over the UI to the merchant, but also requires the merchant to do the most amount of work.


Inline Configuration Example
  payment: {
    framework: 'inline'

Setup Events

With the inline view framework, we need to subscribe to a passive event, ui.inline.setup, for injecting the actual content into the merchants website. This event will receive 4 arguments:

  • Html Template - This is the element that needs to be injected
  • Inline Data Object - An object that describes the current UI experience and how the merchant should render it
  • Resolve function - A function to call when you have successfully injected the html template
  • Reject function - A function to call when you have encountered an error and are unable to inject the html template

The merchant is required to inform Songbird when they have successfully injected the content into the page, or have failed to do so. Songbird will not move forward with the transaction until either the resolve or reject functions have been called. Be sure to have good error handling in this event handler or you could cause the consumer to be stuck if you don't properly call either resolve or reject.

Please be aware

Failure to call the resolve or reject functions may cause the transaction to get stuck. Songbird is waiting for you, the merchant, to tell it when you have finished with this asynchronous task.

The inline data object will contain information related to the current transaction and allow you to intelligently render for specific payment types, and different variations of each payment type. Additionally this object will include the height and width of the html template to allow you to adapt the element receiving the html template accordingly.

Its important to know that html templates injected into the page will be cross domain iframe. This means that if the injected html template is moved after Songbird has started the cross domain rendering, the content within the iframe will be whipped away by the browser. There is nothing Songbird or CardinalCommerce can do about this behavior, it is built into the browsers themselves.

Please be aware

Once the html template has been injected moving the elements around the DOM will cause the content to be deleted by the browser. For more on this please refer to this SO article

ui.inline.setup implementation example
Cardinal.on('ui.inline.setup', function (htmlTemplate, details, resolve, reject) {
  try {    
    var container; // The element we will inject the HTML template into
    if (htmlTemplate !== undefined && details !== undefined) {
      // Depending on your integration you may need to account for other items when processing different payment types
      switch (details.paymentType) {
        case 'CCA':
          // Process CCA authentication screen
          switch ( {
            case 'static':
              // Inject Iframe into DOM in visible spot
              container = document.getElementById('my-visible-wrapper');

            case 'suppress':
              // Inject Iframe into DOM out of view
              container = document.getElementById('my-hidden-wrapper');
              throw new Error("Unsupported inline mode found [" + + "]");

          throw new Error("Unsupported inline payment type found [" + details.paymentType + "]");
      // Because the template we get from Songbird is a string template, we need to inject it as innerHTML
      container.innerHTML = htmlTemplate;
      // Inform Songbird that we have successfully injected the iframe into the DOM and the transaction can proceed forward
    } else {
      throw new Error("Unable to process request due to invalid arguments");

  } catch (error) {
    // An error occurred, we need to inform Songbird that an error occurred so Songbird can abondon the transaction and trigger the 'payments.validated' event with an error

Third Party

The view framework architecture is built in such a way that if the merchant is already using a common view library like Bootstrap, Cardinal can develop a view plugin to leverage the merchants existing implementation of that framework. This means even if Songbird is generating and controlling UI elements like modals, Songbird will use the view library's modal JavaScript to render, open and close the modal.

Please be aware

If you decide to use a 3rd party view framework library like Bootstrap, you are responsible for importing any necessary files required for that library to work. For example if you were using Bootstrap you would need to import the Bootstrap CSS and JavaScript files.

Bootstrap 3


The Bootstrap 3 view framework will render all UI elements in the Bootstrap 3 modal. Please be sure you have fully installed bootstrap on your site already. 

Bootstrap3 View Framework
  payment: {
    framework: 'bootstrap3'