How to configure Custom Widgets Custom Forms

This article focuses on how to configure Custom Widgets Custom Forms, a specific step of the Custom Widget set-up. 
This content is also available in our developer portal. 

Definition

The custom widget form is a custom configurator your team has built when it has created a custom widget. 

As a reminder, a custom widget is a piece of code developed in the AB Tasty platform. 

Once created, this snippet can be used in every kind of campaign (test, personalization) and be customized to fit the campaign’s purpose. 

Example:

You have created a custom widget named Shop opening announcement pop-in to have a custom pop-in already ready in AB Tasty, each time you need to announce the opening of a brand new shop on your company website. 

You need to fix one part of the set-up of this custom widget (the way it is triggered, its general layout, the cross’s store, etc.), but you would like to let some fields be customizable to help your marketing team to customize it easily, without having to dig in the code.

To get an invitation, you should make the following items customizable: the name of the city, the date and time of the opening, and the label of the CTA. As a result, you will need to create a custom form to let your colleagues customize only this information.

Configuration Step

Custom widget forms are an array of objects, displayed as a form.

The custom widget feature works as follows: 

1. A technical user of the account creates a custom widget from scratch by configuring the JS, HTML, and CSS code; 
2. At the end of the configuration, he chooses what kind of fields should be customizable and how to customize them (color, words, etc.);
3. He fills in the Form code box to create this custom form.

Properties​

Defined properties to display forms:

type

Character string

Defines the type of form that will be displayed.
Find the list of allowed types in this article

propName

Character string

Key that will be used in the DATA object to get the value

label

Character string or object 

Defines the label of your form. It will be displayed to help the user understand the purpose of the form. It supports strings but also objects to translate into the following languages: English (en), French (fr), Spanish (sp), and German (de).

value

Any - Form’s default value

Here is an example with a simple text input :

const buttonTextForm = {
   type: 'text',
   propName: 'buttonText',
   label: 'Button text',
   value: 'This is a simple text input',
};

Specific properties to build your look and feel configurator

When you set up your form, you want to make it as easy as possible to be understood and used by your colleagues. 

For example, you should add section titles, descriptions, and separators to make the customization of the custom widget more guided. 

Here are the properties you should add to structure your final form:

Titles

The title snippets should be added right above the first property of the section and right above the separator of the previous section.

Description

The description snippets should be added right after the title snippet and right above the first property of the section.

Separator

The separator snippets should be added right after the last property of the section and right before the title snippet of the next section.

List of propname Fields and Their Specificities​

areainput​

👉 Displays a list of input numbers

It is primarily used to define box-model dimensions (top, right, bottom, left) for many uses, margins, padding, positioning, etc.

value: array containing an object
The number of elements in your object will define the number of inputs. Input labels are object keys and the values are the key/values from the object.

const paddingForm = {
   type: 'areainput',
   label: 'Container padding',
   propName: 'containerPadding',
   value: [{ top: 35, left: 60, bottom: 35, right: 60 }],
};

checkbox​

👉 Displays a checkbox in the form

value: checkboxes do not have a value property but a checked property instead, which is a boolean

const triggerOnPageLoadForm = {
   type: 'checkbox',
   label: {
       en: 'Page load',
       fr: 'Au chargement de la page',
       es: 'Al cargar la página',
       de: 'Beim Laden der Seite',
   },
   propName: 'pageLoad',
   checked: true,
};

codeeditor​

👉 Displays a code editor input
You can specify the code type (JS or CSS).

value: character string

Specific Property

rows: enables you to define the number of rows to display by default in the UI.

export const triggerEventCustomScript = {
   type: 'codeeditor',
   label: 'Custom Trigger JavaScript Code',
   propName: `TriggerEventCustom`,
   value: `
       async function launchIfScroll() {
           return new Promise(resolve => {
               document.addEventListener('scroll', () => resolve(true), {once: true});
           });
       }
       const result = await launchIfScroll();
       return resolve(result);`,
   rows: 15
   };

colorpicker

👉 Displays a color picker

value: character string

const backgroundColorForm = {
   type: 'colorpicker',
   label: 'Background color',
   propName: 'backgroundColor',
   value: "rgba(247, 247, 247, 1)",
};

