Nuts and Bolts

Overview of Architecture

StaticWeb works by having data in specific configuration files which are combined at runtime to build the html pages. There is a template file that contains HTML with keywords, the keywords file contains a list of keywords and a corresponding file to look in for the data to swap for the keyword. This will become more clear as you read on.

File Structure

StaticWeb requires you to have a src folder in your working directory i.e the exampleSite directory from the Getting Started tutorial.

The src folder must contain each of the following files:

When you run StaticWeb it automatically creates an ouput folder next to the src folder and deposits the newly built HTML files in there along with copies of any CSS files from the src directory.

You can only run the StaticWeb command from a directory that contains the target src directory. You cannot run it in the src directory itself or anywhere that doesn't have a src directory. I've tried to provide helpful error messages where appropriate.

*.web Files

The *.web files contain the main HTML content for the page. When you run StaticWeb the *.web files are referenced by the *.keyword files CONTENT line and so when the HTML page is built it looks at the content line to see which *.web file it should use to replace the [CONTENT] keyword with in the *.template file. In short for every *.web file a corresponding HTML file is built with the same name as the *.web prefix.

*.template Files

The *.template files are the first part of the HTML layout and design (the second part being the CSS). The *.template files contain HTML code interspersed with keywords such as [CONTENT]. It is these keywords that are replaced with data from the configuration files when you run StaticWeb.

*.keyword Files

The *.keyword files contain a list of keywords and a corresponding file to look in to get data to swap for the keyword in the template files. The *.keyword entries must always point to other files.

*.config Files

The *.config files contain specific data corresponding to a keyword found in the template file. In the *.config file you create the keyword and data seperated by a : (colon). i.e. in the template file you might have [AUTHOR], and in the config file AUTHOR:Kingsley Hendrickse. When StaticWeb runs the authors name will be substituted for the [AUTHOR] keyword in the template file.

*.dynamic.rb Files

There can be only one *.dynamic.rb file and it contains Ruby methods of which the output is substituted for the corresponding keyword file in the template.

The methods in the dynamic file must be named anymethodname_KEYWORDNAME, where the method name must be all letters and then have an underscore between it and the chosen keyword. You must also return the result as a string.

Lets take a look at the published method in the default index.dynamic.rb

1. def published_PUBLISHED
2. return "-last published #{Time.now}"
3. end

*.mapping Files

There can only be one mapping file and it contains the master mapping which controls which files to look in when the HTML is built. Each .web page you want to build an HTML page for has to have an entry in the mapping file along with which config file to use, which template file and which keyword file. Actually I'll be removing the keyword file in the future as each web file must a keyword file of the same name.

The mapping file is one of the things that gives StaticWeb such flexibility. You can choose to make HTML files from different templates and config files all at the same time.

*.css Files

These are just your regular CSS files, that contain layout, style and design information.

Customizing your Website

Now we've got a feel for how things work. I'm going to show you how to make 2 new keywords for the exampleSite. One static and one dynamic.

Let' start with the static Keyword. Open up your index.template file and add a new keyword as follows:

Now open up the index.config file and create some data for the AUTHOR keyword:

Right, Let's make a dynamic keyword now. Open up the index.dynamic.rb file and edit as follows:

1. def date_DATE
2. return "Today's date is #{Time.now}"
3. end

Next edit the index.template and add the keyword DATE:

Excellent! Run StaticWeb and view your changes:

Hopefully you will see something like this:

Well you should now be well on your way to building awesome static websites with StaticWeb.

Good Luck !