The dataset and HDF Files

It is often convenient to load elements of a dataset from disk. Normally data is loaded from a ClearSilver file format called HDF, although it could easily be loaded from XML or another format. HDF stands for Hierarchical Data Format (yes, another HDF). It supports two different syntax for representing the dataset hierarchy which can be intermixed arbitrarily. The first is a simple dotted path scheme:

Page.Name = My Index
Page.URL = /myindex.html
Page.Menu.0 = Home
Page.Menu.1 = Preferences
Page.Menu.2 = Help
Page.Menu.3 = Support

Page {
  Name = My Index
  URL = /myindex.html
  Menu {
    0 = Home
    1 = Preferences
    2 = Help
    3 = Support
  }
}

The hierarchy within an HDF file can be arbitrarily nested and contain any data elements desired. For instance, to extend the format of the Menu above, we could add:

Page {
  Menu {
    0 {
      Name = Home
      URL = /
    }
    1 {
      Name = Preferences
      URL = /prefs
    } 
    2 {
      Name = Help
      URL = /help.html
    }
    3 {
      Name = Support
      URL = /feedback/
    }
  }
}

Because APIs for HDF support reading and writing files in these formats, HDF can serve as a great configuration or persistence language. However, its primary purpose here is to load static elements into the dataset for use in a ClearSilver template.

When a ClearSilver template is rendering, it can reference specific variables in the dataset or iterate over all of the elements at a specific point in the dataset hierarchy. For example, a CS template which was rendering the HDF dataset above might iterate over Page.Menu, rendering each menu item's .Name and .URL elements.

There are two more important parts of the HDF file syntax.

1. A name can copy the contents of another name by using a colon instead of an equals sign. For example,

   Page.Name : Page.Menu.0.Name

   This means that Page.Name is the same as Page.Menu.0.Name. Note that Page.Menu.0.Name has to be defined before you can copy it into Page.Name.
2. A name can be set to a multi-line string value. This uses a syntax similar to standard UNIX shell/Perl syntax. For example:

   Page.Name << EOM
   This is my multi-line page name.
   Isn't it spiffy?
   EOM