bridge-middletier

Bridge Middletier

Bridge Middletier is a custom framework for eCommerce pages and is used to integrate with Maestro’s transaction server. Bridge will control the user flow through an eCommerce page. It provides a gateway for creating prospects and processing orders, as well as a series of utilities often used in eCommerce pages.

The compiled library is hosted on Github. Cloudflare is used to serve the files to the front end.

 

Resources

 

Deploying

Deploying is scripted via NPM. (clear-cache.sh and deploy.sh will need executable permissions before running).

$ npm run deploy

 

Usage

A bundled and minified version of Bridge must be imported into each page of an eCommerce site, not including terms, privacy, contact pages. Bridge is also dependant on jQuery, therefore jQuery must be imported above Bridge in every offerpage.

  <script id='bridge-controller' src='https://bridge-middletier.xyz/dist/v1/bridge.min.js' data-url='<URL of a Maestro Instance>'></script>
  <link rel='stylesheet' href='https://bridge-middletier.xyz/dist/v1/bridge.min.css'>

The imports for Bridge must be in this format. The script import uses id='bridge-controller' to identify the controller, and the data-url attribute will represent the desired instance of Maestro’s transaction server URL (in the format of: somedomain.com). This will be passed to Transaction.js and used to make calls to Maestro’s API.

*See modules below for details on integrating an eCommerce page with Bridge.

 

Transaction.js

Transaction.js is the bridge between eCommerce pages and Maestro. It provides three forms preconfigured to properly connect with Maestro’s transaction server. Using these forms, an eCommerce page can, create prospects, create initial orders and create additional orders. It will also automatically package additional information required to place orders, such as site id, IP address etc.

All forms emit a spinner-on event on submission and a spinner-off event if error after submission. These events are used to control the visibility of the Spinner.js processing spinner.

Transaction.js and Maestro use a JSON Web Token to pass information between the eCommerce page and the browser. Interaction with the token is usually not necessary as all interaction is handled automatically in Bridge, however this token may be read to retieve user information, such as name and address. See the Utilities GetUserInfo section for details on reading the token.

Below are details on integrating an eCommerce page.

Site Id

Maestro requires a site id to be present for every call to its API. This site id must be present in the url as a parameter ?id=xxxx and must only be present in the url on the first page load. This site id will be immediately retrieved and stored in the browser’s sessionStorage for later use by Bridge. If no site id is present, Maestro will respond with an error message.

Forms

Integrating with the three forms requires several steps.

  1. Identify the form with the appropriate id.

  2. Provide an input for each required field.

  3. Insure the inputs have the required attribute (if appropriate).

  4. Insure the form does not have the no validate attribute.

Identifying the Form

To identify a form, provide one of the options as the form’s id attribute. There are three options of form to choose from.

The use of forms must follow the flow of ProspectForm -> PaymentForm -> UpsellForm. More than one UpsellForm can be used if needed however a PaymentForm must always be used before any UpsellForms can be used.

Providing Required Inputs

Each form has its own required inputs. Forms also have an optional hidden input named nextPage that can control the next page to go to after this form is submitted. If nextPage is not provided, Bridge will follow the default page flow of: index.html -> payment.html -> promo.html -> ../receipt.html. In most situations, nextPage does not need to be used.

ProspectForm

<form id='ProspectForm'>
  <!-- OPTIONAL -->
  <input type='hidden' name='nextPage' value='some-page.html'>

  <!-- REQUIRED -->
  <input name='firstName' required>
  <input name='lastName' required>
  <input name='address1' required>
  <input name='city' required>
  <select name='state' required></select>
  <input name='zip' required>
  <input name='phone' required>
  <input name='email' required>
</form>

PaymentForm - *Important. Each eCommerce page must provide its own logic for making the billing address fields required based on the value of billingSameAsShipping.

