Combi-Action™ Button Developers Guide

A new interaction paradigm and seamless touchpoint for personalising customer experience:

  • affective/cognitive rating of the main action (ex. Subscribe, book, add to cart, wish-list,…”)
  • can capture real-time customer insights in a collaborative mode
  • can help enrich the customer profile and user journey personalization

 

Combi-Action™ button is a patent pending technology of B-sm@rk Ltd.

Introduction

The Combi-Action™ button v1 provides an easy integration of a submit button target.

multi-action-button

Figure 1

The Combi-Action™ button (or multi-action button) replaces a standard button and is made of five different areas (buttons):

  • Button 0: center
  • Button 1: top left
  • Button 2: top right
  • Button 3: bottom left
  • Button 4: bottom right

It is possible to bind a specific action to each button, this could be:

  • opening a simple link in the same or in a new browser tab,
  • executing a custom JavaScript function,
  • submitting a form.

Our Combi-Action™ button is specifically designed to let users perform two actions in one.

For example: the button in the search feature of a travel agency website can be replaced with the Combi-Action™ button. The user, after having written the destination to search for, can either click on the center button to perform a regular search, or give some more information selecting one of the four side buttons.

These side buttons can be customized by the host site and can contain emotions, short sentences, etc… The host site can do different actions, reacting accordingly if a user selects “I hope to find a good deal” or “I value comfort” while looking for a trip to New York.

The appearance of the Combi-Action™ button is completely customizable. There is a basic CSS file that will shape the element as in Figure 1, this is to ensure the presence of a style for a basic usage. It is possible to define custom styles, some examples will be shown in this guide.

Embedding

To embed the Combi-Action™ button in your page, you first need to identify the regular button you would like to replace. In the HTML, the button must have a unique ID set to it.

Add the following code at the very end of your page, just right above the closing </body> tag:

<script>
var MultiActionButton_Config = {
		buttonId: "searchBtn",
		containerClass: "v10",
		buttons: [
			{image: "img/lens.png"},
			{label: "Button 1"},
			{label: "Button 2"},
			{label: "Button 3"},
			{label: "Button 4"}]};
</script>
<script src="https://www.mysmark.com/js/MultiActionButton.js"></script>

This will create a configuration object for the button, and load the JavaScript library from our servers.

The Combi-Action™ button is configurable by a variable called “MultiActionButton_Config” set before its loading. The module will read it and, if everything was set up correctly, eventually replace the regular button with the multi-action one.

Configuration parameters for “MultiActionButton_Config”:

 

PropertyMandatory?Default valueTypeNotes
buttonIdYesStringThe ID of the regular button to replace
buttonsYesArray.<Object>See next chapter
spinnerIdNoFalseBooleanThe ID of the element to show as “loading” after one clicks the CAB
injectBaseCSSNoTrueBooleanSet this to false if you don’t want the JavaScript module to inject the base CSS for the CAB
containerClassNoNullStringThe HTML “class” attribute to give to the CAB container

 

ONLY IN DEVELOPMENT ENVIRONMENTS: you can set to true a variable called “MultiActionButton_Debug” to receive useful messages in the JavaScript console. In case the CAB won’t initialize, a human-readable error will be reported there. If the variable is set to false or does not exist at all, nothing will be output to the console, which is the desired behavior in a production environment.

Buttons Configuration

The “buttons” array is a list of objects which describes each button. The list is ordered and the first object will be Button 0, the second object will be Button 1, and so on. You can specify more than five buttons, but the extra ones won’t be displayed by default.

A button object must have at least a “label” OR “image” property set. If an image is set, it will display as in the center button in Figure 1, while a text label will display as the rest of the buttons. You can specify images for any button, not only for the one in the center.

A button also requires an action to fire on a click event. If a suitable action is not found, the CAB won’t initialize.

The following are actions you can specify:

  • opening a simple link,
  • executing your own JavaScript function,
  • submitting a form.

 

