We have a made a solid effort to provide as much documentation and information about HTML Builder, the way it was built, the way it works and its features. If, however, you find anything lacking from this document or you have any questions, do not hesitate to contact us at [email protected] or submit a ticket through our help desk located at https://selfhosted.net/support/.

Introduction

What it is

HTML Builder is a Javascript application which allows publishers of HTML templates to provide their customers with a quick and easy way to customize HTML templates. HTML Builder requires HTML templates to be divided into blocks which can be placed within a HTML skeleton. HTML Builder also allows for basic content editing, allowing users to changes link text, headers and other written content. HTML Builder can easily be bundled with HTML templates or integrated into other applications (like CMS's).

HTML Builder comes bundled with several HTML blocks to demonstrate it's usage (these are the same blocks as used in the online demo). You are free to use the provided blocks in whatever way you like.

HTML Builder runs (almost) entirely in the browser. The only server side code comes in the form of four PHP files, used for saving a page, uploading images, exporting an entire site and previewing changes.

What it's not

HTML Builder is NOT a CMS (content management system). It does not provide a way for end-users to work on live websites and make changes to such websites.

Upgrading

Upgrading from 1.x to version 2.x

Version 2.x is a complete rewrite and therefor you'll need to replace the entire script. The way blocks are handled has remained the same, so you can copy over your blocks. Other than the block files, everything is different in 2.0 including the elements.json file.

Upgrading from 2.x to 2.x

If you have not modified the source code, upgrading can simply be done by replacing the following folders:

  • (dist)/js/
  • (dist)/css/
  • (dist)/elements/

If you have made changes to the underlying source code, unfortunately there is no easy solution for upgrading to the latest version. You will need to track your changes and re-implement them after upgrading. When done, you will need to rebuild the Javascript. We might be able to provide detailed diffs of changes made to certain files, if you require these please contact us. Please note we do not guarantee we will have these available.

Requirements

To be able to use HTML Builder, you must have the following:

  • PHP
  • Apache webserver (Windows servers will probably work, but are not supported)
  • An FTP tool to upload the files

Structure

HTML Builder is built using HTML, CSS Javascript and four PHP files (for exporting, saving, uploading images and previews). It's built using the Flat UI pro interface kit (http://designmodo.com/flat)

The HTML Builder script is located in the dist folder (you will need to upload the entire contents of this folder to your hosting).

In addition to the dist folder, you'll the following additional folders:

/builder_front/
  • dist/
    • _export.php
    • _preview.php
    • _save.php
    • _upload.php
    • css/
    • elements/
    • elements.json
    • fonts/
    • images/
    • index.html
    • js/
    • site.json
    • tmp/
  • Jake.cmd
  • Jake.sh
  • Jakefile.js
  • js/
    • build/
    • builder.js
    • modules/
    • vendor/
  • package.json
  • README.md
/Documentation/
File/Folder Purpose
dist/ This folder contains all the code needed to run use application. If you're hosting HTML Builder on a server, this the folder you want to point your hosting at. Or, if you're uploading the files to a remote server, you would be uploading the contents of this folder.
Jake.cmd This is the Jake executable to build the application on a Windows PC.
Jake.sh This is the Jake executable to build the application on a Linux or Mac computer.
Jakefile.js This is the Jake file containing all the application's automated tasks, including the build task (which needs to run after modifying the source code).
js/ This folder contains all the source code for the entire application.
package.json This file contains the NPM module list. You'll need this if you're planning to modify the application's source code.
README.md Markdown file containing info about the application, including the current version.

Installation

Installing the HTML Builder script is simply a matter uploading the contents of the dist folder to a server/hosting account. Once uploaded, point your browser to said server/hosting and your script will work.

Drag & Drop

HTML Builder allows users to drag HTML blocks onto a canvas and drop them where they'd like them to appear. Once dropped onto the canvas, the position can be changed by dragging and dropping as well. Blocks can be delete individually or all blocks on the current page can be deleted in one go.

Editing content

The HTML Builder script can also be used to edit written content inside each element. HTML Builder uses a rich text editor, allowing to make changes to the written content. Depending on what type of element you're editing, certain options will be disabled in the editor. Editable text elements will need to be configured through "js/modules/config.js", and depending on the exact configuration, certain text elements might not be editable.

To activate the inline content editor on elements, an object named "editableItems" is used in the config.js module (js/modules/config.js). CSS3 selectors are used to target an element or selection of elements, to activate the content editor make sure the selector's array has "content" in it. Please have a look at the config.js file for examples.

Editing styles

The HTML Builder script also allows for basic CSS editing. Using the built-in CSS editor, end-users can customize whatever CSS attributes the script's admin has configured. When editing a link, the end-user can point the link to either an internal page or an (external) URL.

Which CSS attributes are active is configured through the config.js module (js/modules/config.js) using the editableItems object.

Editing links

The HTML Builder script allows user to edit links as well. To be able to edit links, firstly the link selectors will need to be added to the editableItems array in the js/modules/config.js module. When selected, a "link" tab will be visible in the left panel, allowing you to either choose a page to link to or enter a URL manually as well as setting the inner text of the link element.

Linking within a single page

When building a one-page website, you might want to link to sections within a single page rather then to a separate page. To do this, simply edit the link and use the second dropdown to choose the block you'd like to link to. The ID's to which can be linked, have to be configured within the block HTML files, and the ID attribute should be assigned to the first child element of the main container (for an example, please have a look at any of the bundled block files).

Editing images

The HTML Builder script allows user to edit images as well. To be able to edit images, firstly the image selectors will need to be added to the "editableItems" array in the js/modules/config.js file. When selected, a "image" tab will be visible in the left panel, allowing you to either upload an image or enter a URL manually.

Editing videos

HTML Builder allows users to edit Youtube and Vimeo videos as well. Click the video you'd want to edit. This will open the left sidebar panel where you can enter a Youtube video ID or a Vimeo video ID. You can alter between these as you please, the application will detect which platform you're using and update the video accordingly.

Icon editing

The HTML Builder script allows user to edit icons as well (the script allows you to use all icons available in the Font Awesome collection). To be able to edit icons, firstly the icon selectors will need to be added to the "editableItems" array in the js/modules/config.js file. After clicking on an icon on the canvas, a "icon" tab will be visible in the left panel, allowing you to choose any item from the Font Awesome collection.

Cloning elements

Items which have been setup in the "editableItems" array in js//modules/config.js can be cloned. Select the element which you want to clone and click the clone button in the left panel. Please note that cloned items will be inserted into the canvas right next to the original item.

In some situations, you might want to have the parent of the original item cloned, rather then the item itself. Consider the example of an unsorted list with "a" tags inside "li" tags. In this case, it's the containing "li" element which should be cloned, not the "a" element itself. To make this happen, make sure to add the class name "propClone" to the parent element in your element's .html file. For an example, please have a look at the navigation of the block "header1.html".

Exporting a site

Whenever the user is happy with the final result, the created markup can be exported by clicking the export button. The export feature will grab all the used HTML blocks for each created page and inserts these blocks into a copy of the HTML skeleton file. Once all pages are completed, all the HTML files are bundled into a ZIP archive together with the other external resources like stylesheets, Javascript files and images (as configured through the "save.php" file) which will be downloaded by the end user.

Multiple pages

The HTML Builder script allows users to create multiple pages at once. To add a new page, simply click the green button labeled "+ Add" just below the current pages list. You can alter the page names as well (please use names without the .html extension, these are added automatically during the export). When exporting the markup, the pages will use the same names. To delete a page, simply click the little delete icon next to the page you'd like to delete.

Responsive views

HTML Builder allows users to switch between different view modes, this to ensure the resulting page will look good on mobiles, tablets and desktop screens. To toggle between modes, use the three buttons to the left of the main toolbar.

The screen sizes for the view modes can be configured in the config.js module, by using the "responsiveModes" object.

Global blocks

HTML Builder allows users to configure so-called "global blocks". These are blocks that maintain the same appearance and settings across different pages. This feature comes in handy when configuring navigations and footers for example.

Each block on the canvas has a check box labeled "Global". When checked, changes made to this block will be applied to the same block on all pages in your site, assuming those other blocks are marked as "global" as well.

Using your own blocks

Even though the HTML Builder script comes with several HTML blocks ready for usage, the goal of this script is allow you to use with your own HTML template and your own HTML blocks.

For your HTML template to be compatible with the HTML Builder script, it needs to meet the following requirements:

  • The HTML template needs to have a modular structure, meaning it's composed of re-usable blocks. Such blocks can be headers, slideshows, blog posts, content sections, pricing tables, etc. Each of these blocks must be a direct child of the templates page container element! For example, the main page container is a DIV element with id="page"; then each of your blocks needs to be a direct child of this DIV container.

To setup your HTML template with HTML Builder, please follow the instructions below:

  1. Define your HTML blocks. We suggest creating an additional folder (named "elements" for example) in which you should place your HTML files containing your HTML blocks. Within the folder, you should also place your external resources such as stylesheets, Javascript files and images. Where you place these resources is basically up to you, as long as you make sure the HTML files within your folder can access these files.
  2. Each of your blocks will be placed inside it's own HTML file. This means you'll need to create a separate HTML file for each block (!) Within these HTML files, you'll need to make sure you reference all external resources required for this HTML block to function properly; this could be external CSS files, JS file or images. We suggest you load each HTML file inside your browser to check and make sure it functions and looks correct. Please note that within each HTML file, your block must be a direct child of the same page container block (!)
  3. Edit the config.js module (js/modules/config.js) and enter the correct value for the variable "pageContainer" on line 4 of this file. This value should be a jQuery selector (to be save, we'd suggest using an ID select, for example "#page") pointing to your main page container. Please note that you will need to run Browserify again to generate a new builder.js file. You can do this using the provided Jake file or use your own build tool.
  4. Create/edit your HTML skeleton file (skeleton.html) and make sure it sits within your elements folder (as a direct child). This is the HTML file used to create the final HTML files by the export function. It's important that within this file, you link to all the proper external resources like stylesheets, javascript files, images, etc.

    This HTML file also needs to contain the main page element discussed before, without any child elements! Also keep in mind that the skeleton.html file is referenced by the src attribute of the iframe around line 1938 in dist/index.html, if you change the name of the skeleton file, be sure to update the source attribute of this iframe as well.

  5. Once you have completed all of your HTML blocks, the final step is to create a JSON file which contains all the blocks categories and URLs to the HTML block file. For the correct structure of this JSON file, please take a close look at the provided file "elements.json". For each blocks you'll need to specify the height as well, this is important as it's used to calculate the correct height for the thumbnails as well as the blocks on the canvas.
  6. Finally, you might need to configure the export file, "_export.php". The two available variables for configuration are:
    1. $pathToAssets: this is an array containing all the folders within your elements folder which should be included in the exported ZIP. Please note that you only have to include those folders which are direct children of your elements folder. The export function will run through these folders and automatically include all files and folders found within the specified folders.
    2. $filename: this is name used for the final ZIP archive downloaded by the user.

Defining editable CSS attributes for HTML items

To keep track of your editable items, we've created an array in the config.js module (js/modules/config.js) named editableItems. This multi-dimensional array contains jQuery compatible selectors and an for each selector an array of CSS attributes (please have a look at the original config.js file for the correct syntax). When the script detects a color attribute ("color", "background-color", "border-color", etc) it will automatically activate the color picker.

By default, the script will show a regular text field for each CSS attribute (except colors like mentioned above). However, you can also configure a dropdown with a number of options to choose from. To achieve this, another Javascript array is used, named editableItemOptions. This array contains a combination of jQuery selector and CSS attributes as keys and an array with possible values as values. For the correct syntax to use, please have a look at the original "dist/config.js" file.

PLEASE NOTE: certain issues could arise when nesting editable tags; when clicking on an element which has a parent container element which is also editable, that parent container will be the one selected. You might want to pay special attention to this when setting up your editable items! Since the script uses jQuery based selectors, you can always specify specific classes to prevent this from being a problem.

Configuring the upload script (dist/_upload.php)

To be able to upload images from the HTML Builder script, you'll need to set two variables in "dist/_upload.php". The first one, $uploads_dir specifies the folder in which uploaded files are stored (make sure this folder is writable!). The second variable $relative_path specified the relative path between your block files and the upload folder (this path is used to load the image in the HTML Builder interface after uploading a file).

Using block thumbnail images instead of live iframes

If you're using a large number of blocks, using iframe for the live thumbnails can slow down your script. To provide a workable solution, as of version 1.5, HTML Builder can use images instead of iframes. This significantly speeds up the loading time of the script. To use images, simply add an additional value to the block's entry in your elements.json file. The name of this value should be "thumbnail" and it's value should be the path to the thumbnail image on your server.

Developing & modifying

The HTML Builder script is built using commonjs Javascript modules and to be able to use these modules in a browser environment, a tool named Browserify is used. This tool will process the modules and combine them into a single file (dist/js/builder.js) which can be loaded in a browser.

This method allows us to nicely divide our code into modules, but the downside is that after making a change to the source files, you will need to run the Browserify tool to generate an updated builder.js file.

When making changes to the source code, we'd suggest modifying the original modules and then running Browseify. However, theoretically, it's also possible to modify the generated file directly (dist/js/builder.js). If you decide to do this, please note that if you do decide the use Browserfiy at a later time, the changes in your dist/js/builder.js file will be overwritten.

The commonjs modules are located in js/modules/. We have chosen to use Jake.js as our build tool. So you can use either the bundled build file, or you can also use your own (like Grunt if that's your thing).

For further info regarding developing with HTML Builder, please have a look at README.md. If you have any questions or require assistance, please visit our help desk at https://selfhosted.net/support/

Complex blocks

Special care will have to be given to complex blocks. This applies specifically to blocks that contain Javascript which modifies the HTML in that block. Examples of such scripts are slideshows (the popular jQuery NivoSlider for example). The problem with such scripts is that the modified HTML is rendered on the canvas and when the site is exported, the modified HTML is used rather then the original, un-modified HTML.

To counter this problem, we have created a solution which uses an additional (hidden) iframe for such blocks. These hidden iframes do not allow Javascript to be executed and therefor will always contain the un-modified HTML. When changes are made to the canvas, these changes applied to both the frame on the canvas as well as to the hidden frame with the original HTML.

To make this solution work properly, some additional configuration is required:

1. Unique IDs
Elements that are editable (and which appear in your "ediatbleItems" array as well as in your "editableContent" array) will need to be assigned a unique ID. This uqniue ID is used to synchonize changes between the frame on the canvas and the hidden frame. If an element does not have a unique ID set, syncing won't work.

2. Place the block's Javascript in a separate function
The Javascript responsible for handling the slideshows (or other Javascript which modifies the HTML of the block) should be placed in a separate function. This function can be called whenever you'd like (on document ready or window load, etc). For an example, please refer to the "slideshow1.html" block (just before the closing tag of the BODY element).

3. Add the "sandbox" attribute the elements.json file
To apply this solution to a block, you will need to add the 'sandbox="true"' element to the array in elements.json (for an example, please refer to the "slideshow1.html" block recently added to "elements.json").

4. Add the block's Javascript function to elements.json
The Javadcript function from item 2 now needs to be added to "elements.json" using the "loaderFunction" attribute (for an example, please refer to the slideshow1 block in elements.json)

How should these blocks be edited when on the canvas?

This really depends on the nature of your block. You can add elements such as images to the "editableItems" array as you would normally. However, this will only work if the elements added to "editableItems" are still visible AND clickable after being modified by the slideshow scripts. Some slideshows hide the original images and display images created by the script instead. If this is the case, you won't be able to to use the image editor to edit the images in the slideshow and you should use the HTML source code editor instead.

Getting these complex blocks setup properly might take some trial and error. If you require assistance or need some advice, please don't hesitate to contact us via https://selfhosted.net/support/ as we're more then happy to help out!

Explained

Blocks

blocks are groups of HTML elements (div, ul, h1, p, etc). Examples of blocks can be:

  • Headers
  • Footers
  • Contact forms
  • Content sections
  • Slideshows
  • Portfolios
  • Etc

Each block should be a stand-alone item and should be independent from other blocks. This will allow the script to bundle blocks together to create a page.

Blocks are allowed to share CSS and Javascript with other blocks, as long as they don't require any other blocks to be present on a page to function properly (!) It's up to the template developer to decide on wether to separate all CSS and Javascript for each block, or wether blocks will share CSS and Javascript.

The page container element

The page container element is a HTML element (typically a DIV element is used) which holds all the HTML elements as direct children. The page container element is used in each HTML for your individual elements, as well as in your skeleton.html file. This page container element should also be configured in the js/modules/config.js file.

The Skeleton file (skeleton.html)

The skeleton.html file should somewhere on the same domain as the HTML Builder script (we suggest to keep it in the same folder as your blocks) and is used when exporting pages from the script. The skeleton.html file should:

  • Should have references to all external resources such as stylesheets, javascript file and images used by each and every block used within your script (!)
  • Should contain the page container element (as configured in js/modules/config.js) without any children (!) During the export process, the blocks will be added as children of the page container element.