How to create a Custom Widget

A custom widget is a pre-set piece of code that has been totally created with the custom widget creation flow. The generated code is hosted on our servers, but is not deployed on our platform. AB Tasty doesn’t own this piece of code, it only stores it for future purposes and usages: the client owns their development, deployment, sale, and maintenance. For more information about Custom Widgets (options, usage, parameters, examples, ...) please refer to the reference article about Custom Widgets.

How to create a custom widget 

From the Widget library page, click Create a custom widget and fill in the following information:

Main information

  • Custom widget name: give a clear name to easily understand what is inside and to retrieve it within the custom widget library. Each template must have a unique name, but not too long to be able to see it entirely.  (E.g. “Pop-in news”). 
  • Description (optional): you can use this section to be more specific about the goal of the custom widget.  (E.g. “To promote newsletter and collect emails - new branding”. This description will be also visible in the widget library in the editor and on the extended view in the widget library. 
  • Label (optional): the label is displayed on the widget card to enable you to sort them and use the filters. We’re providing a native list of labels such as Promotion but you can also create your own label by clicking on the drop-down, typing your label, and clicking on ENTER. The new label will be visible in the future label choices.
  • Add image (optional): the image is displayed on the widget card as a cover, it’s useful to identify your custom widgets in one look. You can upload your image or drag and drop it from your files.

Configuration

  • JavaScript code section: enter your JS snippet to inject your custom widget on your page.
  • CSS code section: enter your CSS code to customize the UI of your custom widget.
  • HTML code section: enter your additional HTML code to enrich your content.
  • Form code section: declare your objects following the rules explained in the right panel. The objective is to create a specific form that will be usable in the visual editor when a user will add a custom widget to his campaign. This way, the user will be able to change parameters very easily. To get more information about the form structure, please refer to our technical article. See also in the next paragraph more information about the the properties.
  • Assets section: upload assets (images, video, sound) that will be automatically hosted on our server. 

Configuration of the form

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',
};

For more information about all the capabilities of the custom form, please refer to this specific article: How to configure Custom Widgets Custom Forms

How to preview of a custom widget 

Next to each code box, an eye appears on hover. 

Click on it to open a new tab and preview your code in a sandbox. 

At this stage, we can’t open your website and simulate the custom widget on it.  There are some chances that your custom widget is not executed if you have declared the presence of a certain element of your website’s structure which doesn’t exist in the sandbox. We’re currently working on another solution to avoid this problem.

Good to know 💡

You can also save your widget, add it in a campaign and work on a new version of your custom widget directly in the editor, as the preview will be automatic as your website will be loaded. There is an option to save your widget as the new one from the editor.

How to save and use a custom widget

Click save on the bottom of the custom widget creation flow. The new widget will appear in the following list, section "Your widget" of the Widget library page. 

You can directly click on "use" to create a new campaign that will contain the selected custom widget. 

How to use and edit a custom widget in the editor

By clicking on the 3 dots on the right bottom of each custom widget card, you can edit the custom widget.

Another method consists on adding the custom widget into a campaign and editing it directly in the visual editor, but the modifications will be local and the original custom widget template can’t be overwritten in the editor.

Form

You can change CSS parameters (such as a color or wording) easily by editing specific fields. These fields have been configured on the custom widget set-up page. All pre-set-up fields are available in the form tab.

Example: this is the form generated by the code created in the section "form" of the custom widget set-up page

Code

You can retrieve the code that has been configured in the custom widget template and to adapt it. You can change anything you want in the following code areas: 

  • Javascript
  • CSS (e.g. changing a color)
  • HTML (e.g. changing wording)
  • Form

It can be useful to rework on your custom widget with the ability to see directly the effects on your changes in the editor (preview on your website) versus our preview option in the creation flow that executes the custom widget in a sandbox.

Assets

This section is not available when you open your custom widget configurator for the first time. 

You can see the number of assets added to the custom widget template next to the tab. 

First, you must save your custom widget in the editor by clicking the Save button on the bottom right, and reopening the custom widget configurator from the history panel on the right of the editor.

Then, you will be able to access the Asset options and add some assets and/or delete the existing ones. 

Saving your custom widget 

Once your rework is over, you have 2 possibilities to save your custom widget:

  • Save: the custom widget will be applied to the campaign with all the changes you’ve done, these changes are applied locally, in the campaign only. 
  • Save as a new template: the custom widget will be applied to the campaign with all the changes you’ve done, and a new custom widget will be created in your library. 

    All the changes are recorded in the new custom widget, except those which have been performed thanks to the form, which remain local for the widget used in the campaign.

The original custom widget template can’t be overwritten in the editor. This way, live campaigns using this custom widget can’t be compromised. 

Good to know 💡

If you need to add several custom widgets to a variation, or to other variations/subtests, you won’t be able to duplicate them. You will have to use the variation duplication option, then do the needed changes in your second variation.

Was this article helpful?

/