VAVOOM Tags 1.2

	Vavoom Tags display data that is stored in the Vavoom database. To create and edit data, visit Vavoom Admin.

The VAVOOM (Visual Access to Virtually Organized Organizational Metadata) project encompasses a metadata access layer, the management of a representation of the organizational structure of NCAR/UCAR with controlled vocabularies, a metadata administration application, and a web presentation component.  The sub-project documented herein is the development of the web presentation.

Java Server Pages (JSPs) are used in NCAR/UCAR web sites to create dynamic elements within pages.  The JSP standard includes a variety of tags, plus there are many vendors of additional tags.  The tags developed here are custom JSP tags created specifically for NCAR/UCAR web sites, to access the VAVOOM metadata, and are called VAVOOM Tags.

VAVOOM Tags are generally used by configuring tag attributes in order to select specific information available for presentation in the web pages. They do not have tag bodies.  They return results into the JSP page context through variables which are set through the execution of the tag.

The tags access metadata that is created and managed using the VAVOOM administrative application.  One should be familiar with that application, and somewhat familiar with the organization of the metadata administered with it, in order to more completely understand VAVOOM Tags.  For more information about the data, see the Elements document:
http://word.ucar.edu/vavoom/elements.html
This document describes the tags, attributes and page-context variables

General Entries Attributes

The following attributes are used in the tags which access Entries.

type

Selects the entry type.  One of the following:

• news
• site spotlight
• fast fact
• project
• publication
• media

These identifiers must be used precisely as given, including the space between first and second words.

The special value “any” may be used to select any type or when the type need not be specified.

subtype

Further specifies a given type.  Most types have subtype identifiers, such as "press release" for the news type.  See the Elements document for the values.

publisher

The full parentage of the group that is the author or host of the resource described by the metadata entry.  The publisher is a path-like specification of the organizational unit which has published the entry.  For example, the specification for the Web Engineering Group within SCD is NCAR/CISL/SCD/ESS/WEG.

Note that the publisher does not begin with a slash.

The publisher allows one wildcard at the end of the string to select all publishers at the level in the organization and levels that are under that level.  For example, a publisher of “NCAR/CISL*” will select entries related to CISL and to organizational units which are within CISL.

The special value “any” may be used for entries which apply to any or all publishers.

subject

Provides each publisher with their own namespace for tagging and filtering records by subject or destination.  This is not a controlled-vocabulary.  It is dynamically defined by the strings which contributors enter into the web form to create their entries.

Page-Context Variables

The tags return results into the JSP page context through variables which are set through the execution of the tag.

The following page-context variables are set by many of the tags.  Not all variables have values defined for all of the types (see the Elements document).  In some cases, numerous entries, each with this set of variables, are returned to be iterated over in the JSP.

The variables are used through the JSTL syntax.  Variables are referenced as
      ${variableName}
Example: Render a title with a link to the url variable.
<a href="${URL}">${title}</a>

Primary Tags

These tags access individual metadata entries or collections of entries given selection criteria and then set page-context variables in return.

getEntry Tag

Get one metadata entry of a particular type.

id

This is an identifier of a specific entry.  The value is an integer which is defined in the VAVOOM administration application.  You must use the VAVOOM administration application in order to obtain the specific value of id to use.

Example: get one entry of the Type “news” which has the particular id identifier of the given value, and render the data as a table with a URLThumb, title, short description and release date. Note that the vavoom tag is self-terminating and therefore no closing tag is required.

<vavoom:getEntry type="news" id="123"/>
     <table cellpadding=”3”>
       <tr>
     <td><img src="${URLThumb}" width="125"></td>
         <td><strong>
              <a href="${URL}">${title}</a>
            </strong><br>
            ${shortDescription} (${dateReleased})</td>
       </tr>
      </table>

getLatestEntry Tag

Get  the latest (most recent) entry of the given type (and subtype, publisher, if specified).

Example: get the latest (most recently entered) entry of type “news” and render the data as a table.

