NAV

PageBuilder

Version: 5.0

html php ruby python

Introduction

Welcome to the quickest way to design elegant, mobile responsive emails or landing pages for your business.

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, PageBuilder 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:

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

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

Simply include the PageBuilder 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 PageBuilder to find the related resources. For example, if your PageBuilder 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

Examples

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 PageBuilder to find the related resources. For example, if your PageBuilder 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, 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 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.

Tags

<script>
    // Initialize with tags

    var builder = new Editor({
        root: '/builderjs/dist/',
        tags: [
          {name: 'First Name', type: 'display'},
          {name: 'Last Name', type: 'display'},
          {name: 'Current Year', type: 'display'},
          {name: 'Current Date', type: 'display'},
        ]
    });
    builder.init();
</script>

Tag is a powerful feature of BuildJS, allowing users to inject dynamic content to page or email content. For example, very often user wants to inject a dynamic contact first name or last name to an email template. Dynamic content can be achieved by inserting a place holder, or, in other word, a tag to your email or page content. When it comes to load your page or send your email, tags will be translated to appropriate values. Example of tags are:

Other examples of constant tags

You can define your own list of tags and pass those to the tags parameter of PageBuilder construction. PageBuilder has a very powerful feature allowing you to drag and drop a tag to your template content page, without you having to manually type in the tag. Even more, you can benefit from tag autocomplete feature. That is, just type an open bracket and PageBuilder will render a autocomplete dropdown list of all available tags for you

That's how PageBuilder helps with tag editing, making it easy for user to add tags to email or page content.

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 PageBuilder submits its latest content for storing (handled by server script). See Storage section for details
tags Tags used by the PageBuilder 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 PageBuilder renders its content. It is document.root by default

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

// 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 PageBuilder sends its content to the server. By default, when user clicks Save button, PageBuilder 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

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 PageBuilder 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 PageBuilder 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>
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.
html php ruby python