Tamaro: How to customize the Widget

Change default Colors and add your own Styles

The easiest way to change the style is adding your own CSS styles. There are many CSS variables, which can be tailored to your needs. Be careful CSS variables are not supported in IE11 and other older browser versions. But we take care of the compatibility, you just have to use the :root selector. A list of available variables are shown below:

:root {
  # Title, background color of numbering and selected UI elements such as checkboxes and radio buttons
  --tamaro-primary-color
 
  # Defines the color for links, e.g. change currency
  --tamaro-primary-color__hover
 
  # Primary background color for selected areas
  --tamaro-primary-bg-color
 
  # Primary text color
  --tamaro-text-color
 
  # Background color for hover
  --tamaro-bg-color__hover
 
  # Primary color for borders
  --tamaro-border-color
 
  # Primary color for input field placeholders
  --tamaro-placeholder-color
 
  # Sets the color for text which are defined within an information container 
  --tamaro-info-text-color
 
  # Sets the color for info icons (e.g. CVV and instructions of credit card)
  --tamaro-info-icon-color
 
  # Sets the color for labels and underlines if an error appears
  --tamaro-error-color
 
  # Colors for default buttons, for instance the cancel button in the recurring dropdown.
  --tamaro-button-color
  --tamaro-button-color__hover
  --tamaro-button-bg-color
  --tamaro-button-bg-color__hover
  --tamaro-button-border-color
  --tamaro-button-border-color__hover
 
  # Colors for primary buttons, for instance the submit button.
  --tamaro-button-primary-color
  --tamaro-button-primary-color__hover
  --tamaro-button-primary-bg-color
  --tamaro-button-primary-bg-color__hover
  --tamaro-button-primary-border-color
  --tamaro-button-primary-border-color__hover
}

The widget has a CSS namespace `tamaro-widget`. If you want to override styles you should use this prefixes in your style to have a higher styles specifiy. Have a look at the following example:

#tamaro-widget.tamaro-widget {
 background-color: #ccc;
}

Implement Custom Event Handlers

The following events are available:

• beforeLoad - Before the widget resources get loaded
• afterLoad - After the widget resources were loaded
• beforeCreate - Before the widget instance is created
• afterCreate - After the widget instance is created
• beforeRender - Before the widget is rendered
• afterRender - After the widget is rendered
• purposeChanged - Purpose changed
• amountChanged - After the amount has changed
• currencyChanged - Currency changed
• paymentTypeChanged - Changed to one-off or recurring
• recurringIntervalChanged - Interval changed
• paymentMethodChanged - Payment method changed
• beforePaymentValidateAndSend - Before payment form has been validated and sent
• beforePaymentValidate - Before payment form has been validated
• paymentValidateSuccess - After payment form has been validated successfully
• paymentValidateError - After payment form has been validated with errors
• beforePaymentSend - Before payment form has been sent
• paymentComplete - After payment has been completed
• subscriptionUpdateComplete - After subscription has beeb updated
• subscriptionCancelled - After subscription has been cancelled

To subscribe to an event you have to define a function (handler), which will be called, when the event occurs. In the example below we subscribe to the `currencyChanged` event:

function currencyChangedHandler(event) {
  console.log("The currency was changed, let's have a look at the event, which comes with ", event)
}
 
window.rnw.tamaro.events["currencyChanged"].subscribe(currencyChangedHandler)

//or

window.rnw.tamaro.events.currencyChanged.subscribe(currencyChangedHandler)

You can also pass an anonymous function as a callback to subscribe to an event. The code above can be rewritten as defined below:

window.rnw.tamaro.events["currencyChanged"].subscribe(function(event) {
   console.log("The currency was changed, let's have a look at the event, which comes with ", event)
})

All events, except  `beforeLoad`, `afterLoad`, `beforeCreate` come with the identical set of data, which includes the widget api. The widget api provides all necessary methods to interact with the widget, transaction and subscriptions.

Event is an object, that comes with two properties: `eventName` and `data`. Data contains the api object of the widget, which includes all collected properties of the widget. The most important property is computedConfig, which contains all params, that the widget has got during the initialization process.  Almost all values can be changed manually via the browser's console or by passing a config object as second argument to the `runWidget` function.

After a payment has been made, the paymentComplete event is triggered. You can access the details of a payment transaction using the object transactionInfo:

window.rnw.tamaro.events["paymentComplete"].subscribe(function(event) {
   console.log("transaction info object ", event.data.api.transactionInfo)
   console.log("transaction is identified by the epp_transaction_id ", event.data.api.transactionInfo.epp_transaction_id)
   console.log("transaction status is defined as follows: ", event.data.api.transactionInfo.epayment_status)
   console.log("transaction status is defined as follows: ", event.data.api.transactionInfo.epayment_status)

})

Customize Configuration

The examples below will show you how can change the configuration of the widget.

Change the Language

To switch to another language define the language ISO 639-1 Code in the config object as shown below:

<script>
 window.rnw.tamaro.runWidget('.rnw-widget-container', {
 language: 'de',
 })
</script>

Show Debug Panel

To see the debug panel set the `debug` parameter to`true`. 

All available options can be set as config parameters or can be selected in the`Debug panel`.

Let's have a look at the most important options:

• language - set current language
• layout - Currently there is only one layout available called list and second layout step will be available soon which renders each section in a dedicated step.
• flow - you may specify a payment flow that should be used for all payments. Currently there are three methods: redirect, iframe, popup. The widget will try to use it, if possible, otherwise fallback to a supported flow (not all payment methods support all payment flows). We recommend to use redirect fl
• overlay_mode - some data in the widget should be shown in overlays. This option sets how this overlay should look like. 
  outer - overlay will be shown as modal dialog (it's set by default). 
  inner - overlay will be shown in-place instead of on top of the other blocks.
• test_mode - set this option to make a test payment or when you working locally for a test. This option has to be removed or set to false for production payments.
  
  

<script>
 window.rnw.tamaro.runWidget('.rnw-widget-container', {
 debug: true,
 layout: 'list',
 flow: 'redirect',
 overlayMode: 'outer',
 debugSlots: true,
 debugErrorMessages: true,
 debugStyles: true
 })
</script>

To facilitate debugging of data you can set `Debug styles` option.  `Debug error message` shows all possible error messages. `Debug slots` shows all places where you can add as additional component as field. To see all computed configuration parameters just click on the config link in the Debug panel. To see all available translations click on the Translations link.

Conditions in Configuration

Some of the config properties can be defined by using conditions.

These are the most used conditions: 

• amount()
• paymentMethod()
• paymentType()
• recurringInterval()
• purpose()
• currency().

A condition dynamically gets a value from the widget and based on the resulting value you can for instance either show or hide some of elements of the widget.

As an example - let's override the payment methods. Three payment methods will be shown: Credit Card,  PostFinance and SMS. The latter will only be shown when the following condition evaluates to true: If selected amount is greater than 100, SMS method will be hidden otherwise it will be shown. Check out the full example:

<script>
  window.rnw.tamaro.runWidget('.rnw-widget-container', {
    paymentMethods: [
      "cc",
      "pfc",
      {
        "if": "amount() < 100",
        "then": "sms"
      },
    ]
  });
</script>

 That was easy, wasn't it?

Let's try the next one: Based on a selected purpose we want to have different payment methods available: The SMS payment method will only be shown when the first purpose is selected. The condition we will use for that is `purpose()`:

<script>
window.rnw.tamaro.runWidget('.rnw-widget-container', {
  paymentMethods: [
    "cc",
    "pfc",
    {
      "if": "purpose() == p1",
      "then": "sms"
    },
  ]
});
</script>

If you need to show different values of amounts based on the selected currency - use currency() in the condition as in the example below:

<script>
window.rnw.tamaro.runWidget('.rnw-widget-container', {
  amounts: [
    {
      "if": "currency() == usd",
      "then": [5,10,50,100],
    },
    {
      "if": "currency() == chf",
      "then": [10,15,60,80],
    },
    {
      "if": "currency() == eur",
      "then": [15,20,80,100],
    },
  ]
});
</script>

A condition usually consists of operators and methods. The character > is an operator.
There are many operators that you're already used to and some that might be new to you.
New operators can easily be added to the Compiler class.
Besides operators, there are methods. The `amount()` expression is a method.
Methods are simple functions that may, or may not, take arguments and return a value.
New methods can easily be added like this: 

rnw.tamaro.compiler.addMethods({
 date: () => new Date().toLocaleString()
})

You might write conditions either in traditional or functional format, for example,
traditional: 1 < 2 and 3 > 2,
functional: and(lt(1, 2), gt(3, 2)).

List of available operators:

List of available methods:

Configuration options

List of all available configuration options, based on the WidgetConfig class. Please be aware that in Javascript we use camelCase where as defined in YAML we use snake_case for the parameter names.

No matter what config formats you've used, widget will merge them all together using this priority: Runtime > JavaScript > YAML and create a new config object based on those three. It is accessible trough the widget instance `window['widget'].computedConfig`. Do not try to override any values on the `computedConfig` object, since your changes will be overwritten as soon as the the config recomputates, use `window['widget'].config` instead. Be aware that config does not support a deep merge. So if you overwrite an object within the config, you have to provide the whole sub config of this object.

Adding Hidden Parameters

If you need to pass a hidden parameter along with a transaction just add it to the paymentFormPrefill property:

<script>
  window.rnw.tamaro.runWidget('.rnw-widget-container', {
    paymentFormPrefill: {
      stored_hidden_parameter: "myValue"
    }
  });
</script>

This parameter will be attached to a transaction with a value "myValue".

Slots

Within slots you can create new fields. There are various slots available, please turn on the `debug` option and click on `Debug slots` option to make them visible 

Customize Translations 

To see all available translations make sure that `debug` option is turned on. Then click on the `Translations` link in the `Debug section`.

You can define your own translations within the config object. In the following example we overwrite the labels of three purposes.

Field Component - Adding Custom Fields

This component is used to add different form fields. The following types can be used:  

• `text`
• `radio`
• `radio-group`
• `radio-in-group`
• `checkbox`
• `checkbox-group`
• `checkbox-in-group`
• `select`

Adding a Text Field

For example, if you decided to add the company name input field in the profile form you can choose one of the slots, for instance profile_form_1. Your code will look as below: 

<script>
  window.rnw.tamaro.runWidget('.rnw-widget-container', {
    debug: true,
    slots: {
      profile_form_1: [{
        component: "field",
        type: "text",
        name: "stored_customer_company_name",
        label: "payment_form.stored_customer_company_name",
        placeholder: "payment_form.stored_customer_company_name"
      }]
    },
  });
</script>

Where:

• `slots` - a property where custom fields can be added.
• `component` - the name of the component
• `type` - type of the component.
• `name` - name of the field in the form
• `label` and `placeholder` - a translation key

Before using any custom fields, make sure you have defined them inside the paymentFormPrefill config section:

<script>
  window.rnw.tamaro.runWidget('.rnw-widget-container', {
  ...
  paymentFormPrefill: {
    stored_customer_company_name: null
  }
  ...
  });
</script>

Adding a Radio Group

Let's add a radio group, combining `radio-group` and `radio-in-group` types. That will be a radio group to select the type of the company.

<script>
  window.rnw.tamaro.runWidget('.rnw-widget-container', {
    debug: true,
    paymentFormPrefill: {
      stored_customer_company_name: null,
      stored_customer_type: null,
    },
    translations: {
      en: {
        payment_form: {
          stored_customer_type: 'Customer type',
          stored_customer_types: {
            private: 'private',
            public: 'public',
          },
        },
      },
    },
    slots: {
      profile_form_1: [{
        component: "field",
        type: "radio-group",
        name: "stored_customer_type",
        label: "payment_form.stored_customer_type",
        children: [{
          component: 'field',
          type: "radio-in-group",
          name: "stored_customer_type",
          text: "payment_form.stored_customer_types.private",
          value: 'private',
        }, {
          component: 'field',
          type: "radio-in-group",
          name: "stored_customer_type",
          text: "payment_form.stored_customer_types.public",
          value: 'public',
        }],
      },
    ]},
  });
</script>

Where:

• `children` - an array of components
• `text` - a translation key
• `value` - a value of a field

Adding a Checkbox

Now we will add a checkbox to accept terms and conditions.

<script>
  window.rnw.tamaro.runWidget('.rnw-widget-container', {
    debug: true,
    paymentFormPrefill: {
      stored_customer_accept_terms: false,
    },
    translations: {
      en: {
        payment_form: {
          stored_customer_accept_terms: 'I accept terms and conditions type',
        },
      },
    },
    slots: {
      profile_form_end: [{
        component: "field",
        type: "checkbox",
        name: "stored_customer_accept_terms",
        text: "payment_form.stored_customer_accept_terms",
      },
    ]},
  });
</script>

Where:

• `type` - type of the component
• `text` - a translation key

Adding a Select

Let's add a select component, which allows to choose between Yes or No.

<script>
    window.rnw.tamaro.runWidget('.rnw-widget-container', {
    debug: true,
    paymentFormPrefill: {
      stored_customer_drop_donations: null,
    },
    translations: {
      en: {
        payment_form: {
          stored_customer_drop_donations: 'Do you want to drop your donations?',
          drop_donations_options: {
            yes: "I want to drop my donations",
            no: "I don't want to drop my donations"
          }
        },
      },
    },
    slots: {
      profile_form_start: [{
        component: "field",
        type: "select",
        name: "stored_customer_drop_donations",
        label: "payment_form.stored_customer_drop_donations",
        options: [
          {value: 'yes', label: 'payment_form.drop_donations_options.yes'},
          {value: 'no', label: 'payment_form.drop_donations_options.no'}
        ],
      },
    ]},
  });
</script>

Where:

• `type` - type of the component
• `options` - an array of options, that contains both a value and a label

Validation

We are able to add custom fields but what about an opportunity to validate them. Let's try to implement a custom validation rule.

There is a list of available validate methods, which can be used: `alpha`, `numeric`, `alpha_numeric`, `alpha_dash`, `numeric_dash`, `alpha_numeric_dash`, `format`, `email`, `accepted`, `required`, `in`, `nin`.

We gonna have a look at each of them:

• `alpha` - allows you to validate if a given value contains only alphabetical characters;
• `numeric` - to validate if a given value contains only digits and no other characters;
• `alpha_numeric` -  allows you to validate if a given value contains both alphabetical and digits characters;
• `alpha_dash` - if a given value contains alphabetical characters and a dash;
• `numeric_dash ` - if a given value contains only digits characters and a dash;
• `alpha_numeric_dash` - if a given value contains alphabetical, digits characters and a dash;
• `format` - to validate a given value as a regex expression;
• `email` - check if a given value is an email address;
• `accepted` - a given value can be considered only as `"yes"`, `"on"`, `"1"` `1`, `"true"`, `true`;
• `required` - a filed is required to be filled;
• `in` - a check if a given value exists in a certain range;
• `nin` - a check if a given value doesn't exist in a certain range;

Validation of Custom Fields

In the following example we will create a custom `Company Code` field, which will have the following properties:

• type - text
• name - stored_customer_company_code
• label - Company Code.

We are going to add this new filed to the `profile_form_start` slot. To see all possible slots turn `Debug slots` option on. Don't forget to put this custom field into the `paymentFormPrefill` section. Let's add all this to the config object and add it as argument to the runWidget function:

<script>
  window.rnw.tamaro.runWidget('.rnw-widget-container', {
    slots: {
      profile_form_start: [{
        component: "field",
        type: "text",
        name: "stored_customer_company_code",
        label: "payment_form.stored_customer_company_code",
        placeholder: "payment_form.stored_customer_company_code"
      }]
    },
    paymentFormPrefill: {
      stored_customer_company_code: null,
    },
    translations: {
      en: {
        payment_form: {
          stored_customer_company_code: 'Company code',
        },
        validation_errors: {
          stored_customer_company_code: {
            field_has_wrong_format: 'No valid code, only four digits',
            field_is_missing: 'Type a company code',
          }
        },
      },
    },
  });
</script>

Now, let's decide what rules we should use to validate this field. We will define two rules:

1. This field is required to be filled - so we will define the `required` rule.
2. Furthermore the field must consist of four digits. For that we can use the `format` rule.

We are ready to summarize and get down to do that. To validate a custom field we can use the event `afterCreate` and passing the above defined rules to paymentValidations  as in the example below:

function setupCustomFieldValidation(event) {
  var widget = window['widget'] = event.data.api;
  var paymentValidations = window.rnw.tamaro.toJS(widget.computedConfig.paymentValidations);

  
  // adding rules for a custom field
  paymentValidations['stored_customer_company_code'] = {
    required: true,
    format: /\d{4}/
  };
  
  widget.config.paymentValidations = paymentValidations;
}

window.rnw.tamaro.events["afterCreate"].subscribe(setupCustomFieldValidation);

We have to add it like this to merge with existing validation rules. If you just overwrite/extend paymentValidations in config object, you will lose all existing validation rules.

Prefill fields via URL Parameters

Each query parameter should have "rnw-" prefix.

Example: https://tamaro.raisenow.com/futurogoal-demo/latest/index.html?rnw-payment_type=recurring&rnw-recurring_interval=yearly

Allowed fields to be prefilled are:

• 'purpose', 'currency', 'payment_type', 'recurring_interval', 'payment_method', 'amount'
• all other custom fields ('stored_<field_name>') if they are present in config.payment_form_prefill object

Fields that are restricted to prefill:

• 'cardno', 'expm', 'expy', 'cvv', 'bankiban', 'bankbic', 'iban', 'payer_line1', 'payer_line2', 'payer_line3', 'payer_line4'