<vavoom:getLatestEntry type="news"/>
   <table cellpadding=”3”>
      <tr>
        <td valign="top"><img src="${URLThumb}" width="125"></td>
        <td valign="top"><strong><a href="${URL}">${title}</a></strong><br>
                    ${shortDescription} (${dateReleased})</td>
      </tr>
   </table>

getEntries Tag

Get a collection of all the entries of a given type, subtype and publisher.  The collection will be sorted by a particular element in the entries if the “sortby” attribute is specified (text elements will be sorted alphabetically and date elements will be sorted reverse-chronologically, if “sortorder” is not specified).

The results from the tag are stored in a collection (a data structure like an array) of entries with the name of “results”.  This collection can then be accessed using a looping control structure in the command language for JSPs, namely JSTL.  Each data element of each entry can be referenced.

1. sortby

The results can be sorted by a particular element name.  The results could be thought of as rows and columns of information, as in a spreadsheet.  Sorting by an element is similar to sorting a spreadsheet by a column.

1. sortorder

The sorting specified in sortby can be reversed using this attribute by setting the value to “reverse”.

1. block

The results of the tag is normally filtered by approval and expiration.   Entries which have not been approved through the editor workflow and are past the expiration date are not shown in a web page.  This can be overridden by setting “filter” to “false”.

Example: get all the entries of type “project”, sort by “title”,, and then render the page-context variables of the first 10 results.

<vavoom:getEntries type="project" sortby=”title”/>
<table cellpadding=”3”>
      <tr>
           <th>Project</th>
       <c:forEach items="${results}" var="entry" begin=”0” end=”9”>
                      <td><a href=”${entry.URL}”>${entry.title}</a></td>
       </c:forEach>
       </tr>
</table>

Note 1: The begin and end parameters in the foreach JSTL tag are optional. If they are not specified, the entire result set will be printed. If begin is specified and end is not, then all will be printed starting with begin.  The foreach tag has other functionality not shown here. See JSTL documentation for more details.

Note 2: To reverse the order of the sorting, set the sortorder attribute to “reverse”.

1.  topic

The results can be further filtered by topics.  Topics are subject areas that are arranged in a hierarchy of topic and subtopic for each publisher.  They are optional, and if available, are presented to the editor when the entry is created or edited.

getRandomEntry Tag

Get an entry randomly.  If the “latest” attribute is specified, the selection will be from a subset of the entries.

1. latest

This attribute allows for selecting a subset of the latest entries from which to select the random entry to display.  Older entries can be ignored without needing to be expired or removed from the holdings.

Example: get a randomly-selected entry from the 20 latest “news” entries that are of the subtype “press releases” and are published by UCAR.

<vavoom:getRandomEntry type="news" subtype="press release"
      publisher=”UCAR” latest=”20"/>
<table cellpadding=”3”>
       <tr>
     <td><img src="${URLThumb}" width="125"></td>
         <td><strong><a href="${ URL }">${title}</a></strong><br>
                    ${shortDescription} (${dateReleased})</td>
       </tr>
      </table>

Topic Tag

This tag retrieves top-level topics for a publisher, and the subtopics which are children of a given topic.  These tags are usually used together to display a hierarchical list of entries, organized by topics and subtopics, to be navigated by the browser.

getTopics Tag

Get the collection of topics owned by a publisher.

1. var

This attribute gives the name of a data variable to hold the results.  Unlike the primary entry tags described above, the results cannot be stored in a pre-determined named variable such as “results” because Topic and Subtopic tags are nested, hence separate variables need to be used to store each.

The results of the tag are stored in a collection (a data structure like an array) of entries with the name of var.  This collection can then be accessed using a looping control structure in the command language for JSPs, namely JSTL.  Each data element of each entry can be referenced.

1.  topic

The results can be further filtered by topics.  Topics are subject areas that are arranged in a hierarchy of topic and subtopic for each publisher.  They are optional, and if available, are presented to the editor when the entry is created or edited.

