Introduction

Welcome to BuilderJS 5.0, the most powerful HTML Email or Page builder tool. BuilderJS is the easiest, quickest way to design elegant, mobile responsive emails or landing pages for your business.

BuilderJS is made in pure Javascript and HTML, making it easy to integrate with any web application no matter what the server-side programming language is (Java, .Net, PHP, Ruby on Rails, Python, etc.)

BuilderJS is made fully customizable and open to any integration scenario: you can make it a standalone web page or embed it into your own site. For example, when it comes to save user work, BuilderJS allows you to configure a Save URL, to which it will make a POST request, passing the latest updates to the server-side scripting for handling. The request is triggered when user clicks on Save button in the builder. And there are lots of other configuration settings allowing you to customize how it works and interacts with the other components.

This API documentation page was created with Slate. Feel free to help contribute to the our documentation.

Installation

Quick start

Put the following HTML / JavaScript code snippet to your HTML page. Make sure you update the reference paths href and root values accordingly to your setup:

<!DOCTYPE html>
    <head>
        <link rel="stylesheet" href="/builderjs/dist/builder.css"></link>
        <script type='text/javascript' src="/builderjs/dist/builder.js"></script>
    </head>
    <body>
        <script language="Javascript">
            var builder = new Editor({ root: "/builderjs/dist/" });
            builder.init();
        </script>
    </body>
</html>

It's that simple! The builder's init() function will do the magic of rendering the entire builder view with its default settings and append it to your page's body.

BuilderJS comes with init() helper function allowing you to quickly initiate the builder and append it to your current web page.

Simply include the BuilderJS JavaScript and CSS files to your HTML page and initiate it on page load. See sample code in the right panel, javascript tab, to see how easy it is to load a fully-functioning builder to your webpage. With minimum configuration like that, the builder loads with a default blank design page like below

Default Blank Page

Important

Notice the "root" parameter which is important for BuilderJS to find the related resources. For example, if your BuilderJS distributable dist/ folder is available at http://example.com/builderjs/dist/, then you need to set your "root" value to an absolute path of "/builderjs/dist/". Remember to add both leading and trailing slashes

Instantiate the builder object and use init() helper function is the easiest way to get started with the builder. See more advanced configuration options in the next sections of this document.

Examples

BuilderJS also comes with a sample package so that you can quickly explore the builder features. Just put the sample folder to your document root and open it in a web browser to see it in action

http://example.com/sample/

Advanced

<script>
    // A more complicated setup
    var builder = new Editor({
        root: '/builderjs/dist/',
        url: 'http://example.com/template/02093403',
        saveUrl: 'http://example.com/save?id=02093403',
        saveMethod: 'POST',
        backUrl: 'http://example.com',
        tags: [
            {name: 'First Name', type: 'display'},
            {name: 'Last Name', type: 'display'},
            {name: 'Current Year', type: 'display'},
            {name: 'Current Date', type: 'display'}
        ]
    });
</script>

Notice the "root" parameter which is important for BuilderJS to find the related resources. For example, if your builderjs distributable (dist) is available at http://example.com/builderjs/dist/, then you need to set your "root" value to "/builderjs/dist/". Remember to keep both leading and trailing slashes.

See the right panel for a more complicated setup. See the Configuration section for advanced installation options which provide you more control over how the builder functions.

By default, BuilderJS renders its HTML content to the document.body element of the page. i.e. the builder view will occupy the whole page. You can also configure it to render to a child element of your page.

Configuration

Load a Template

By default BuilderJS loads with a blank design for you to start making your own HTML email or page. You can also start working with an existing email or page template by loading it into the design view. There are 2 ways of loading an existing template:

From an HTML string

<script>
    var builder = new Editor({ root: '/builderjs/dist/' });
    builder.load('<div> <h1>Awesome title</h1> <p> Page content... </p> </div>')
</script>

Use the load(html) function, passing an HTML string. See code example in the right panel

Parameter	Default	Description
html	[empty]	HTML content for loading to the viewer

From a public URL

Very often, your template is also available as a public URL. Then you can pass it to the url parameter to your builder initialization code. See example in the right panel

<script>
    var builder = new Editor({
        root: '/builderjs/dist/',
        url: 'http://example.com/template/2001990'
    });

    builder.init();
</script>

Parameter	Default	Description
url	null	URL to the template page which will be fetched and loaded to the builder

Upload a template