It important to note that the CAB must replace an <input> (or <button>) element inside a form, to allow submitting it on click.

Example code:

buttons: [
	{image: "images/lens.png"},
	{label: "Open link on this tab", href: "test.php?clicked=btn1"},
        {label: "My Callback", callback: myCallback},
	{label: "Open link in new tab", href: "test.php?clicked=btn3", target: "_blank"},
	{label: "Submit form"}
]

If the CAB is replacing a button inside a form:

  • Button 0 has a “lens.png” image and will submit the form on click,
  • Button 1 has a text label and will open the set URL in the same tab,
  • Button 2 has a text label and will execute the myCallback() function on click,
  • Button 3 will open the set URL on a new tab,
  • Button 4 will submit the form.

 

If the CAB is not inside a form, it won’t be initialized in this case, as there are buttons without a valid action set (Button 0 and 4). If no action is set, “form submission” is the default one.

If you have enabled the debug mode, you should receive a clear error message in this last case.

Styling

The CAB comes with a predefined, basic CSS. If you simply embed the CAB, the JavaScript will ensure to inject the CSS file in your page automatically.

However, it is recommended you add this <link> element manually to your page to optimize its loading to your users.

In the same page of the CAB, add the following code inside the <head> section:

 

<link href="https://www.mysmark.com/css/modules/embed/multi-action-button.css" type="text/css" rel="stylesheet">

 

If you do so, the JavaScript module won’t inject it on the “document ready” event, you don’t need to set the injectBaseCSS property to false too in this case, as the detection of the basic CSS is automatic.

If you have your own CSS file which overrides most if not every style rule of the basic one, you can simply add your file in the head section and then set injectBaseCSS to false. In this way the only CSS managing the style of the CAB is the one you specified.

If you wish to use the basic CSS, you can either leave containerClass null or set it to “v10”, which is a version of the CAB that comes in the basic CSS. If you want to use your own CSS, we suggest you use a unique class name to set your rules and then add it in containerClass.

Custom Styles

The easiest way to modify the appearance of the CAB is to start from the base CSS we offer and then override a few rules.

Make sure to manually include your CSS file in the head section of the page. It doesn’t matter if you also include the base CSS or not since the JavaScript will do it for you if you haven’t specifically set injectBaseCSS to false. In any case, we recommend you do something like this:

 

<link href="https://www.mysmark.com/css/modules/embed/multi-action-button.css" type="text/css" rel="stylesheet">
<link href=”css/my-own-mab-style.css” type=”text/css” rel=”stylesheet”>

 

When writing your style, it’s good practice to always specify the container class of the CAB so that you don’t accidentally target other elements outside of it, plus a class name of your choice. If you wish for example to change the color of the center button, you can do the following:

 

.combibtn.myOwnClass .neutral {
	background-color: #e24257;
	border-color: #e24257;
}

 

Remember to set containerClass in the configuration object to “myOwnClass”! The rule you’ve just seen is targeting the center button having “combibtn” and “myOwnClass” as classes of the general container element. The “combibtn” class is always added by default, while your class name must be specified in the configuration. This will keep your code tidy and modular, separated by the original CAB one.

We recommend to take a look into the base CSS file to understand what classes are available and what properties are set. In the following list you will find the most useful classes’ names and elements you can override with your own style.

TargetDescription
.combibtnThe external container
.combibtn .neutralThe center button
.combibtn .btnAreaAll the other buttons
.combibtn .btnArea.top-leftSpecifically for Button 1. Useful for setting borders or round corners
.combibtn .btnArea.top-rightButton 2
.combibtn .btnArea.bottom-leftButton 3
.combibtn .btnArea.bottom-rightButton 4

Backend

Now that you have set up the frontend, the backend is straightforward. If the action you’ve set for the buttons is to submit a form, you will receive the user’s choice in your form data. Look in your POST or GET data array for the variable called “MABClicked”, its value is the button clicked.

ButtonMABClicked value
Center0
Top-left1
Top-right2
Bottom-left3
Bottom-right4