Events

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.

Cardinal.on('ui.render', function(){
  // Complete an action when the UI element is rendered
});

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.

{
    "Validated": false,
    "ActionCode": "ERROR",
    "ErrorNumber": 10011
    "ErrorDescription": "Canceled by user"
}

Events

Default

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.

Cardinal

MODAL

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.configure({
  payment: {
    framework: 'cardinal'
  }
});

Inline

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.

Configure

Cardinal.configure({
  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.

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.

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 (details.data.mode) {
            case 'static':
              // Inject Iframe into DOM in visible spot
              container = document.getElementById('my-visible-wrapper');
              break;

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

          break;
        default:
          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
      resolve();
    } 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
    reject(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.

Bootstrap 3

MODAL

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. 

Cardinal.configure({
  payment: {
    framework: 'bootstrap3'
  }
});