mldblog: Templates
02010-Nov-13, Sat 11:00 in /mldblog [mldblog] [permalink]
This is part of a series of posts documenting the code of mldblog.

Template-Files

Templates are UTF-8 files, used to render mldblog's output. They can access variables to output them or use them in conditionals within the template.
There are two templates that are special, so they have their own section below: content_type.type and date.type.

Rendering Templates

mldblog::render_template($template_file, \%parameter) is responsible for rendering a template file.
The first parameter is a string containing the name of the template-file to render (e.g. head.html). $DIR_TEMPLATES is automatically prepended.
A hash-reference is the second (optional) parameter. It contains all the values that will be accessible by the template.

Consider the following hash to be used as the parameter:

$param = {
  a = 1,
  b = {
    b1 = 'foo',
    b2 = 'bar'
    },
  c = {
    d = {
      e = 'mouh'
    }
  }
};
The following table lists how to access those values in Perl or output them within a template.
PerlTemplate
$param->{a}<$a>
$param->{b}->{b1}<$b:b1>
$param->{c}->{d}->{e}<$c:d:e>

render_template() does one more thing: it adds mldblog::G as \%parameter->{G} to the parameter. If no parameter was specified, an empty one is created.
So every template that is rendered by render_template() has access to the global variables through <$G:VAR>.
e.g. <$G:title> outputs the title as defined in the configuration section of mldblog.pl.

Using Variables

The table above shows how to insert the value of a variable into a template. To do so, simple wrap them in a construct like this: <$VAR> where VAR is the "path" within the hash-reference as constructed above. (e.g. <$c:d:e>)

To insert fragments conditionally based on variables, you have to use one of the expressions listed in the table below to wrap the conditional snippet. (e.g. <?a=1>a is 1</?a><?a!=1>a is not 1</?a>)

The following table lists all available operators:

if defined(VAR)<?VAR>
if !defined(VAR)<?VAR!>
if VAR == x<?VAR=x>
if VAR != x<?VAR!=x>
if VAR > x<?VAR^x>
if VAR < x<?VAR!^x>

Of course, nested conditionals are possible if different variables are used.

<?a^5>a is big<?n:x=1> and n:x is one</?n:x></?a>valid
<?a^5>a is bit<?a=6>, but at its smallest bigness</?a></?a>invalid

content_type & date

content_type.type is special, because it is rendered by mldblog::get_content_type($type). This function reads only the very first line of the template file content_type.$type and performs no variable interpolation.

date.type is rendered by using mldblog::render_date($template_file, $time).
The first parameter is handled like the first parameter to render_template() (because it is used internally).
$time is a scalar containing the Epoch date/time that will be rendered. If $time is not specified the current time is used.
The following variables are available to the template rendered via render_date():

yearYear
monthMonth (numeric 1-12)
month0Month (numeric 01-12)
dayDay (numeric 1-..)
day0Day (numeric 01-..)
hourHour (0-24)
hour0Hour (00-24)
minuteMinute (0-59)
minute0Minute (00-59)
monthnameName of month (English)
daynameName of day (English)
Each of these variables are contained within two namespaces: local and ut for values in the locale (server) timezone or UTC.
e.g. <$ut:year>-<$ut:month0>-<$ut:day0>

Templates Used by mldblog

The templates used by mldblog and their parameters, depend on the number of entries to be displayed. Whatever the number of entries is, content_type.type and date.type are always used.

Single Entry

head, entry and foot are used. Each of them being rendered with the entry's hash as parameter. An entry's hash is generated by read_entry() and may be extended or changed by plug-ins.
mldblog itself generates the following hash:
$e = {
  path,
  id,
  moddate,
  header = {
    title,
    date,
  }
}
If other key/value-pairs are listed in an entry's file, besides Title and Date they are automatically converted to lowercase and added to header.
$e = {
  header = {
    x-tags,
    x-social,
    x-comments-disabled,
  }
}

Multiple Entries

head, entry and foot are used, but only entry is rendered with the entry's hash as parameter.

No Entries

The template files head, empty and foot are used. All of them are rendered without an entry-specific parameter, so only global variables are available to them.

To conveniently sum it up:

0 entries1 entry>1 entries
head undef $entry undef
entry - $entry $entry
empty undef - -
foot undef $entry undef
No comments
Post Comment