The <media> Tag

WebMake allows you to refer to files and web pages symbolically, separating the site layout from the URL structure, and avoiding later problems with dangling links when a page's URL is changed. This is done using $(url_refs).

This works well for content items defined in WebMake, such as output files defined using the <out> tag. However it is not handy when dealing with a images or other files that are not generated using WebMake.

Therefore media files, such as images, and external, non-WebMake-controlled files, can be searched for using the <media> tag. This tag allows you to search a data source (directory, etc.) for a pattern.

Note that data sources which do not map to files in a filesystem, or other methods accessible to a web browser browsing your site, do not make sense for the <media> tag; so, for example, the svfile: protocol is not supported, as a web browser cannot load an image from a CSV file. As a result, currently only one data source protocol can be used with the <media> tag, namely file:.

Attributes Supported By Datasource Tags

src

All datasources require this attribute, which specifies a protocol and path, in a URL-style syntax: protocol:path . file: is the default protocol, if none is specified.

name

This attribute is used to specify the pattern of data, under this path, which will be converted into content or media items. The part of the data's location which matches this name pattern will become the name of the item. Typically, WebMake glob patterns, such as "*.txt" or ".../*.html" are used.

skip

A pattern which should match filenames that should be skipped. Files that match this pattern will not be included as content or media items, or as metatables. Glob patterns, again, are used here.

prefix

The items' names can be further modified by specifying a prefix and/or suffix; these strings are prepended or appended to the raw name to make the name the content is given.

suffix

See above.

namesubst

a Perl-formatted s// substitution, which is used to convert source filenames to content names. See the example under The File: Protocol, below.

nametr

a Perl tr// translation, which is used to convert source filenames to content names.

listname

a name of a content item. This content item will be created, and will contain the names of all content items picked up by the <contents> or <media> search.

metatable

a search pattern, similar to name above, which provides filenames from which metadata will be loaded.

metatableformat

The format for the above metatable files.

In addition, the attributes supported by the content tag can be specified as attributes to <contents>, including format, up, map, etc.

Also, the attributes supported by the <metatable> tag can be used if you've specified a metatable attribute. Note that metatableformat should be used instead of format, as format is already used for the content items.

The content blocks picked up from a <contents> search can also contain meta-data, such as headlines, visibilty dates, workflow approval statuses, etc. by including metadata.

The file: protocol loads content from a directory; each file is made into one content chunk. The src attribute indicates the source directory, the name attribute indicates the glob pattern that will pick up the content items in question.

<contents src="stories" name="*.txt" />

The filename of the file will be used as the content chunk's name -- unless you use the namesubst command; see below for details on this.

Note that, for efficiency, the files in question are not actually opened until their content chunks are referenced using ${name} or get_content("name").

Normally only the top level of files inside the src directory are added to the content set. However, if the name pattern starts with .../, the directory will be searched recursively:

<contents src="stories" name=".../*.txt" />

The resulting content items will contain the full path from that directory down, i.e. the file stories/dir1/foo/bar.txt exists, the example above would define a content item called ${dir1/foo/bar.txt}.

If you use the namesubst command, the filename will be modified using that substitution, to give the content item's name. So, for example, this contents tag:

<contents src="stories" name="*.txt" namesubst="s/.txt//" />

will load these example files as follows:

Filename	Content Name
stories/index.txt	${index}
stories/foo.txt	${foo}
stories/directory/bar.txt	${directory/bar}
stories/zz/gum/baz.txt	${zz/gum/baz}

You can now load metadata from external files while searching a directory tree for content items or media files. This allows you to load image titles, etc. from files which match the filename pattern you specify in the metatable attribute.

The attributes supported by the <metatable> tag can be used in the datasource tag's attribute set, if you've specified a metatable attribute, allowing you to define the format of the metatable files you expect to find.

There's one major difference between normal metatables and metatables found via a data source; the names in this kind of metatable refer to the content or media object's filename, not its content name.

In other words, the names of any content items referred to in the metatable files will be modified, as follows:

• if the name attribute contains .../, then the content items could be deep in a subdirectory. The metatable file does not have to contain the full path to the content item's name; it can just contain the item's filename relative to the metatable itself.
• if a namesubst or nametr function is specified, the content names in the metatable will be processed with this. Again, this means that the metatable data just has to provide the filename, not whatever the resulting content item will be called.

These features will hopefully make the operation a little more intuitive, as users who add files to a media or contents directory will not have to figure out what the resulting content item will be called; they can just refer to them by their filename, when tagging them with metadata.

  <media src="file:images" name=".../*.gif" />
  <media src="file:images" name=".../*.jpg" />