文档

Programming reference

You can find full list of JavaScript/TypeScript modules, classes, interfaces, types, functions and variables available when creating your own plugin in our Builder plugin API reference. Please don't use undocumented functionality as your plugin might break if we make incompatible changes.

Plugin directory structure

Every plugin consists of multiple files:

  • main.json - (optional) Contains information about plugin such as its type or entry point (for plugins created with typescript).
  • main.html - (required) In case of a custom element plugin this html file serves as a template when rendering element in the builder or on published website. Otherwise this file may be blank.
  • main.js and/or main.min.js - (required) Contains plugin logic which is loaded into builder (uses JavaScript ES5 version).
  • main.php - (optional) Server-side logic for custom elements displayed on published websites (on-premises only).
  • main.png - (optional) Plugin icon that will be displayed in builders UI (size 24x24 pixels). Ignored when plugin does not register any custom element.

Plugin meta information (main.json)

This file must contain a single JavaScript object with following structure:

  • String type - (optional) Type of plugin. If present must have one of the values:
    • "gateway" - plugin that adds a new payment option to store cart and/or payment gateway button for immediate purchases;
    • "map" - plugin that adds a new map type;
    • "video" - plugin that adds a new video player type;
    • "ui" - plugin that replaces default Site.pro builder UI with its own (since v3.7.301);
    • "generic" - any other element that does not have any of the above mentioned functionality (used by default).
  • Boolean requireStoreModule - (optional) Must be set to true if plugin uses store module functionality. This also forces store module to be published along with plugin element even if website has no store or cart element on any page. Defaults to false.
  • Boolean requireBillingInfo - (optional) Must be set to true if payment gateway added by plugin requires billing information to be entered by customer. Defaults to false.
  • Boolean fixedHeight - (optional) When set to true custom element added by plugin will have a fixed height when publishing with auto-layout enabled. Defaults to false.
  • Array of String requireJsLibs - (optional) A list of JavaScript libraries from store module that must be included in published website.
  • Array of String loadModules - (optional) A list of modules that must be loaded (code executed) when plugin is loaded. Typically this option is used when plugin is written entirely in TypeScript language, which encapsulates all transpiled code into modules. Internally builder calls a JavaScript require function with the list of given modules to execute their code. This array may be empty (or omitted) if you have no modules declared in main.js or main.min.js. This option is available since v3.7.301.
  • Boolean admin - (optional) Set this to true if plugin should load only when builder is opened in administration (template creation) mode. This can be used to prevent plugin from getting loaded into production environment while it is being developed. Defaults to false.

Example of main.json

{
	"type": "gateway",
	"requireStoreModule": true,
	"requireBillingInfo": true
}

Element template (main.html)

This file should contain html code (with Mustache templating engine) that will be rendered to builder and final published site.

If you need different html for different cases (when in builder, on preview or on publish) there are variables added to template for that:

  • isPublished - will be true when plugin is rendered on published/previewed in builder website.
  • isPreview - will be true when plugin is rendered on previewed in builder website.

Template will also be populated with all properties from plugins element data object ElementDataDef.

Plugin logic (main.js / main.min.js)

This file must have the plugin logic, that registers and handles custom elements, payment gateways, or overrides UI functionality.

Plugin logic is loaded and executed always, even if that plugin is disabled. Disabling plugin only tells builder to ignore custom elements and payment gateways registered by the plugin.

Note.
Since v3.7.301 plugin logic is loaded from main.min.js instead of main.js if minified version is present and builder is not in admin (template creation) mode.

Using PHP code in plugin (only for on-premises builders)

Sometimes it is not enough to use HTML/Javascript code for creating plugin. Often 3rd party plugins provide REST API for integration or manipulation of the system, for example:

  • shops require saving orders
  • plugins may use PHP libraries
  • plugins may require encrypting form fields before submitting what requires server-side script like PHP

