7.10 User tags

User tags are a way of passing additional information from Hollywood scripts to plugins. They can be used to pass an unlimited amount of additional data to plugins directly from the Hollywood script. Most of the Hollywood commands that support plugins also allow you to pass user tags that should be forwarded to plugins. Of course, this makes only sense if the user data is actually recognized by the respective plugin.

For example, let's suppose there's a plugin that can load PDF pages as images. This makes it possible to use Hollywood's LoadBrush() command to create a brush from a PDF page. However, functions like LoadBrush() don't support specifying a page number or a password because they're not designed to load pages from PDF documents. A plugin could deal with this limitation by simply defining two new user tags, e.g. Page and Password, and then scripts could use these two tags to pass the information to the plugin.

From the Hollywood script's point of view, user tags are simply passed in an optional UserTags table accepted by many Hollywood functions, e.g. LoadBrush(). The UserTags table can contain an unlimited amount of key-value pairs that define individual user tags. Note that the key must always be a named table index like Page or Password. It's not possible to use numeric table indices as user tags. The value can be a string or a numeric value. If it is a string, it can also contain binary data.

To come back to our example from above, to pass a page and a password to an image plugin via user tags, a Hollywood script could simply do the following:

; load page 5 of test.pdf as a brush, passing "mypwd" as the password
LoadBrush(1, "test.pdf", {UserTags = {Page = 5, Password = "mypwd"}})

A plugin could then look for the tags Page and Password to find out the page number to load and the password for the PDF (if any). This makes it possible to pass all kinds of additional information to Hollywood plugins.

Furthermore, user tags are also supported by many preprocessor commands so you could also do the following to load page 5 of test.pdf as a brush:

; load page 5 of test.pdf as a brush, passing "mypwd" as the password
@BRUSH 1, "test.pdf", {UserTags = {Page = 5, Password = "mypwd"}}

Note that user tags are supported by all kinds of plugins: They are supported by image loaders, anim loaders, sound loaders, video loaders, icon loaders, font loaders, file adapters, directory adapters, display adapters, network adapters, and serializers. Loaders typically forward the user tags to adapters as well so that file adapters will be able to listen to user tags passed through loaders.

Show TOC