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/.
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 notHTML 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 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:
To be able to use HTML Builder, you must have the following:
- Apache webserver (Windows servers will probably work, but are not supported)
- An FTP tool to upload the files
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:
||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.|
||This is the Jake executable to build the application on a Windows PC.|
||This is the Jake executable to build the application on a Linux or Mac computer.|
||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).|
||This folder contains all the source code for the entire application.|
||This file contains the NPM module list. You'll need this if you're planning to modify the application's source code.|
||Markdown file containing info about the application, including the current version.|
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.
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.
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.
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).
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.
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.
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.
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
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.
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.
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:
- 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 (!)
- 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.
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.
- 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.
Finally, you might need to configure the export file, "_export.php". The two available variables for configuration are:
- $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.
- $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.
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
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/
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.
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").
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!
blocks are groups of HTML elements (div, ul, h1, p, etc). Examples of blocks can be:
- Contact forms
- Content sections
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.
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 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.