To add PHP code into your plugin take the following steps:

  1. create file "main.php" in your plugin folder and write your PHP code
  2. open file "main.html" and add marker {{{requireService}}}. The marker will be replaced with PHP code in published website
  3. open file "plugins/plugins_whitelist.json" and add your plugin name to php list
Note.
PHP code is not loaded in site builder but only in published website.
Adding multiple PHP files to plugin

Let's say you develop plugin which integrates some 3rd party system to your site. This system provides PHP SDK which you want to use.
The PHP SDK can be a folder which contains one or multiple .php files, other folders containing other files, etc.
To add all this PHP library to your plugin take the following steps:

  1. create folder "site" in your plugin folder
  2. add all needed 3rd party files/folders into folder "site"

After that you will have access to folder "site" within your PHP file "main.php".
Let's presume you have file in your plugin "myplugin/site/SomeLibrary.php". Then you can load this file with line require_once("SomeLibrary.php"); in your PHP file.

Plugin testing (only for on-premises builders)

If you are using on-premises builder then you are given one more option of testing the plugin.
Instead of using built-in system you can work on plugin in your builder at once.
All plugins are stored in builder folder "plugins" and are distributed by folders.
To add your plugin to builder you need to take the following steps:

  1. create folder "myplugin" inside builder plugins folder
  2. create files "main.html", "main.js" and "main.png" in folder "plugins/myplugin" (please see documentation above)
  3. add plugin logic to specified files (please see documentation above)
  4. create file "main.json" in folder "myplugin" and add content {"admin": true}
  5. register your plugin in builder by adding it to file "plugins/plugins-ext.json" (create it if it does not exist; this file should share the same structure with file "plugins/plugins.json")

After adding plugin you can test it in admin builder mode ("Create custom templates" link in your on-premises brand).

To make plugin available for all your customers set parameter {"admin": false} in file "main.json".

Programming logic of your plugin

Custom elements

Plugin must use PluginWrapper.registerPlugin() method to register a custom element with its property dialog definition, saving/loading and other event handlers.

Custom element plugin example (Vimeo video player)
main.html:
<iframe
	id="{{id}}_vimeo"
	src="http://player.vimeo.com/video/{{content.groupId}}?portrait={{content.portrait}}&title={{content.title}}&autoplay={{content.autoplay}}&color={{content.color}}"
	width="{{width}}px"
	height="{{height}}px"
	frameborder="0"
	webkitallowfullscreen
	mozallowfullscreen
	allowfullscreen
></iframe>