1.  id

A particular topic can be selected by ID number.

1.  title

A particular topic can be selected by Title.

Example: loop over all the topics and subtopics for a given publisher and render the Projects.

<table>
<tr>
<c:forEach var="topic" items="${topicset}">
                <td>
                <strong>${topic.title}</strong>
                <br/>
                <vavoom:getSubtopics topic="${topic}" var="subtopics"/>               
            <c:forEach var="subtopic" items="${subtopics}">
                ${subtopic.title}
                <br></br>
                <vavoom:getSubtopicEntries subtopic="${subtopic}" type="Project" subtype="field" var="entries"/>               
                <c:forEach var="entry" items="${entries}">
                    ${entry.title}
                    <br></br>
                </c:forEach>
            </c:forEach>
                </td>
</c:forEach>
</tr>
</table>

Search Tag

General-purpose search of any attributes of entries.

The results from the tag are stored in a collection (a data structure like an array) of entries with the name of “results”.  This collection can then be accessed using a looping control structure in the command language for JSPs, namely JSTL.  Each data element of each entry can be referenced.

1. search

This attribute specifies the string to search for.  The string includes modifiers such as wildcards.  The search string uses Lucene search syntax, which is documented here: http://lucene.apache.org/java/docs/queryparsersyntax.html

Note that you cannot begin a search string with a wildcard (“*” or “?”) because the search would take too long.

Example: get the Fast Facts submitted by “Sitongia”.

<vavoom:search type="fast fact" search=”submitter:’sitongia’”/>
<c:forEach items="${results} var="entry"">
        <b>${entry.title}</b>
</c:forEach>

Accessory Tags

These are third-party tags which are used by page designers in this context.

cache Tag

The cache tag simply identifies a region of the JSP page that will be cached to speed up rendering to the browser.  The tag invokes OpenSymphony cache, an open source web app. When the region is cached, the dynamic part of the region will not be executed every time a user looks at it with their browser.  The first time someone looks at the region, it is executed and the output is stored in the cache.  The next time, the stored cache results will be shown to the user, rather than executing the dynamic elements again.  This greatly speeds up page rendering.
Caching should be used when you know that the content that that region of JSP will show will not change more often than the time period for which you want it cached.
The cache tag allows the lifetime of the cached data to easily be specified.  Everything between the open and close cache tags is cached, including the HTML and the result of the returned variables. Here's an example:

<cache:cache key="NewsPressReleases" cron="0 * * * *">
<table>
    <tr>
      <vavoom:getEntry Type="News" subtype="press release" publisher=”/UCAR” id="1st"/>
        <td valign="top"><img src="${URLThumb}" width="125"></td>
        <td valign="middle">&nbsp;</td>
        <td valign="top"><b>
           <a href="${ URL }">${title}</a></b><br>
                    ${shortDescription} (${dateReleased})</td>
    </tr>
</table>
</cache:cache>

You can specify a "key" that uniquely identifies the cached region.  The key must be unique for the entire site.  A good convention is to incorporate the page name or subsite name into the key so that you are guaranteed to have a unique name.  If not specified, the tag will generate a unique key for the cached region of the page.

The cron attribute specifies when the cached data should be refreshed using the same cron parameters used in UNIX.  In this case, the cache data is refreshed at the top of every hour. Alternatively, you can use the “time” parameter to specify a time duration.

Definitions

Assumptions

• The data model is defined separately.
• The Administration application already exists, and enforces business rules regarding authorization and access control.
• Metadata elements are selected through the use of tag attributes.
• VAVOOM tags do not have bodies.
• VAVOOM tag names start with lower case.
• All VAVOOM tags attributes are given in lower case.
• JSTL tags are used in addition to VAVOOM tags.

WEG Home | Documentation | Support | webmaster@ucar.edu | Top

UCAR | NCAR | CISL | © 2007, UCAR | Privacy Policy | Terms of Use | Sponsored by