html-builder

html-builder

Completeyly hacked together as requirements came up, but it works!

Added websocket client. When finished building it will send a reload msg to the server to instruct the server to send a reload msg to the browser.

Use nodejs modules in the browser! No browserify!

It now concatenates your css and js files in production mode and adds a cache stamp to all static resources, to work together with bb-server.

The main file html-builder.js exports one function: 'build'. This function takes a dataFileName. If it is not given it will look for build/recipe.js in the current working directory.

If the function build is called it will build a site using the info given in the recipe.

buildMonitor.js is a command line utility that monitors and builds a site using html-builder whenever there are changes in the directory given as its first argument. If no argument is given it monitors the ./build directory. It looks for recipe.js in the monitored directory to pass on to html-builder.

The recipe.js file needs to export an object describing the site.

var exports = {
	[...]
}

What follows is a list of properties that can be defined on the exported object:

• verbose: boolean
  Verbose output to the console
• prettyPrintHtml: boolean
  Whether to generate pretty formatted html (buggy)
• paths: object
  • root: string
    base directory
  • partials: string
    where to find partials relative to root, can be overridden per template
  • out: string
    where to save produced files
  • js: string
    where to save produced js files
• routes: array
  list of route descriptions for angular.js each of the format: [ path, file, controller]
• partials: object
  See below

The html-builder builds one or more html files by nested insertion of other html fragments or files. Every html fragment/file apart from toplevel html files need to be given an id. By referring to these ids inside the fragments/files the html-builder can build the toplevel html files, using mappings listed in partials.

A fragment is called a partial, and the listing of partials is the main part of the recipe.js file. There is no dependency management so partials need to be defined before they can be used in other partials.

The main types of partials are:

• ids Plain string literals. These get inserted as is.
• metaBlock
  An easy way to build a metablock
• linkBlock
  Listing of css files
• scriptBlock
  Definition of one or more script blocks
• slideShow
  listing of definition of slide shows
• menu
  Definition of one or more menus
• template

Every template can have its own id, and needs a src. The src can be a file on disk or an id of a previously defined partial. A template can write its result to disk under the name given to the out property. Finally the mapping property of a template maps ids found in the source to partials defined earlier and inserts them.

Partials can be referred to by their id or by giving the name of a file on a disk. The ids in the source need to be postfixed with the tagIdPostfix (by default --). This can be set site wide or overridden per template. The location of partials on disk is also set site wide, but can be also overridden per template. A mapping from an id can refer to one partial or an array of partials. When an array they will be inserted one after the other.

For an example of a complete recipe.js see my repo js-project

Or checkout the documentation

I wrote this thing because I don't want to write html if I can help it. Especially not repetitive html, such as listings of source or css files. Html is unreadable, especially if the page gets large because of its verbosity, so I wanted to keep it manageable by breaking it up. I can now work on a part of a site, or a little corner of it and every time I save the fragment the site gets rebuilt and reloaded in the browser using live page or moz-reload in emacs or similar. The only thing is it gets a bit confusing which partial contains which other partial(s). Maybe I should draw a map of it. That should help.

The resulting html doesn't look too pretty though. You could achieve the similar result by using a templating library such as handlebars etc but these build the result in the browser, not necessary always. Plus I don't like the magic. With this builder I am in control of what happens.

What does appeal is the new html5 custom elements and html imports. Combined with ractive.js and possibly postal.js, both easily understood libraries, it might be possible to put something together I can use in the future instead of this html-builder, dropping angular (way too much magic..).