main.js:
PluginWrapper.registerPlugin('vimeo', {
	name: 'Vimeo',
	element: {
		minSize: {width: 100, height: 100},
		defaultSize: {width: 480, height: 300},
		resizable: true
	},
	propertyDialog: {
		noScroll: true,
		tabs: [
			{children: [
				{type: 'VerticalLayout', children: [
					{type: 'Label', text: __('Vimeo ID or URL'),
						helpText: __('Vimeo video id or url with format https://vimeo.com/{video_id}')
					},
					{type: 'TextField', id: 'groupId'}
				]},
				{type: 'HorizontalLayout', css: {marginTop: 15}, children: [
					{type: 'VerticalLayout', children: [
						{type: 'Label', text: __('Portrait'), helpText: __('Show the user’s portrait on the video')},
						{type: 'RadioBox', id: 'portrait0', label: __('Yes'), group: 'portrait'},
						{type: 'RadioBox', id: 'portrait1', label: __('No'), group: 'portrait'}
					]},
					{type: 'VerticalLayout', children: [
						{type: 'Label', text: __('Title'), helpText: __('Show the title on the video.')},
						{type: 'RadioBox', id: 'title0', label: __('Yes'), group: 'title'},
						{type: 'RadioBox', id: 'title1', label: __('No'), group: 'title'}
					]},
					{type: 'VerticalLayout', children: [
						{type: 'Label', text: __('Autoplay'), helpText: __('Play the video automatically on load.')},
						{type: 'RadioBox', id: 'autoplay0', label: __('Yes'), group: 'autoplay'},
						{type: 'RadioBox', id: 'autoplay1', label: __('No'), group: 'autoplay'}
					]},
					{type: 'VerticalLayout', children: [
						{type: 'Label', text: __('Color'), helpText: __('Specify the color of the video controls.')},
						{type: 'ColorSelector', id: 'color'}
					]}
				]}
			]}
		]
	},
	resizeTimeout: null,
	resizeAction: function(data, elem) {
		if (!this.resizeTimeout) {
			var self = this;
			this.resizeTimeout = setTimeout(function () {
				self.resizeTimeout = null;
				self.updateElement();
			}, 1000);
		}
	},
	openAction: function(fields, data, elem) {
		fields.groupId.setText(data.content.groupId);
		fields.portrait0.setValue(data.content.portrait === '1');
		fields.portrait1.setValue(data.content.portrait === '0');

		fields.title0.setValue(data.content.title === '1');
		fields.title1.setValue(data.content.title === '0');

		fields.autoplay0.setValue(data.content.autoplay === '1');
		fields.autoplay1.setValue(data.content.autoplay === '0');

		fields.color.setValue(data.content.color);

		fields.groupId.on('change', function() {
			var url = fields.groupId.getText();
			var regExp = /https:\/\/(www\.)?vimeo.com\/(\d+)($|\/)/;
			var match = url.match(regExp);
			if (match) {
				fields.groupId.setText(match[2]);
			}
		});
	},
	applyAction: function(fields, data, elem) {
		if (fields.portrait0.getValue()) data.content.portrait = '1';
		if (fields.portrait1.getValue()) data.content.portrait = '0';

		if (fields.title0.getValue()) data.content.title = '1';
		if (fields.title1.getValue()) data.content.title = '0';

		if (fields.autoplay0.getValue()) data.content.autoplay = '1';
		if (fields.autoplay1.getValue()) data.content.autoplay = '0';

		data.content.color = fields.color.getValue().replace('#', '');
		data.content.groupId = fields.groupId.getText();
	},
	loadAction: function (data) {
		if (!data.content.groupId) data.content.groupId = '7976699';
		if (!data.content.portrait) data.content.portrait = '1';
		if (!data.content.title) data.content.title = '1';
		if (!data.content.autoplay) data.content.autoplay = '0';
		if (!data.content.color) data.content.color = '#00adef';
	}
});

E-commerce plugin example (only for on-premises builders)

In this section e-commerce plugin is considered as a payment gateway which can be added to "Store Cart" widget in builder.
Let's say you need to have payment gateway in your Store which does not currently exist in site builder. Then creation of e-commerce plugin is a right choice.

Simple payment plugin

The creation of e-commerce plugin can be started from creation of a simple payment plugin. Let's name simple payment plugin a button for which website owner can set some predefined product(s), amount, price, etc. (similar to Buy Now button of Paypal system). To deal with it you need to use documentation (API) of payment gateway system which you want to integrate — you will need to know what parameters and what endpoint you need to submit the form to.

Let's write the code for a simple payment plugin for a dummy payment gateway:

main.js:

