To access data from the CatDV database, you need to include special tags in your JSP pages. Each tag is of the form <catdv:xxx>…</catdv:xxx>. If there is no separate closing tag then XML syntax needs to be used, as in <catdv:xxx/>.
Tags normally take one or more attributes (similar to arguments of a function) that identify the data being queried.
Although some tags directly expand to produce HTML or other text that is inserted into the output, most of the tags in the CatDV tag library define variables which must explicitly be included in the page, as this gives the JSP more control over where and how the data is presented in HTML. Many of the tags therefore define a variable such as ‘catalog’ or ‘clip’ that stores the values being returned. How to access these variables is covered in the next section.
The tags below are currently available. The current list of available tags is also shown in the catdv.tld file.
The serverStats tag
The <catdv:serverStats/> tag takes no parameters and returns a text string listing how many objects of each type are stored in the database.
The browseDatabase tag
The <catdv:browseDatabase> tag accepts a single http request parameter “order” defining the order in which catalogs are returned.
It iterates over all the catalogs in the database and defines the “catalog” variable for each row being returned in turn. It also defines the “rowcount” variable to display how many catalogs are contained in the database.
The catalog tag
The <catdv:catalog> tag returns details about a specific catalog. It accepts a single http request parameter “id”, defining the numeric id of the catalog. It defines “catalog” and “rowcount” variables, and can contain a <catdv:cliplist> tag to iterate over the clips within that catalog.
The cliplist tag
The <catdv:cliplist> tag is an iterator tag that returns details for a variable number of clips. It it called as many times as necessary, setting the “clip” variable for each clip in turn. The <catdv:cliplist> tag only occurs within another tag to define the list of clips, either <catdv:catalog> to return all the clips in a given catalog, or <catdv:doQuery> to return the clips matching a query.
For example, the <catdv:catalog> and <catdv:cliplist> tags might be combined as follows:
<catdv:catalog>
<p>The catalog <b><%= catalog.get(“Name”) %></b> has <%= rowcount %> clips:</p>
<catdv:cliplist>
<%= clip.get(“Name”) %> (<%= clip.get(“In”) %>-<%= clip.get(“Out”) %>)
<br>
</catdv:cliplist>
</catdv:catalog>
The doQuery tag
The <catdv:doQuery> tag accepts the request parameters below to define a clip query.
Up to 20 query terms can be defined by defining attr1/op1..20
For a text-based query you should specify the following parameters:
| attrN | Name of attribute being queried (one of: Name, Notes, AnyField, NameNotes, Tape, Bin, Format, ImportNotes, SourceMedia, User1..UserN) |
| opN | Query operation (0=contains, 1=equals, 2=starts with, 3=ends with, 4=is blank, 5=is one of, 6=contains one of, 7=regular expression, 8=all words, 9=fuzzy match) |
| paramN | Text being compared against. In the case of ‘one of’ comparisions this is a comma-separated list of values |
| ignoreN | Case insensitive comparision |
For a date-based query use the following parameters:
| attrN | Name of date attribute being queried (one of: RecDate, MediaDate, ImportDate, ModifiedDate, CatalogCreated, CatalogExended, CatalogSaved or CatalogPublished) |
| opN | Query operation (16=equals param1, 17=before param1, 18=after param1, 19=between param1 and param2, 21=date is blank) |
| paramNa, paramNb | Date values being compared with, in d/m/y [h:m[:s]] format. |
By default a Boolean AND operation is assumed (ie. all conditions must be true to find a clip) but you can specify more complex queries like in the CatDV client application by setting
| orN | This term OR any other terms with the ‘or’ flag set must match |
| notN | This term must be false for a clip to match |
Additionally, you can specify attributes which aren’t in the list of known attribute names above by giving their attribute IDs preceded by a ‘#’, eg. attr5=#12.
You can limit the number of clips that are returned by setting maxRows.
A <catdv:cliplist> tag within the scope of the doQuery tag will then iterate over the matching clips and display the results, one row at a time.
The queryDatabase tag
The <catdv:queryDatabase> tag accepts the same request parameters as <catdv:doQuery> to define a query. However, rather than returning a list of clips matching the query it returns a list of catalogs. The “catalog” variable is defined, as per <catdv:browseDatabase>
The clipBasket tag
A clip basket can be used to collect together results from different queries like a shopping basket. Baskets are created and managed automatically as part of the user’s session context. They expire automatically after 30 minutes.
The <catdv:clipBasket> tag accepts the following parameters
| basketAction | Either ‘add’ or ‘remove’ to add or remove all the clip with specified clip ids from the basket |
| c_ID | Which clips to add or remove, for example c_1234=on to add or remove the clip whose id is 1234. |
As an alternative to setting basketAction and a c_ you can specify a single clip id to add with the parameter ‘add’, for example add=1234
A <catdv:cliplist> tag within the scope of the clipBasket tag will then iterate over the clips in your current basket and display the results, one row at a time.
The sendEmail tag
You can email the contents of the user’s clip basket using the <catdv:sendEmail> tag. This accepts the following parameters:
| to | Recipient email address |
| name | Sender’s name |
| Sender’s email address | |
| cc | Optional CC email |
| message | Optional message (in addition to the clip basket) |
| subject | Subject header |
You need to configure the sendEmail servlet by specifying various context parameters in the web.xml file:
| mail.host | Which SMTP server to use |
| mail.user | Which user to log on as (for smtp authentication) |
| mail.password | Password for smtp authentication |
| mail.preamble | Text to include at start of email message |
| mail.postamble | Text to include at end of message |
| mail.success | Text that the sendEmail tag displays to user on successful sending (otherwise an error message is displayed) |
| mail.fields | Comma separated list of fields to include when listing clips in the email message |
The getThumbnail servlet
The JPEG data for a thumbnail image is returned using the getThumbnail servlet. This is a separate servlet rather than a tag because the data is returned in a separate http request, not as part of an HTML page. The servlet takes a single parameter “id” which defines the id of the thumbnail object in the database, for example <IMG SRC=”/catdv/getThumbnail?id=12345” WIDTH=64 HEIGHT=48>.
Developers do no normally need to worry about the details of how to use the getThumbnail servlet as the complete <IMG SRC …> expression to use is predefined and returned as part of a “clip” object.
The getMedia servlet
This is a new servlet that will display media and preview files directly from within Tomcat (without having to configure a separate web server such as Apache). If the media files are accessible to the server and you configure media.dir to be the root directory of the media, for example /Volumes/Media, then “/catdv/media/xyz/file.mov” will return the contents of /Volumes/Media/xyz/file.mov. Similarly /catdv/preview/… will append the given path onto the value of the preview.dir variable.