<form id='PaymentForm'>
  <!-- OPTIONAL -->
  <input type='hidden' name='nextPage' value='some-page.html'>

  <!-- REQUIRED -->
  <input type='hidden' name='productCode' value='some-product-code'>
  <input type='radio' name='billingSameAsShipping' value='yes' checked>
  <input type='radio' name='billingSameAsShipping' value='no'>
  <input name='creditCardNumber' required>
  <select name='creditCardType' required></select>
  <select name='expiryMonth' required></select>
  <select name='expiryYear' required></select>
  <input name='CVV' required>

  <!-- REQUIRED IF (billingSameAsShipping === 'no') -->
  <input name='billingFirstName'>
  <input name='billingLastName'>
  <input name='billingAddress1'>
  <input name='billingCity'>
  <select name='billingState'></select>
  <input name='billingZip'>
</form>

UpsellForm

<form id='UpsellForm'>
  <!-- OPTIONAL -->
  <input type='hidden' name='nextPage' value='some-page.html'>

  <!-- REQUIRED -->
  <input type='hidden' name='productCode' value='some-other-product-code'>
</form>

 

Validation.js

A preconfigured validation library. Give your form inputs the required names and Validation.js will do the rest.

Validation.js will apply a valid or invalid image on all Input or Select elements after a user has changed the elements value, indicating a valid or invalid value.

It will also apply number only and min/max length rules for elements 'zip', 'phone', 'creditCardNumber' and 'CVV', automatically setting their type to tel.

*Important

Maestro requires most form inputs to be required. Each eCommerce page will be responsible for setting the appropriate inputs as required and must insure that no validate IS NOT set on the form.

Please see Transaction.js for full information on proper form integration.

 

Modal.js

Modal.js is a simplifed popup window framework used for displaying Terms & Conditions, Contact, Privacy Policy etc in a closable popup modal, without leaving the current page, lowering user bounce rates.

To use a modal, create an anchor tag with the class 'bridge-modal' and the path to the desired page as the href. Bridge will open this link in a popup modal. Use this for all footer links, or links to any terms, privacy pages.

<a href='path-to-file.html' class='bridge-modal'>Click Here</a>

 

Mobile-Redirect.js

Mobile-Redirect.js will redirect a user to/from the desktop/mobile versions of an eCommerce page, based on the screen size of their device.

function redirectIfMobile(path?: string);
function redirectIfDesktop(path?: string);

Redirecting a User

From a desktop page:

<!--redirects the user to the mobile version if they are on mobile-->
<script>redirectIfMobile()</script>

From a mobile page:

<!--redirects the user to the desktop version if they are on desktop-->
<script>redirectIfDesktop()</script>

*Important

Only make these function calls from the index page of each version (desktop or mobile). It will redirect using the default folder structure (/desktop/mobile). If a different redirect path is needed, each function will accept a new path as an argument. In most situations, the default path will work. This function call must be placed below the import for Bridge.js.

 

Spinner.js

Spinner.js is a processing spinner triggered by spinner-on/spinner-off events emitted by Transaction.js. It will automatically appear after submitting any of the three forms provided by Transaction.js. No setup is required

The processing spinner contains a default message, however this can be overridden with a custom message by calling the spinnerText({}) function and providing header, body or footer values. To override the default message, this function call will need to be on every page where the processing spinner pop up will be present.

function spinnerText(message: { header?: string, body?: string, footer?: string });

Example:

<script>
  spinnerText({
    header: 'Header text',
    body: 'Body text',
    footer: 'Footer text'
  })
</script>

 

Utilities

Bridge contains several utilities in Javascript and CSS

Utilities.js

The following are general utility functions provided by Bridge.

GetUserInfo

This function returns the decoded contents of the Transaction.js JSON Web Token as an object. It accepts an optional parameter JSON web token string for development purposes. In production, no parameter is required.

function GetUserInfo(token?: string);

Example:

const user = GetUserInfo()

console.log(user.firstName)
console.log(user.lastName)
console.log(user.email)

Utilities.css

The following are general utility css classes provided by Bridge.