PluginWrapper.registerPlugin('myplugin', {
    name: 'myplugin',
    element: {
        minSize: {width: 50, height: 50},
        defaultSize: {width: 100, height: 100},
        resizable: true
    },
    propertyDialog: {
        tabs: [
            {children: [
                {type: 'VerticalLayout', spacing: 15, children: [
                    {type: 'HorizontalLayout', columnWeights: [6, 6], css: {marginTop: 15}, children: [
                        {type: 'VerticalLayout', children: [
                            {type: 'Label', text: 'Merchant ID', helpText: 'Your identifier in payment system'},
                            {type: 'TextField', id: 'merchant'}
                        ]},
                        {type: 'VerticalLayout', children: [
                            {type: 'Label', text: 'Password', helpText: 'Your password provided by payment system'},
                            {type: 'TextField', id: 'password'}
                        ]}
                    ]},
                    {type: 'HorizontalLayout', columnWeights: [4, 4, 4], css: {marginTop: 15}, children: [
                        {type: 'VerticalLayout', children: [
                            {type: 'Label', text: 'Product Name'},
                            {type: 'TextField', id: 'name'}
                        ]},
                        {type: 'VerticalLayout', children: [
                            {type: 'Label', text: 'Price'},
                            {type: 'TextField', id: 'price'}
                        ]},
                        {type: 'VerticalLayout', children: [
                            {type: 'Label', text: 'Currency'},
                            {type: 'DropdownBox', id: 'currency', options: [
                                {id: '#USD', name: 'USD', value: 'USD'},
                                {id: '#EUR', name: 'EUR', value: 'EUR'},
                                {id: '#GBP', name: 'GBP', value: 'GBP'}
                            ]}
                        ]}
                    ]}
                ]}
            ]}
        ]
    },
    resizeAction: function (data, elem) {
        if (!this.resizeTimeout) {
            var self = this;
            this.resizeTimeout = setTimeout(function () {
                self.resizeTimeout = null;
                self.updateElement();
            }, 1000);
        }
    },
    openAction: function(fields, data, elem) {
        var itm;
        itm = fields.currency.getItemById('#' + data.content.currency);
        fields.currency.selectItem(itm);
        fields.merchant.setText(data.content.merchant);
        fields.password.setText(data.content.password);
        fields.name.setText(data.content.name);
        fields.price.setText(data.content.price);
    },
    applyAction: function(fields, data, elem) {
        var itm;
        itm = fields.currency.getSelectedItem();
        data.content.currency = itm.getOriginal().value;
        data.content.merchant = fields.merchant.getText();
        data.content.password = fields.password.getText();
        data.content.name = fields.name.getText();
        data.content.price = fields.price.getText();
    },
    // set some default values
    loadAction: function (data) {
        if (!data.content.name)
            data.content.name = 'Default product name';
        if (!data.content.price)
            data.content.amount = '10';
        if (!data.content.currency)
            data.content.currency = 'USD';
    }
});

main.html:

<form action="[payment gateway endpoint]" method="post" target="_blank">
    <input type="hidden" name="d_merchantid" value="{{content.merchant}}" />
    <input type="hidden" name="d_productname" value="{{content.name}}" />
    <input type="hidden" name="d_productprice" value="{{content.price}}" />
    <input type="hidden" name="d_currency" value="{{content.currency}}" />
    {{{requireService}}}
    <button type="submit">Pay</button>
</form>

main.php:

<?php

$password = md5($pluginData->password);
echo '<input type="hidden" name="d_password" value="'.$password.'" />';
echo '<input type="hidden" name="d_transactionid" value="'.md5(microtime()).'" />';
We added "main.php" file to make payment gateway look more realistic — so that it requires submitting encrypted password with the form rather than plain password value.
Usually payment systems require to encrypt set of some form field values and add it to that form as an extra field.
On website the {{{requireService}}} string will be replaced with an output that PHP code generates.

The plugin does not do much — it creates form which submits order information to payment system by clicking button "Pay". The payment system handles sent data and offers payment methods to a client.

The plugin properties dialog should look like this in builder interface:
Simple payment plugin properties dialog for dummy payment gateway

Payment gateway plugin for Store Cart widget

Custom payment gateways that should appear in store cart must be registered using ElementRegister.registerPaymentGateway() method.

To integrate your plugin into store some changes must be made to a simple payment plugin:

  • modifying file "main.js"
  • modifying files "main.html"
  • adding PHP file with payment gateway class description
Modifying file "main.js"

The site builder should know that your plugin is a payment gateway and it has to be included to Store Cart widget as an option.
To let builder know about it we add the following code at the very beginning of "main.js" file: 


