Introduction

What it is HTML Builder (front-end) is a Javascript script which allows publishers of HTML templates to provide their customers with a quick and easy way to customise 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 elements to demonstrate it's usage (these are the same elements as used in the online demo). You are free to use the elements in whatever way you like.

HTML Builder runs (almost) entirely in the browser. The only server side code is in the form of a single PHP file used for exporting HTML markup.

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

MAKE A BACKUP BEFORE UPDATING!!

Before updating, you should copy all the config data from your /js/builder.js (at the top of the file) as you'll need to enter this data into the updates builder.js file.

Next, simply replace all the files in the script folder except for the following items:

• /elements.json
• /elements/* (all files and folders inside your /elements folder)

Finally, place your config data back into the updated /js/builder.js file and you're all set.

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 a single PHP file ("save.php", used for exporting created markup). It's built using the Flat UI pro interface kit (http://designmodo.com/flat)

The following folders are part of the Flat UI Pro kit:

• /bootstrap (contains basic bootstrap items)
• /css (contains custom css)
• /custom (contains less+css)
• /fonts (contains the fonts used in Databased)
• /images (contains images used in Databased)
• /js (contains the Flat UI Pro javascript files)
• /less (contains the original Flat UI Pro less files)

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

Configuration / Using builder with your own template

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

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 elements. Such elements can be headers, slideshows, blog posts, content sections, pricing tables, etc. Each of these elements 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 elements 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 elements. We suggest creating an additional folder (named "elements" for example) in which you should place your HTML files containing your HTML elements. Within the elements 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 elements folder can access these files.
2. Each of your elements will be placed inside it's own HTML file. This means you'll need to create a separate HTML file for each element (!) Within these HTML files, you'll need to make sure you reference all external resources required for this HTML element 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 element must be a direct child of the same page container element (!)
3. Edit /js/builder.js and enter the correct value for the variable "pageContainer" on line 3 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.

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 will also need 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 135 in 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 elements, the final step is to create a JSON file which contains all the element categories and URLs to the HTML elements file. For the correct structure of this JSON file, please take a close look at the provided file "elements.json". For each element 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, "save.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.

To keep track of your editable items, we've created an array in "builder.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 "builder.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 "builder.js" file.

PLEASE NOTE: certain issues could arise when nesting editable tags; when clicking on an elements 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.

To be able to upload images from the HTML Builder script, you'll need to set two variables in "/iupload.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 element files and the upload folder (this path is used to load the image in the HTML Builder interface after uploading a file).

If you're using a large number of elements, 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 element'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.

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 http://chillyorange.com/basic-support/ as we're more then happy to help out!

Drag and drop

HTML Builder allows users to drag HTML elements 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. Elements can be delete individually or all elements on the current page can be deleted in one go.

Content editing

The HTML Builder script can also be used to edit written content inside each element (simply by setting the "building mode" to "content"). 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/builder.js", and depending on the exact configuration, certain text elements might not be editable.

To configure editable text elements, an array named "editableContent" is used in /js/builder.js. This array should contain proper jQuery selectors targeting elements which inner text is allowed to be edited. You either target individual elements, or a group of elements. In case you're targeting a group of elements, it's best to wrap these elements within a parent DIV container and add this container DIV to the "editableContent" array.

Style/detail editing

The HTML Builder script also allows for basic CSS editing and link editing. Using the built-in CSS editor, end-users can customise 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.

Link editing

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/builder.js file. To edit links on the canvas, firstly select the Details building mode, this will allow you to select links. 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.

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

Image editing

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/builder.js file. To edit images on the canvas, firstly select the Details building mode, this will allow you to select images. When selected, a "image" tab will be visible in the left panel, allowing you to either upload an image or enter a URL manually.

Video editing

HTML Builder allows users to edit Youtube and Vimeo videos as well. To edit a video, switch to "Details Mode" and 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/builder.js file. To edit icons on the canvas, firstly select the Details building mode, this will allow you to select icons. When selected, a "icon" tab will be visible in the left panel, allowing you to choose any item from the Font Awesome collection.

Cloning items

Items which have been setup in the "editableItems" array in /js/builder.js can be cloned. Switch to "Details" building mode, select the item which you want to clone and finally click the clone button from 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 element "header1.html".

Export HTML

Whenever the user is happy with the final result, the created markup can be exported by click the blue export button. The export feature will grab all the used HTML elements for each created page and inserts these elements 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.

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

How does it work?

The HTML Builder script uses iframes to create thumbnails of all your elements (what you're seeing are actual renderings of your elements, scaled down to create the thumbnails).

When an item is dragged onto the canvas, the iframe is copied and scaled up to fit nicely within the canvas. Each element on your canvas remains within it's own iframe.

When switching to content mode, each frame will see it's "designMode" attribute set to on, allowing the user to make changes to the content. Since Internet Explorer has some issues with "designMode" and scaled down iframes, the content mode is disabled on Internet Explorer browsers.

When switching into style/detail editing mode, the end-user can alter a set of pre-defined CSS attributes for certain elements (the script's administrator has to specify which CSS attributes for which elements are allowed to be edited). When in style/detail editing mode, the end-user can hover over elements on the canvas and when an element is editable, a red dashed outline will appear around that element. If then clicked, a panel will slide in from the left side showing the CSS attributes which can be edited for the clicked item.

When hitting the export button, the script will loop through each page, collecting the elements and inserting them into the main page container in a copy of the "skeleton.html" file after which the markup and other files will be downloaded.

Elments

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

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

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

Elements are allowed to share CSS and Javascript with other elements, as long as they don't require any other elements 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 element, or wether elements 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/builder.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 elements) 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 element used within your script (!)
• Should contain the page container element (as configured in /js/builder.js) without any children (!) During the export process, the elements will be added as children of the page container element.