datepicker​

👉 Displays a simple date picker

value: date object or valid date string

DATA value: Date.tostring()
const inputDate = {
   type: 'datepicker',
   label: 'Pick a date to display',
   propName: 'date',
   value: new Date(),
};

datetimepicker​

👉 Displays an all-in-one date and time picker, enabling you to get a requested date and time from users.
Can be used for a countdown, for instance.

value: date object or valid date string.
An empty date string will use the current date as the default value.

return value: Unix timestamp

const inputDateTime = {
   type: 'datetimepicker',
   label: 'Pick a date and time to display',
   propName: 'datetime',
   value: '',
};

datetimetimezonepicker​

👉 Displays a datetimepicker, in addition to a collapsed group to set further information :

• a toggle to follow the sun (will end at this time in each timezone or not)
• a selection input to choose a timezone when needed (when the "follow the sun" toggle is off)

value: object with two properties at init :

• type: should be set to init on the form part
• value: same as datetimepicker but also allows a GMT timezone string

DATA value: a complete object

• previewTimestamp: timestamp number (value to be used for the editor preview when the "follow the sun" toggle is on)
• type: local or global value, depending on whether the "follow the sun" toggle is on or off.
• timecustom widgets: object, in numbers, corresponding to the minute, hour, day, month, or year.
• raw: object with all data:
• followTheSun: boolean
• previewTimezone: character string for geolocation timezone
  Ex: 'Europe/Paris' (value to be used for the editor preview when "follow the sun" toggle is on)
• timedef: object. Same as timecustom widgets.
• timezone: character string for geolocation timezone
  ex: 'America/Los_Angeles'
• userContext: object with complete data related to the current user:
• isInDST: boolean describing whether the user is currently in daylight - saving time or not.
• local: object similar to timecustom widgets but with current user date and time values
• offset: number resulting from getTimezoneOffset
• timestamp: timestamp number
• timezone: character string for geolocation timezone
  ex: 'Asia/Tokyo'

const inputDateTimeTimeZone = {
   type: 'datetimetimezonepicker',
   label: 'Pick a date and time to display',
   propName: 'datetimeTimezone',
   value: {
       type: 'init',
       value: '+0100'
   },
};

hidden​

👉 Hides an input 

value: character string

const hiddenInput = {
   type: 'hidden',
   value: window.innerHeight,
   propName: 'innerHeightSetup',
};

inlinenotification​

👉 Displays information to the user about the features of your form or custom widget

value: This custom widget does not need a value property.

Specific Properties:

label: character string corresponding to the message to be displayed

hrefUrl: character string corresponding to the URL you want the user to be redirected to

const documentationNotification = {
   type: 'inlinenotification',
   label: 'Click here to access documentation',
   hrefUrl: 'https://developers.abtasty.com/',
};

number​

👉 Displays an input of type number

value: number

Specific Properties: 

You are also able to provide more properties:

min: number (default value is 0);

max: number (default value is 9999);

step: number (default value is 1).

const zindexCustomForm = {
   type: 'number',
   label: 'Custom z-index value',
   propName: 'zindexCustom',
   value: 1,
   min: -2147483647,
   max: 2147483647,
};

paragraph​

👉 Displays text into the form.
It can be used to inform, alert, and so on

value: no value is needed in this case. 

Content should be placed in the text property - character string.

const styleHelper = {
   type: 'paragraph',
   text: `In that part you can add styles to your custom widget.`,
};

radio​

👉  Displays a radio input with multiple radios

value: character string || number || boolean

Specific Property for Radio: 

options [Array of objects: {label: type label, value: same as value}]

const insertPositionForm = {
   type: 'radio',
   label: 'Select where to insert the custom widget compared to selected element',
   propName: 'insertPositionType',
   value: 'afterbegin',
   options: [
       {
           label: 'Before selected element',
           value: 'beforebegin'
       },
       {
           label: 'At the beginning of selected element',
           value: 'afterbegin'
       },
       {
           label: 'At the end of selected element',
           value: 'beforeend'
       },
       {
           label: 'After selected element',
           value: 'afterend'
       }
   ]
};

radioImage​

👉 Display a radio input with images/icons as buttons

value: character string