ElementRegister.registerPaymentGateway({
    name: "Dummy system",               // (required) name of payment gateway inside Store Cart widget
    id: "myplugin",                     // (required) must be the same as your plugin name
    priceFieldId: "price",              // (required) plugin price field ID in your plugin defined in property "propertyDialog"
    keyFieldId: "merchant",             // (required) field ID in your plugin defined in property "propertyDialog"
    keyField2Id: "password",            // (optional) another field ID in your plugin defined in property "propertyDialog"
    keyFieldDef: {type: "HorizontalLayout", columnWeights: [6,6], noPadding: true, children: [
        {type: "TextField", placeholder: "Merchant ID", id: "key"},
        {type: "TextField", placeholder: "Password", id: "key2"}
    ]},
    nameFieldId: "name",                // (optional) plugin product name field ID in your plugin defined in property "propertyDialog"
    globalVars: ["merchant","password"] // (optional) these variables will be available in PHP code
});

Let's take a closer look at these parameters (see PaymentGatewayItem):

  • name — Name of payment gateway system inside Store Cart widget. This property is only informative and does not affect any plugin logic.
  • id — This property tells builder what plugin payment gateway will be associated with. The value for this property must be the same as your plugin name.
  • priceFieldId — Just specify field ID which stands for price in your property "propertyDialog" in "main.js". From the beginning the price is not known in Store and therefore it is replaced with a special placeholder {{price}} in HTML form. When you submit the form this placeholder will be replaced with a real order price and sent to payment system.
  • keyFieldId — Specify merchant field ID here (or any other parameter which is related to payment system merchant identifier).
  • keyField2Id — Here we presume that our Dummy payment gateway specifies password which must be also used in the form (for example in signature calculation). So we add it as a second parameter.
    Note: You can use any number of parameters of such format: keyField3Id, keyField4Id, etc.
  • keyFieldDef — This field accepts object which describes layout of properties specified above (keyFieldId, keyField2Id) in Store Cart properties dialog. The structure of this object is the same as of "propertyDialog". Developing your payment gateway you can see examples of this property used in other predefined payment gateways (e.g. in "plugins/assist/main.js").
  • nameFieldId — Just specify field ID which stands for product name/description in your property "propertyDialog" in "main.js".
  • globalVars — Specify array containing field IDs which you will need to have in PHP code. In example above we specified fields "merchant" and "password". We presume that after successful payment the payment system will send IPN (Instant payment notification) to website which must be handled properly. The information which payment system sends in this step can be encrypted and to decrypt it you might use your merchant ID or password values.
    Note: Of course this depends on payment system. You must read documentation which payment system provides and be able to handle payment result properly. If payment system for which you implement plugin does not use IPN or it does not require calculating signature then you can omit property "globalVars".

After adding this part of code you should see something like this in Store Cart widget properties dialog:
Store Cart widget properties dialog

Modifying file "main.html"

When you integrate your plugin in Store widget then a special variable {{content.store}} is available inside "main.html" file.
Let's see how the file should look like now:


