HDF Dataset

Clearsilver 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

# The second is a nested elements scheme:
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.

Attributes

Any HDF Node can carry attributes along with it. An attribute is of the form [key=value, ...] and occurs immediately after the hdf node name. In practice this has mostly been used to support internationlization tools, by marking translatable strings in HDF with [lang].

Images {
      top {
	height [type=num] = 512
	width [type=num] = 512
	url [url] = /img/loc/top.gif
	alt [lang, lang=en, desc="The end of \n the world?"] = ClearSilver Rocks!
      }
    }

Copy Subtree

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.

Multi-Line Strings

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