Specific Property: options are the same as for radio label and style
The character string should be long or short, depending on the desired button size.

const textAlignmentForm = {
   type: 'radioImage',
   label: 'Text alignment',
   propName: 'textAlign',
   value: 'center',
   style: 'little',
   options: [
       {
           label: 'Left',
           value: 'left',
           src: `https://widgets-images.abtasty.com/style/icon-text-alignLeft.png`
       },
       {
           label: 'Center',
           value: 'center',
           src: `https://widgets-images.abtasty.com/style/icon-text-alignCenter.png`
       },
       {
           label: 'Right',
           value: 'right',
           src: `https://widgets-images.abtasty.com/style/icon-text-alignRight.png`
       }
   ]
};

searchselect​

👉 Displays a select that includes a search input for selects that have several values

value: character string

Specific Property:options are the same as for radio

Specific Options Properties:

placeholder: character string.
Text to be displayed when the search field is empty.

const textFontNameForm = {
   type: 'searchselect',
   label: 'Select font',
   propName: 'fontName',
   value: 'inherit',
   placeholder: 'Search for a font',
   options: [
       {
           'label': 'Inherited from element',
           'value': 'inherit',
           'description': '',
       }
       {
           'label': 'Roboto',
           'value': 'Roboto',
           'description': '12 styles',
       },
       {
           'label': 'Open Sans',
           'value': 'Open Sans',
           'description': '10 styles',
       },
       {
           'label': 'Lato',
           'value': 'Lato',
           'description': '10 styles',
       },
       {
           'label': 'Montserrat',
           'value': 'Montserrat',
           'description': '18 styles',
       },
   ],
};

select​

👉 Displays a select

value: character string

Special Property: options are the same as for radio

const backgroundPositionForm = {
   type: 'select',
   label: 'Background position',
   propName: 'backgroundPosition',
   value: 'center',
   options: [
       {
           label: 'Top',
           value: 'top'
       },
       {
           label: 'Bottom',
           value: 'bottom'
       },
       {
           label: 'Center',
           value: 'center'
       },
       {
           label: 'Left',
           value: 'left'
       },
       {
           label: 'Right',
           value: 'right'
       },
   ]
};

selectelement​

👉 Displays an input used to fill selectors containing a button.
It will enable the user to select a website element.

value: character string (more likely formatted as a CSS selector)

const triggerEventClick = {
   type: 'selectelement',
   label: 'Select the element that will trigger the custom widget on click'
   propName: `triggerElementClick`,
   value: 'body',
};

slider​

👉 Displays a slider to select a number as a value

value: number

Specific Properties: min and max of type Number
Both are optional. The default values are 0 and 100.

const borderWidthForm = {
   type: 'slider',
   label: 'Border width',
   propName: 'borderWidth',
   value: 2,
   min: 0,
   max: 50,
};

switch​

👉 Displays a switch that enables the user to select an option

value: boolean

const displayCloseButtonSwitchForm = {
   type: 'switch',
   label: 'Display close button',
   propName: 'closeButton',
   value: true,
};

textarea​

👉 Displays a text area that enables the user to enter text

value: character string

Specific Property: rows of Number type to define the number of rows of your textarea

const textContentForm = {
   type: 'textarea',
   label: 'Text to set in your custom widget',
   propName: 'textContent',
   value: `Your message goes here.
Keep it short and to the point. Make short sentences.
Invite your users to consider your idea.
You can do multi-line messages.`,
   rows: 6,
};

text​

👉 Displays a simple text input

value: character string

const buttonTextForm = {
   type: 'text',
   label: `Button's text`,
   propName: 'buttonText',
   value: 'See the offer',
};

url​

👉 A text type input dedicated to the URL
Format checking and error handling are managed by default.

value: character string

const linkForm = {
   type: 'url',
   label: `Button's URL`,
   propName: 'redirectionUrl',
   value: window.location.origin,
};

wysiwyg​

👉 Displays a textarea input enriched with text styling features

value: character string

const custom widgetTextContent = {
   type: 'wysiwyg',
   label: 'Text',
   propName: 'content',
   value: `Your message goes here. Keep it short and to the point. Make short sentences. Invite your users to consider your idea.
​​​​​​​You can do multi-line messages.`,

};