Custom Widgets Form

The configuration form allows the end user of your Custom Widget to customize it easily, even without any technical knowledge.

Properties

Defined properties to display forms:

type: String, defines the type of form that will be displayed, find the list of allowed types here: https://developers.abtasty.com/docs/custom-widgets/custom-widgets-form#list-of-propname-fields-and-their-specificities

propName: String, it is the key that will be used in DATA object in order to get the value.

label: String or Object, defines the label of your form, it will be displayed to help the final user understand what is the purpose of the form. It supports strings but also objects to translate in following languages : en, fr, es, de.

value: Any, it is the value the form will have by default.

Here is an example with a simple text type input :

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

Conditions management

const triggerEventClick = {
  type: "selectelement",
  label: "Select the element that will trigger the Custom Widget on click",
  propName: `triggerElementClick`,
  value: "body",
  condition: (DATA) => DATA.triggerType === "click",
};

// or using destructuring

const triggerEventClick = {
  type: "selectelement",
  label: "Select the element that will trigger the Custom Widget on click",
  propName: `triggerElementClick`,
  value: "body",
  condition: ({ triggerType }) => triggerType === "click",
};

The condition function takes the whole DATA object as parameter, meaning it contains all key/values from it. Simply return true or false depending on your custom condition and the form will display or hide your conditional input accordingly.

Displaying a field in the form based on a condition can be done by adding the condition key with a function as value. This condition will only hide the field from the widget's form, and the property will still exist with its value saved in the DATA object.

List of propName fields and their specificities

areainput

Displays a list of input numbers, it is mostly used to define box-model dimensions (top, right, bottom, left) for many usages, margin, 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.

Checkboxes don't have 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: String.

Specific property:

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

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 to users.

value: 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 String date.

DATA value: Date.tostring()

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

datetimetimezonepicker

Displays a datetimepicker with, in addition, a collapsed group to set some more information :

• A toggle to follow the sun (Will end at this time in each timezone or not)

• A select input to choose a timezone when needed (When the "follow the sun" toggle is off)

value: Object with 2 properties at init :

• type: That you should 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 use for the editor preview when the "follow the sun" toggle is on)

• type: String 'local' or 'global' depending whether the "follow the sun" toggle is on or off.

• timecomponents: Object containing as Number the following: minute, hour, day, month, year

• raw: Object with all data :

  • followTheSun: Boolean

  • previewTimezone: String for geolocation timezone, ex: 'Europe/Paris' (Value to use for the editor preview when "follow the sun" toggle is on)

  • timedef: Object, same as timecomponents

  • timezone: 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 like timecomponents but with current user date and time values.

    • offset: Number resulting of getTimezoneOffset

    • timestamp: timestamp Number

    • timezone: 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",
  },
};

group

Display a group of forms, this is a visual change only, all props from children of it will be accessible directly in DATA at the end.

This is not a form, it does not have a value property but a children one which contains an array of objects, these objects are supposed to be fields.

List of specific properties :

children: Array of objects

collapsible: Boolean (default: false) Define if the group can be collapsed or not.

collapsed: Boolean (default: true) In case collapsible is true, define the initial state of it.

Read me!

As children of this input you can use any input except replicable and group input types.

const textStylesGroup = {
  type: "group",
  label: "Text styles",
  collapsible: true,
  collapsed: false,
  children: [
    { ...textAlignmentForm },
    { ...textColorForm },
    { ...textFontForm },
  ],
};

group render

replicable

Display a group of inputs that you can replicate to get multiple values for 1 type of information required.

This is not a form, it does not have a value property but a children one which contains an array of objects, these objects are supposed to be fields.

List of specific properties :

children: Array of objects min: Number (optional) used to set a minimum number for the amount of times the children will be replicated (default is 1) - the form will not let you remove any more replicated groups when this limit is reached max: Number (optional) used to set a maximum number for the amount of times the children will be replicated (default is 4242) - the form will not let you add any more replicated groups when this limit is reached headerLabel: String (optional) - used to label each set of replicable groups addButtonLabel: String (optional) - used to label the button used to add replicable groups

You'll then be able to access actiontracking array and get name and from key/values in each item.

Read me!

As children of this input you can use any input except replicable and group input types.

const atSettings = {
  propName: "actiontracking",
  type: "replicable",
  category: "conditions",
  children: [
    {
      type: "text",
      propName: "name",
      label: "Tracker name",
      defaultValue: "More than 5 seconds",
    },
    {
      type: "number",
      propName: "from",
      label: "Time a user has to spend on the page to trigger the goal (sec)",
      min: 0,
      defaultValue: 5,
    },
  ],
};

searchselect render

hidden

Allows you to have a hidden input.

value: String

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

inlinenotification

Allows you to inform the users about a specificity of your form or Custom Widget.

This element doesn't need a value property.

List of specific properties :

label: String as the message you want to display.

hrefUrl: String of url type you want the user to redirected to.

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

inlinenotification render

number

Displays an input number type.

value: Number

You're also able to provide more properties:

min: Number (default is 0)

max: Number (default is 9999)

step: Number (default is 1)

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

number render

paragraph

Simply displays some text into the form, it can be used for many reasons: to inform, alert, and so on.

No value in that case, put your content in text property: 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: 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 begining of selected element",
      value: "afterbegin",
    },
    {
      label: "At the end of selected element",
      value: "beforeend",
    },
    {
      label: "After selected element",
      value: "afterend",
    },
  ],
};

radio render

radioImage

Display a radio input with images/icons as buttons

value: String

Specific property: options like radio and style: String big or little 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`,
    },
  ],
};

radioImage render

searchselect

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

value: String

Special property: options like radio

Special options properties:

filterable: String, have to be similar to default value

placeholder: String, text to show when the search field is empty

const textFontNameForm = {
  type: "searchselect",
  label: "Select font",
  propName: "fontName",
  value: "inherit",
  filterable: "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",
    },
  ],
};

searchselect render

select

Displays a select

value: String

Special property: options like 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",
    },
  ],
};

select render

selectelement

value: String (more likely formatted as a css selector)

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

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

Special properties: min and max of type Number, both are optionals, default values are 0 and 100.

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

slider render

switch

Displays a switch that allows the user to select an option.

value: Boolean

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

switch render

textarea

Displays a textarea that allows users to put text in it.

value: String

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

textarea render

text

Displays a simple text input.

value: String

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

text render

url

A text type input dedicated to the URL, format verification and error handling are managed by default.

value: String

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

areainput render

wysiwyg

A textarea input improved with text styling functionalities

value: String

Give an example for each

const customWidgetTextContent = {
  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.`,
};

wysiwyg render