Using File Metadata Fields

When you upload images or other files, you can choose to provide information about those images (often called metadata). Your initial Webvanta site is configured for a single metadata text field, the caption, as well as two taxonomy-type metadata fields, categories and tags.

If these are the only metadata you need, you don't need to do any configuration; just enter the caption and select the required categories and tags when you upload the image.

You can also edit the caption or other metadata at any time by selecting the file in the Files admin page, and then clicking the Edit button.

Adding Custom Fields

If you want additional metadata fields or taxonomies, edit the Global Setting named asset.metadata.settings. This setting has a string, in JSON format, that defines the custom metadata fields:

[{"mime": "*/*", "fields": [{"name": "caption"}]}]

This looks rather technical, we realize, and we plan to replace the editing of this string with a nice widget before too long, but for now, you need to modify this string to add metadata fields. You just add as many items as you want, separated by commas, in the same format as the "caption" item. For example, this setting will provide metadata fields for caption, author, and date:

[{"mime": "*/*", "fields": [{"name": "caption"}, {"name": "author"}, {"name": "date"}]}]

You can optionally specify that a custom metadata field get a multi-line text area, instead of a simple text field, which is helpful if you expect to enter a long description, for example. Here's an example that creates a single metadata field, called "description", which get a four-line text area for entry:

[{"mime": "*/*", "fields": [{"name": "description", "type": "textarea", "height": "4"}]}]

Associating Taxonomies with Files

Using the syntax described above, you can add any number of text metadata fields, and the category and tags taxonomies are automatically associated with all files.

If you want to use other taxonomy fields, you need to use the "version 2" format. Here's an example:

[{"mime":"*/*","version":"2","fields":[{"name":"caption","label":"Title"},{"name": "credit"},{"name":"company","type":"taxonomy","value":"company!*"}]}]

Note the addition of the version setting, which enables the new behavior. If the version is set to 2, then the category and tag taxonomies are not associated with files; only taxonomies that you specify are used.

This example illustrates several feature of the version 2 capabilities:

• If "label" is defined, it is used to label the field in the upload/edit form. When accessing the field in your code, use the name rather than the label. If the label is not defined, then a capitalized version of the name is used to label the field.
• To associate a taxonomy with files, specify the type as "taxonomy". For the value, use the name of the taxonomy. (As with text metadata fields, you can optionally specify a label.)
• If you add an exclamation point (!) after the name of the taxonomy, then a tag-cloud with an 'add new term' link is shown on the edit/upload form. Using the 'add new term' link, you can enter a taxonomy term that does not already exist. If you do not use an exclamation point, a tag-cloud of all taxonomy terms is shown without the 'add new term' link (the widget will use a tree structure with checkboxes if the field is a hierarchical taxonomy).
• If the taxonomy name is followed by an asterisk (*), then multiple selection is allowed; otherwise, only a single term can be specified. If used in combination with the exclamation point, the asterisk must follow the exclamation point.

Using Metadata Fields in Your Pages

To access the metadata fields, you must be in an asset context, which is typically set via the w:assets tag. For example:

<w:assets tag="cats">
  <img src="<w:path rendition='medium' />" />
  <p><w:caption /></p>
</w:assets>

This code repeats the two inner lines for every image that has the tag "cats". The first line displays the "medium" rendition of the image, and the second line displays the caption.

If you add custom metadata fields, each is accessed by a corresponding w:fieldname tag.

Working with Article Icons

A slightly different technique is needed when you need to access the metadata for an article's icon image. In this case, the WebvantaScript context is set for the article, typically by being on an item page:

<w:kb:item>
  <w:name />
  <img src="<w:icon />" />
  <w:body />
</w:kb:item>

With this code, however, there is no asset context available to enable you to access the caption for the icon image. So you must use the two-part form of the w:icon tag, changing the code above to something like the following:

<w:kb:item>
  <w:name />
  <w:icon>
    <img src="<w:assets:path />" />
    <p><w:assets:caption /></p>
  </w:icon>
</w:kb:item>

This sets up a context for the icon image, so you can then access it's file path using w:assets:path, and the caption and any other metadata using the usual WebvantaScript. (Note that the assets prefix is required in the tags that access the individual fields.)