Getting Started
Nuts and Bolts

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:

  • *.web
  • *.template
  • *.keyword
  • *.config
  • *.dynamic.rb
  • *.mapping
  • *.css

  • You can prefix with any name you like as long as there are no spaces between the words, instead you must use an underscore i.e This_is_my_new_page.web, the menu code automatically splits the words when creating the menu. The *.web file becomes the name of the HTML file.

    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

    In the template file there is a -last published Sat May 21 18:01:11 BST 2005 keyword which will be replaced with the output of this published method when you run StaticWeb. You can add in your own methods here and create new keywords in the template. You can also create helper methods if you like as long as you don't use underscores in their names.

    *.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:

  • cd exampleSite/src
  • nano -w index.template
  • Next to the [CONTENT] keyword add [AUTHOR]
  • Now open up the index.config file and create some data for the AUTHOR keyword:

  • nano -w index.config
  • add AUTHOR:Your Name

  • Now all you need to do is run StaticWeb to see your new keyword in action:
  • cd ../.
  • staticweb
  • konqueror output/index.html
  • Right, Let's make a dynamic keyword now. Open up the index.dynamic.rb file and edit as follows:

  • cd src
  • nano -w index.dynamic.rb

  • Add the following code to the dynamic file:
    1. def date_DATE
    2. return "Today's date is #{Time.now}"
    3. end

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

  • nano -w index.template
  • next to the [AUTHOR] keyword add [DATE]
  • Excellent! Run StaticWeb and view your changes:

  • cd ../.
  • staticweb
  • konqueror output/index.html
  • 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 !


    Copyright 2004 Kingsley Hendrickse. All rights reserved. -last published Sat May 21 18:01:11 BST 2005