Remember that BuildJS is a pure front-end application. Uploading a template to the server requires server scripting language like Ruby on Rails, PHP, Java... to handle file upload and pass the URL of the newly uploaded template as url parameter of the builder construction function.

Other Settings

Below is the complete list of configuration settings (optional) that can be passed to the Builder construction

Construction Parameters

Parameter	Description
url	URL of the template to be loaded. If not provided, BuildJS will load a blank design page
backUrl	URL of the page that builder redirects to when Exit or Back button is clicked
templates	List of templates available for user to choose from. See Templates section for details
title	Title to set for the current HTML page, overwriting the `<title>` tag value
saveUrl	The URL to which BuilderJS submits its latest content for storing (handled by server script). See Storage section for details
tags	Tags used by the BuilderJS to represent a dynamic value. See Tags section for the details
view	Possible values include `design` and `preview`. Tell the builder to open in design or preview mode
renderTo	The parent element to which BuilderJS renders its content. It is `document.root` by default

Key Features

Visual Drag & Drop Editor

BuilderJS comes as a fully-functioned visual Drag & Drop editor, allowing you to quickly build your page or email templates without any hassle

Source Editor

Beside the visual Drag & Drop editor, BuilderJS also supports a Source Editor which allows you to completely customize your page or email design by updating HTML / CSS directly. This is for advanced users who are familiar with HTML / CSS markup language

Source Editor

Template

<script>
// Pass a list of available templates to the builder
// which will be available for user to choose from
// by going to Design > New From A Template

// List of available templates
var templates = [
  {
      name: 'My Awesome Template 1',
      url: 'http://example.com/template/030331',
      thumbnail: 'http://example.com/template/030331/thumb.png'
  }, {
      name: 'My Awesome Template 2',
      url: 'http://example.com/template/030332',
      thumbnail: 'http://example.com/template/030332/thumb.png'
  }, {
      name: 'My Awesome Template 3',
      url: 'http://example.com/template/030333',
      thumbnail: 'http://example.com/template/030333/thumb.png'
  }, {
      name: 'My Awesome Template 4',
      url: 'http://example.com/template/030334',
      thumbnail: 'templates/030334/thumb.png'
  }
];

// Pass to the builder
var builder = new Editor({
    root: '/builderjs/dist/',
    templates: templates
});

</script>

Notice that templates parameter expects an array of templates, each with name, url and thumbnail

BuilderJS allows you to create new blank workspace and build your design from scratch. However, most of the time, you may want to start making your own email or page design from an existing template, then taylor it to your own needs.

You can also pass a list of available templates to BuilderJS, and it will in turn show up to user for choosing from, by going to Design > New From Template

Available Templates selection

See example on the right to find out how to pass a list of available templates to your builder.

Responsive

BuilderJS supports making email or pages that are fully responsive. You can preview your design with a PC, tablet or mobile phone simulator supported by BuilderJS. It is to make sure your email or page will show up correctly in reality

HTML Widgets

BuilderJS comes with lots of pre-defined HTML widgets (or block or common HTML content) like image box, text box, divider, page footer, email signature, banner, etc. providing you everything you need to build an email or page

Custom Widgets

You can also add your own widget to the list for using later on. BuilderJS supports "Add to widget library" feature, allowing you to select an element or group of elements to become a widget.

Storage

<script>
    // Initiate builder with `saveUrl`
    // See `php` or `ruby` tab to see how to
    // handle save request sent from builder in PHP and Ruby respectively
    var builder = new Editor({
        root: '/builderjs/dist/',
        url: 'http://example.com/template/02093403',
        saveUrl: 'http://example.com/save?id=02093403',
        saveMethod: 'POST'
    });
</script>

# Sample controller code for handling the save request
# sent from BuilderJS

# Python code sample is not yet available
# comming soon!

# Sample controller code for handling the save request
# sent from BuilderJS

require 'activerecord'
require 'mysql'

# Set up MySQL connection
ActiveRecord::Base.establish_connection(
  adapter: 'mysql2',
  database: 'myDB',
  username: 'user',
  password: 'password'
)

# Associate Template class with the `templates` data table
class Template < ActiveRecord::Base
  # associated with `templates` table
end

# Retrieve parameters passed to the server script
content = params[:content]
template_id = params[:id]

# Actually update the MySQL database
template = Template::find(template_id)
template.content = content

template.save

<?php

// Sample controller code for handling the save request
// sent from BuilderJS