<form action="[payment gateway endpoint]" method="post"
{{^content.store}} target="_blank"{{/content.store}}
{{#content.store}} data-gateway-id="DummySystem"{/content.store}}>
    <input type="hidden" name="d_key" value="{{content.key}}" />
    <input type="hidden" name="d_productname" value="{{content.name}}" />
    <input type="hidden" name="d_productprice" value="{{content.price}}" />
    <input type="hidden" name="d_currency" value="{{content.currency}}" />
    {{#content.store}}
    <input type="hidden" name="d_transactionid" value="{transactionId}" />
    <input type="hidden" name="d_callbackurl" value="{callbackUrl}" />
    <input type="hidden" name="d_returnurl" value="{returnUrl}" />
    <input type="hidden" name="d_cancelurl" value="{cancelUrl}" />
    <input type="hidden" name="d_verifyurl" value="{verifyUrl}" />
    {{/content.store}}
    {{{requireService}}}
    <button type="submit">Pay</button>
</form>

The changes we made are:

  • Made attribute target="_blank" not used in form when the form is used in Store widget.
  • Added attribute data-gateway-id (this is required for Store widget).
  • Added form parameter {transactionId}. This is a placeholder which will be replaced with a real transaction ID generated by Store widget when submitting the form.
  • Added form parameters {callbackUrl}, {returnUrl}, {cancelUrl} and {verifyUrl}. These are placeholders which will be replaced by real URLs generated by Store widget when page is loaded. Let's take a closer look at these parameters:
    • {callbackUrl} — Add this placeholder if your payment system supports IPN. The placeholder will be replaced with URL which must be used by payment system as IPN URL.
      Note: Some payment systems do not support passing URL as a form parameter. Intead they let you pre-configure this URL in merchant account. In such case just do not add this parameter to the form and see how this issue is solved in predefined payment gateway plugin "Robokassa" (file "plugins/robokassa/main.js").
    • {returnUrl} — Add this placeholder if your payment system supports return URL. Usually payment systems let you specify URL where buyer will be redirected after successful payment.
    • {cancelUrl} — Add this placeholder if your payment system supports cancel URL. Usually payment systems let you specify URL where buyer will be redirected after canceling payment (or after payment was unsuccessful).
    • {verifyUrl} — Add this placeholder if your payment system supports payment verifying URL. Sometimes payment systems let you specify URL which will be called by payment system before callback URL in order to check if payment is not fake and really exists. Usually in this case payment systems require to output some message indicating of payment existence.

We can see that parameter d_transactionid is added twice to the form when using payment system from Store widget — first time in "main.html" file and the second time in "main.php" file. To fix this problem we need to edit "main.php" file:


<?php

$password = md5($pluginData->password);
echo '<input type="hidden" name="d_password" value="'.$password.'" />';
if (!$pluginData->store) {
	echo '<input type="hidden" name="d_transactionid" value="'.md5(microtime()).'" />';
}

Also we can see that parameter d_password is not added to the form at all. This parameter will be added to the form by PHP gateway payment class.

Adding PHP gateway payment class

In previous sections we managed to submit form to payment system when the form is used in Store widget. Now the form can send dynamic price taking it from Store and pass extra parameters like IPN URL needed for payment system to inform website about payment status. After that we need write logic which will handle IPN call on website and send appropriate response (if needed).

1. Create file "plugins/myplugin/site/GatewayMyplugin.php".
Note: The name of the file should be constructed from concatenated words "Gateway" and your plugin name with capitalized first letter (e.g. if plugin name is "abc" then gateway class must be "GatewayAbc" or if plugin name is "abc_def" then gateway class must be "GatewayAbcDef").

2. Add the following contents to the file:


<?php

class GatewayMyplugin extends PaymentGateway {

    /** @var boolean */
    protected $returnAfterCallback = false;

    public function init() {}

    /** @return string */
    public function getTransactionId() {}

    /**
     * @param array $formVars
     * @return string[]
     */
    public function createFormFields($formVars) {}

    /**
     * @param array $formVars
     * @return string
     */
    public function createRedirectUrl($formVars) {}

    /**
     * @param array $formVars
     * @return string
     */
    public function createInstantRedirectUrl($formVars) {}

    /**
     * @param StoreModuleOrder $order
     * @return boolean
     */
    public function callback(StoreModuleOrder $order = null) {
        return true;
    }

    /** @param StoreModuleOrder $order */
    public function verify(StoreModuleOrder $order = null) {}

}

The class must extend abstract class "PaymentGateway" which contains one required method "getTransactionId". All other methods are optional and should be used only if needed by payment system you are developing payment gateway plugin for.

We left all methods empty because the logic will depend on payment system requirements. Let's take a closer look at these methods:

  • init — There can be any code for class initialisation. The method is called after class contructor.
    Note: This method must return boolean value. If it returns true then the payment will be set as successful. Otherwise the payment will be considered failed.
  • returnAfterCallback — Property indicating whether website must redirect client to Return URL right after Callback URL (IPN) was called and callback logic was processed.
    Note: Some payment systems prefer using separately return URL and callback URL. The client is redirected from payment system by return URL back to website (payment system → browser) and the callback URL is called later (payment system → server). In this case property "returnAfterCallback" must be false. Some payment systems prefer redirecting client back to website and pass payment status details at once with no separate IPN call. In this case property "returnAfterCallback" must be set to true.
  • getTransactionId — Must return value from request (POST or GET depending on payment system) of property which stands for transaction ID passed as parameter "d_transactionid" in form. This method is important because Store on website must identify payment by returned value. If Store does not find payment by transaction ID returned by this method it will not be able to set appropriate status to payment (complete,pending,failed).
  • createFormFields — Returns array of HTML inputs which should be embedded to the form right after a buyer submitted the form but the form has not been sent to payment system yet. The method accepts argument $formVars which is associative array containing serialized form information.
    Note 1: Some payment systems require calculating signature of values which are submitted. This can be done in this method and an extra form input returned.
    Note 2: If one of returned HTML inputs name matches name of already existing input in the form then that input will be completely replaced with returned in this method.
    Note 3: If you return boolean false then form will not be submitted.
  • createRedirectUrl — Returns URL which will be set to form "action" attribute. Some payment systems do not have static payment submitting URL. Instead they provide per merchant-basis URL or dynamic URL depending on form field values.
  • createInstantRedirectUrl — The Store will just redirect the client by URL returned in this method without submitting any POST data. If returned, then method createRedirectUrl will be ignored.
  • callback — The logic of callback. For example payment system might require to respond with some message which would indicate of successful IPN handling. In this case You can output any message like echo "OK"; (the message can be any depending on payment system). Note that you can also set your headers if payment system require (e.g. header('Content-Type: application/json; charset=utf-8');.
    Note: This method must return boolean value. If it returns true then the payment will be set as successful in Store. Otherwise the payment will be considered failed.
  • verify — The logic of payment verification. For example payment system might require to respond with some message which would indicate of payment existence. Otherwise payment system will not process the payment considering it fake. You can output any message like echo "OK"; (the message can be any depending on payment system).
In the class scope you can access property $this->config in any method. This is a property of type "stdClass" contains information stored in file "main.js" in property globalVars. For example in our Dummy payment gateway we can access our stored properties like this: $this->config->merchant and $this->config->password. Except our stored properties the object $config can also have these by default:
  • wbLang — 2-letter language code the website is currently on (set only if "Languages" widget is added in website).
  • wbDefLang — 2-letter language code of default site language (set only if "Languages" widget is added in website).
  • wbBaseLang — 2-letter language code of builder language the client was on while building website (always set).

Overriding default builder UI (only for on-premises builders since v3.7.301)

Plugin must follow these minimum requirements to override default UI:

  • Plugin type must be set to "ui" (type property in main.json file)
  • Plugin must have its own custom UI manager class that extends UIManager class from public plugin API.
  • Custom UI manager in its constructor must create a DOM element (for example DIV), add it to body, and initialize it as builder canvas using BuilderAPI.init() method (builder api instance is provided to constructor upon manager instance creation).
  • Custom UI manager must be registered in builder using UIManager.registerUI() function.

Since builder version 3.7.305 you are also required to open the Brand > Customize Builder dialog and select which UI plugin must be used in builder. In earlier versions builder was automatically initializing last loaded UI plugin.

Example of a blank custom UI manager
main.json:
{
	"type": "ui"
}
main.js:
require(["PluginApi/UIManager"], function(UIManager) {
	var MyCustomUI = function(builder) {
		UIManager.UIManager.call(this, builder);
		var builderCanvas = $('<div id="builder_canvas"/>');
		$(document.body).append(builderCanvas);
		builder.init(builderCanvas);
	}
	MyCustomUI.prototype = Object.create(UIManager.UIManager.prototype);
	MyCustomUI.prototype.constructor = MyCustomUI;

	UIManager.registerUI(pluginData.id, MyCustomUI);
});

Please see BuilderAPI class for available builder, website and page control functions.

Other examples

  • Using List object (zip)
  • Using custom object list (zip)