WebMake Documentation (version 1.1)

The <wmmeta> Tag

WebMake can load metadata embedded in any content chunk, and use this metadata at any point in the site. In addition, metadata can be set externally from the content using the <metatable> and <metadefault> tags.

A metadatum is like a normal content item, except it is exposed to other pages in the index.wmk file. Normally, you cannot reliably read a dynamic content item that was set from another page; if one content item sets a variable like this:

<{set foo="Value!"}>

Any content items evaluated after that variable is set can access ${foo}, as long as they occur on the same output page. However if they occur on another output page, they may not be able to access ${foo}.

To get around this, WebMake includes the <wmmeta> tag, which allows you to attach data to a content item. This data will then be accessible, both to other pages in the site (as $[contentname.metaname]), and to other content items within the same page (as $[this.metaname]).

Think of them as like size, modification time, owner etc. on files; or member variables in an object-oriented language. Another good way to think of it is as "catalog data", as opposed to "narrative data", which is what a normal content item is. (thanks to Vaibhav Arya, vaibhav /at/ mymcomm.com, for that analogy.)

Examples of metadata that can be useful, and suggested names for that data, are as follows:

Title

the title of a content item. The default title for content items is (Untitled). (built-in)

Score

a number representing the "priority" of a content item; used to affect how the item should be ranked in a list of stories. The default value is 50. (built-in)

Abstract

a short summary of a content item. (optional)

Up

used to map the site's content; this metadata indicates the content item that is the parent of the current content item. This metadatum is used to generate dynamic sitemaps. (built-in)

Here's some built-in "magic" items of metadata that do not need to be tagged with the <wmmeta> tag. Instead, they are automatically inferred by WebMake itself:

declared

the item's declaration order. This is a number representing when the content item was first encountered in the WebMake file; earlier content items have a lower declaration order. Useful for sorting.

url

the first <out> URL which contains that content item (you should order your <out> tags to ensure each stories' "primary" page is listed first, or set ismainurl=false on the "alternative" output pages, if you plan to use this). See also the get_url() method on the HTML::WebMake::Content object.

is_generated

0 for items loaded from a <content> or <contents> tag, 1 for items created by Perl code using the add_content() function.

mtime

The modification date, in UNIX time_t seconds-since-the-epoch format, of the file the content item was loaded from. Handy for sorting.

More suggested meta tags, and their formats, are listed at the end of this document.

Note that content items representing metadata cannot, themselves, have metadata.

How to Use It

Meta-data is set from within a content chunk using the <wmmeta> tag; this tag is automatically stripped from the content when the content is referenced. It can be used either as an XML-style empty tag, similar to the HTML <meta> tag, if it ends in />:


  <wmmeta name="Title" value="Story 1, blah blah" />

or with start and end tags, for longer bits of content:


  <wmmeta name="Abstract">
    Story 1, just another story.
  </wmmeta>

As you can see, each item of metadata needs a name and a value. The latter format reads the value from the text between the start and end tags.

For efficiency during subsequent site builds, metadata is cached in the site cache file, so it will not need to be re-read from the original content chunk unless that content chunk is modified again.

Meta tag names are case-insensitive, for compatibility with HTML meta tags.

Referring to Metadata

Metadata is referred to using the deferred content ref format:

$[content.metaname]

Where content is the name of the content item, and metaname is the name of the metadatum. So, for example, $[blurb.txt.title] would return the title metadatum from the content item blurb.txt.

Any content chunk can access metadata from other content chunks within the same <out> tag, using this as the content name, i.e. $[this.title] . This is handy, for example, in setting the page title in the main content chunk, and accessing it from the header chunk.

If more than one content item sets the same item of metadata inside the <out> tag, the first one will take precedence.

The example files "news_site.wmk" and "news_site_with_sections.wmk" demonstrate how meta tags can be used to generate a SlashDot or Wired News-style news site. The index pages in those sites are generated dynamically, using the metadata to decide which pages to link to, their ordering, and the titles and abstracts to use.

Suggested Metadata Names

The tags marked (built-in) are supported directly inside WebMake, and used internally for functionality like building site maps and indices. All the other suggested metadata names here are just that, suggestions, which support commonly-required functionality.

Also note that tag names are case-insensitive, they're just capitalised here for presentation.

Title

the title of a content item. The default title for content items is (Untitled). (built-in)

Score

a number representing the "priority" of a content item; used to affect how the item should be ranked in a list of stories. The default value is 50. Items with the same score will be ranked alphabetically by title. (built-in)

Abstract

a short summary of a content item.

Section

the section of a site under which a story should be filed.

Author

who wrote the item.

Approved

has this item been approved by an editor; used to support workflow, so that content items need to be approved before they are displayed on the site.

Visible_Start

the start of an item's "visibility window", ie. when it is listed on an index page. (TODO: define a recommended format for this, or replace with DC.Coverage.temporal)

Visible_End

the end of an item's "visibility window", ie. when it is listed on an index page.

DC.Publisher

a Dublin Core tag. The organisation or individual that publishes the entire site.

The Dublin Core is a whole load of suggested metadata names and formats, which can be used either to replace or supplement the optional tags named above. Regardless of whether you replace or supplement the tags above internally, it is definitely recommended to use the DC tag names for metadata that's made visible in the output HTML through conventional HTML <meta> tags.

Why Use Metadata

Support for metadata is an important CMS feature.

It is used by Midgard and Microsoft's SiteServer, and is available as user-contributed code for Manila. It provides copious benefits for flexible index and sitemap generation, and, with the addition of an Approved tag, adds initial support for workflow.

It allows the efficient generation of site maps, back/forward navigation links, and breadcrumb trails, and enables index pages to be generated using Perl code easily and in a well-defined way.

Example


  <content name="foo">
    < wmmeta name="Title" value="Foo" />
    < wmmeta name="Abstract">
      Foo is all about fooing.
    </ wmmeta>

    Foo foo foo foo bar. etc.
  </content>

WebMake Documentation (version 1.1)