// MySQL credentials
$servername = "localhost";
$username = "user";
$password = "password";
$dbname = "myDB";

// Create connection
$conn = new mysqli($servername, $username, $password, $dbname);

// Retrieve parameters passed to the server script
$html = $_POST['content'];
$html = $conn->real_escape_string($html);
$templateId = $_GET['id'];

// Actually update the MySQL database
$sql = "UPDATE templates SET content = '{$html}'
        WHERE id = '{$templateId}'";

if ($conn->query($sql) === TRUE) {
    echo "Template updated successfully";
}

$conn->close();

When it comes to save, BuilderJS allows you to specify a Save URI, to which it will make a POST request, passing the latest updates to the server side scripting for handling. The request is triggered when user clicks on Save button in the builder.

Actual job of storing the submitted content is handled by a server-side scripting language like PHP, Ruby, Python, Java, .Net, etc.

Below is an example of how BuilderJS sends its content to the server. By default, when user clicks Save button, BuilderJS makes a POST request to the URL specified by saveUrl parameter passed to the builder construction method.

See sample code on the right panel, javascript tab to see how to specify a save URL mentioned above. See php or ruby or python tabs for sample code snippet that handles such request.

Sample POST request

POST http://example.com/template/save?id=02093403

Request header

Below are request headers added by BuilderJS. Note that it is an Ajax request (specified by the X-Requested-With: XMLHttpRequest header) that accepts a JSON response from your server

Accept: application/json
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
X-Requested-With: XMLHttpRequest

Request parameters

Below are POST parameter passed to the server along with the request

Parameter	Description
content	HTML content of the design, including any update made to the design. Simply store its value to a server's database like MySQL, PostgreSQL, Oracle or any other database management system
token	CSRF token just in case your server requires it

Integration

Since BuilderJS is a pure JavaScript library, accepting parameters passed to its initialization, it is open to any kind of integration no matter what your programming language or database system is.

All its job is to load a template in HTML, allow user to make changes using its visual drag & drop or source edit then submit the changes to the server for storing. You can use PHP, Ruby, Python, Java, .NET or any other server side scripting language to handle BuilderJS requests. In the distributable package, we also include sample PHP scripts for saving, exporting, etc.

Customization

<script>
    class MySampleWidget extends Widget {
        // get HTML to insert into content
        init() {
            super.init();
        }

        title() {
            return 'My Sample Widget';
        }

        renderHtml() {
            return '<div> A Simple Widget with 1 line of text </div>';
        }

        // custom behavior goes here...
</script>

BuilderJS is written in a well designed structure, allowing easy and straightforward customization. For example, you can add your own widget to the library beside the default ones like Text, Image, Video, Social Network Icons, etc. See the right panel, javascript tab to find out how to write a custom widget.

By extending the Widget base class, your MySampleWidget will automatically inherit all behaviors of a common widget like drag & drop enabled, move/duplicate/delete support. You can specify its own characteristics like title, thumbnail, etc. by overwriting the corresponding methods.

Documentation is being updated. In the mean time, please contact us for more details on this topic.

SaaS Support

BuilderJS is also suitable for SAAS (Software as a Service). That is, you have control of how BuilderJS features are available to your users. For example, you can always turn a feature ON or OFF for different classes of users.

Documentation is being updated. In the mean time, please contact us for more details on this topic.

Errors

For reference, the following error codes should be used by the server side scripting to better communicate with BuilderJS

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The kitten requested is hidden for administrators only.
404	Not Found -- The specified kitten could not be found.
405	Method Not Allowed -- You tried to access a kitten with an invalid method.
406	Not Acceptable -- You requested a format that isn't json.
410	Gone -- The kitten requested has been removed from our servers.
418	I'm a teapot.
429	Too Many Requests -- You're requesting too many kittens! Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

As of version 5.0, there are two cases when BuilderJS makes an Ajax request to the server end. The first is for saving latest changes of the design view (see Storage section for more details), and the second is when it sends an asset (image or video). Server script should return HTTP 200 for successful job and one of the error code above for failure

Introduction

Installation

Quick start

Important

Examples

Advanced

Configuration

Load a Template

From an HTML string

From a public URL

Upload a template

Tags

Other Settings

Construction Parameters

Key Features

Visual Drag & Drop Editor

Source Editor

Template

Responsive

HTML Widgets

Custom Widgets

Storage

Sample POST request

Request header

Request parameters

Integration

Customization

SaaS Support

Errors