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.