BibDesk's templates are based on Key Value Coding, which is an intuitive way to describe properties of objects. We will not attempt to give a full explanation of this concept. We only give some general hints that will be useful for writing templates for BibDesk export and services. For more information, see Apple's Key Value Coding Guide.
A key is simply a name for a property of an object. Keys usually contain just letters.
Properties of objects can have properties themselves. You can find the property using a key path.
A key path is simply several keys joined together by dots. For example the following key path describes
the property named propertyKey of a property named valueKey of some object.
valueKey.propertyKey |
A property can sometimes describe a collection of objects. For example the key publications describes
the collection of publication objects of a document. These collection keys are handled slightly
different from keys describing single values, both in key value coding and in BibDesk templates.
The main difference for key value coding with collection keys is the meaning of key paths.
For collections, the value behind the dot is the name of a property of the items in the collection,
not of the collection itself. For example if collectionKey describes some collection property and
valueKey is the name of a property of the items in the collection, then the key path collection.valueKey
will describe another collection, which is made from all the properties named valueKey of the original items.
For example, the key path publications.title will give the collection of all the titles of the publications.
When you want to get a property of the collection rather than the items, you need to insert an
@ at the beginning of the key. A collection can have two types of properties.
The first type of property for a collection is a property that modifies the whole collection, returning a new collection.
For example take a collection of all the fields of some publication. Then you can modify this collection by
removing all the fields that have not been set. The key for this property is @nonEmpty. So the full key path
for all the non-empty fields would then be allFields.@nonEmpty, which you can then use in a collection template tag.
We call them collection modifier keys.
Another type of a property for a collection is one that does not return another collection, but rather
a single value property associated to the collection. For example, the key path collectionKey.@count
will give the number of items in the collection. We call those keys collection value keys.
Key value coding is used in templates for BibDesk's templated export feature. An export template can contain certain special template tags, which are similar to HTML tags, and are named by a key path. The main idea of the templating feature is that the tags are replaced by the value of the property described by the key path. There are three types of template tags: value tags, collection tags and condition tags.
The simplest tags are value tags. They simply describe a single property value, like the string value. The tags have the form
<$valueKey/> |
Or you can use a key path.
<$valueKey.modifierKey/> |
You can often think of the extra components of the key path after the dot as modifiers of the properties.
For example assume that the property describes a string value. Then you could use a modifier key
capitalizedString that simply capitalizes the string value. For example for a publication, you could use the
template tag <$title.capitalizedString/>, which is replaced by the title of the publication written
in capital letters.
A more advanced template tag is used to enumerate collection properties. For example, in an export template, you might want to write out some properties for the collection of all publications. Collection tags consist of two tags, a start tag and an end tag.
<$collectionKey> item template </$collectionKey> |
The item template that is written between the start and end tag is used as a template that is passed
to the items of the collection. Keys in template tags appearing in the item template will be interpreted
as names of properties of those items.
You can also include a template that is used as a separator between items, which will be ignored after the last item of the collection. For this you need to insert a third template tag between the start and end template tags as follows.
<$collectionKey> item template <?$collectionKey> separator template </$collectionKey> |
If a collection template tag appears by itself on a further empty line, this whole line will be ignored (but of course not the tag itself), including the newline at the end of the line.
As we noted earlier, key paths for collection properties modify the items of the collection. As they return a collection, we can use them again for a collection tag, as in the following example.
<$collectionKey.valueKey> item template </$collectionKey.valueKey> |
This gives an enumeration over the values given by valueKey of the items in the collection.
You can also use collection modifier keys to modify the collection. As these still give a collection, they should be used in collection tags, as in the example below.
<$collectionKey.@modifierKey> item template </$collectionKey.@modifierKey> |
Or you can use collection value keys. As these returns a single value, it should be used in a value template tag, something like the following.
<$collectionKey.@collectionValueKey/> |
Another template tag is used to include part of a template depending on whether a value is empty or not. For example, you might want to write out some property, and perhaps some more text around it, only when it is set. Condition tags consist of two tags, just as collection tags, but the key should be a value key.
<$conditionKey?> template for non empty condition </$conditionKey?> |
You can also supply a template when the value for the conditionKey is empty. For this you need to insert a third template tag between the start and end template tags as follows.
<$conditionKey?> template for non empty condition <?$conditionKey?> template for empty condition </$conditionKey?> |
Instead of checking for an empty value, you can also check for fixed values.
<$conditionKey=firstValue?> template for match to firstValue <?$conditionKey=secondValue?> template for match to secondValue ... <?$conditionKey?> template for no match </$conditionKey?> |
Or you can match on substrings.
<$conditionKey~matchValue?> template for substring match </$conditionKey?> |
In these conditions the alternate template tags (starting with <?$) are optional.
There can be an arbitrary number of alternate matches. Matches are case insensitive.
Apart from = and ~, also < and <= are available as comparison operators.
All alternate tags must have the same comparison operator as the initial tag.
As for collection template tags, if a condition template tag appears by itself on a further empty line, this whole line will be ignored, including the newline at the end of the line. Moreover you can use key paths as well, as long as the combined key path returns a value key.
We talked all the time about properties of objects. You can ask the question: of which object are we taking a property?
This depends on the context for our template. BibDesk can have two types of templates:
the Main Page template file, and an Item template file. In the Main Page template file, the keys should describe
properties of the document. For example the fileName of the document. In an Item template file,
the keys describe properties of publication objects. For example the title of the publications.
However in between collection tags, the keys describe properties of the items in the collection.
For example, the following could appear in the Main Page template, as publications is the key for a collection
property of a document.
<$publications>
<$title/>
</$publications>
|
This simple template will write out all the titles of the publications in the document.
However, when the key path starts with a dot ".", the property is a global object rather than a property of the context object. There are a few global objects defined, such as the current date.
<$.date.standardDescription/> |
For BibDesk there are essentially five types of objects. The top level document, a publication item, a field of a publication, an author of a publication, and a macro.
In the item template inside a collection tag you can use the special key "#" to get a counter for the items.
<$#/> |
You can modify the counter with value modifier keys for a number.
| Template Keys |