Resource Registry entry

Specify a resource (a string) that points to a document (local or web) or search engine from a module.

The Resources utility can be used from within a record to:

  • Open / display a document (usually though not necessarily an HTML document).
  • Search the Internet using details in the record (dynamically generating a search URL).

A Resource is a string, generally a URL, generated from a Registry entry and pointing to a document, such as an HTML document or search engine. The document could also be a local document (an MS Word file for example) or a document available on a network drive.

The most common use of Resources is to extract data from the current record, insert it into a URL and send the URL to a search engine. For example, a Natural History institution wants to extract the genus and species from a record and search GBIF (Global Biodiversity Information Facility) using that information. The Resource Registry entry allows URLs to be generated dynamically based on data found within the current record.

The Resources utility is found on the Tools tab of the Ribbon:

Resources

The sub menu entries (e.g. Search Google) are defined with a Resources Registry entry.

To add an entry to the Resources sub menu, it is necessary to create a Registry entry that defines the:

  1. Label for the sub menu (title).
  2. Resource to display when the sub menu entry is selected.

Usage

This Registry entry can be assigned to users and groups:

Key User User Group Group Group Group
Key 1 User User Group Group Group Group
Key 2 user user group group Default Default
Key 3 Table Table Table Table Table Table
Key 4 table Default table Default table Default
Key 5 Resource
Key 6 title
Value resource
User user Table table Resource title resource
User user Table Default Resource title resource
Group group Table table Resource title resource
Group group Table Default Resource title resource
Group Default Table table Resource title resource
Group Default Table Default Resource title resource

where:

title

is the name of a resource displaying under the Resources option on the Tools tab of the Ribbon.

When the same title is defined for a Resource, an entry higher in this list takes precedence over one that is lower. Thus in this example:

User fred Table eparties Resource Search Google resource1
Group Default Table Default Resource Search Google resource2
Group Default Table Default Resource Search GBIF resource3

when all users, including fred, select Resources, the Resources sub menu will display two entries: Search Google and Search GBIF. However, when fred selects Resources>Search Google, the resource shown will be resource1, whereas all other users will see resource2.

Resources shown on the sub menu are sorted alphabetically by title.

resource

defines the path to the resource to be displayed or fetched. In general this path takes the form of a URL, however any other document locator (e.g. file path) may be used. In order to allow data from the current record to be incorporated in a resource path, an XML based parser is used. In other words, you define in XML how the document path is to be constructed. The XML used consists of only six tags, but provides a flexible mechanism for building a document path.

Here we provide a solid overview of how to use the six tags to define resource. A detailed look at the six tags and their attributes can be found in XML reference.

Consider this simple example. The following resource entry will display the GBIF home page if selected:

<resource>
   <location>
      <text>http://www.gbif.org/</text>
   </location>
</resource>

When the ampersand (&) character is used in a Resource definition, it must be specified as:

&amp;

For example:

hl=en&amp;q=%22

The first thing to notice is that the whole entry is enclosed within the <resource></resource> tags. The <location> tags enclose the <text> tags which generate a single document path. A number of <location> tags may appear within the one set of <resource></resource> tags.

Each <location> tag generates one document path. When processing occurs, each <location> section is evaluated, one after another, until a non-empty document path is returned. If processing finishes and no non-empty document path has been returned, the Resource title entry is removed from the Resources sub menu.

The <text> tag defines text used to build a document path. In the example above, output from executing the XML would be http://www.gbif.org/. If a user selected this resource from the Resources sub menu, their browser would start up and display the GBIF home page.

The example above, while useful, is a bit limiting. Ideally we want to include data from the current record. The <value> tag allows data to be extracted and added to a document path. The example below adds the value in the IdeGenus column as a search term for Google:

<resource>
   <location>
      <text>http://www.google.com/search?hl=en&amp;q=</text>
      <value column="IdeGenus" format="url"/>
   </location>
</resource>

The <value> tag gets the data from the specified column attribute (in this case IdeGenus) and outputs it as part of the document path. The format attribute indicates that the data should be encoded using the URL encoding rules (see http://www.rfc-editor.org/rfc/rfc1738.txt for details about URL encoding). In effect, encoding ensures that data can be sent via a URL.

So, if the column IdeGenus contains Panthera, the output from the above Resource would be http://www.google.com/search?hl=en&amp;q=Panthera, which would initiate a Google search for the term Panthera, displaying the results:

Resources: Search results

We can combine <value> and <text> tags to build up quite complex document paths. For example, let's say we wanted to include the genus (IdeGenus) and species (IdeSpecies) in our Google search. Since we want the terms to appear next to each other we need to enclose the search term in double quotes (URL encoded as %22) with a space between each term (URL encoded as +). The following resource could be used:

<resource>
   <location>
      <text>http://www.google.com/search?hl=en&amp;q=%22</text>
      <value column="IdeGenus" format="url" />
      <text>+</text>
      <value column="IdeSpecies" format="url" />
      <text>%22</text>
   </location>
</resource>

If we have a genus of Panthera and a species of leo, the document path generated would be:

http://www.google.com/search?hl=en&amp;q=%22Panthera+leo%22

which would initiate a Google search displaying the results:

Resources: Search results

We can build quite complex document paths using the four tags discussed so far.

The fifth tag, <if>, is a conditional tag that provides control over whether a document path should be calculated. In the example above we may only want to perform the Google search if both the genus and species fields contain values. The <if> tag allows a field to be tested for either filled / empty or for a given value. If the tag evaluates to true, then the inner tags are evaluated, otherwise they are ignored.

In this example we only output the document path if both the Genus and Species fields contain values:

<resource>
   <location>
      <if column="IdeGenus" filled="yes">
         <if column="IdeSpecies" filled="yes">
            <text>http://www.google.com/search?hl=en&amp;q=%22</text>
            <value column="IdeGenus" format="url"/>
            <text>+</text>
            <value column="IdeSpecies" format="url"/>
            <text>%22</text>
         </if>
      </if>
   </location>
</resource>

The <if> tag takes a column name to identify which field is to be tested. The filled attribute can be set to yes or no to indicate whether the field should be filled or empty respectively. Thus the tag <if column="IdeGenus" filled="yes"> is true if IdeGenus has a value. If it is filled, processing continues with the inner tags (in this case another <if> tag), otherwise everything down to the closing </if> is ignored.

In the example above, the <text> and <value> tags are only processed if the Genus and Species fields contain a value, otherwise an empty document path is generated. If the document path is empty, the resource is removed from the Resources sub menu (you can permanently display the resource by setting the visible attribute on the <resource> tag to "yes", that is <resource visible="yes">).

The last tag, <title>, allows the menu caption to be altered. In particular you may want to include data in the caption. The <title> tag can include <text>, <if> and <value> tags. Any output generated by the <text> and <value> tags, when enclosed in a <title> tag, will replace the title text defined in the Registry.

The following example extends the previous example by adding the genus and species values to the menu caption displayed:

<resource>
   <location>
      <if column="IdeGenus" filled="yes">
         <if column="IdeSpecies" filled="yes">
            <text>http://www.google.com/search?hl=en&amp;q=%22</text>
            <value column="IdeGenus" format="url"/>
            <text>+</text>
            <value column="IdeSpecies" format="url"/>
            <text>%22</text>
	    <title>
		<text>Lookup Google for "</text>
		<value column="IdeGenus"/>
		<text> </text>
		<value column="IdeSpecies"/>
		<text>"</text>
	    </title>
         </if>
      </if>
   </location>
</resource>

It is possible to build quite sophisticated document paths with a combination of the six tags. Multiple <location> tags can be included, with processing continuing until a non-empty document path is generated.

The example below takes advantage of this to generate one of three Google URLs depending on whether the Genus and / or Species fields are filled:

<resource>
   <location>
      <if column="IdeGenus" filled="yes">
         <if column="IdeSpecies" filled="yes">
            <text>http://www.google.com/search?hl=en&amp;q=%22</text>
            <value column="IdeGenus" format="url" />
            <text>+</text>
            <value column="IdeSpecies" format="url" />
            <text>%22</text>
         </if>
      </if>
   </location>
   <location>
      <if column="IdeGenus" filled="yes">
         <text>http://www.google.com/search?hl=en&amp;q=</text>
         <value column="IdeGenus" format="url" />
      </if>
   </location>
   <location>
      <if column="IdeSpecies" filled="yes">
         <text>http://www.google.com/search?hl=en&amp;q=</text>
         <value column="IdeSpecies" format="url" />
      </if>
   </location>
</resource>

The first <location> section is used if both a Genus and Species are supplied, the second <location> section if only a Genus is supplied and the last section if only a Species is given. If there is no Genus and species, an empty document path results and the Resource is disabled.

Examples

In this example we use the Getty Art and Architecture Thesaurus to look up terms while we are inserting or editing a record. In order to use the resource the user must enter a value into the first field of the SubSubject_tab column. The URL format used by the Getty is:

http://www.getty.edu/vow/AATServlet?find=term&page=1&note=

In order to use the URL we need to add in the term from the data. The following resource XML could be used:

<resource visible="yes">
	<location>
		<if column="SubSubject_tab" filled="yes">
			<text>http://www.getty.edu/vow/AATServlet?find=</text>
			<value column="SubSubject_tab" format="url" />
			<text>&amp;page=1&amp;note=</text>
		</if>
	</location>
</resource>

The complete Registry entry would be:

Key Setting
Key 1 Group
Key 2 Default
Key 3 Table
Key 4 ecatalogue
Key 5 Resource
Key 6 Lookup AAT (Getty)
Value <resource><location><if column="SubSubject_tab" filled="yes"> <text>http://www.getty.edu/vow/AATServlet?find=</text> <value column="SubSubject_tab" format="url" /> <text>&amp;page=1&amp;note=</text></if></location></resource>

This time we perform a Google search for works of art. We use the Title (TitMainTitle) and Creator (CreCreatorName) fields when searching.

The format of a URL for Google is:

http://www.google.com/search?hl=en&q=terms

where terms is a series of individual values separated by a "+" character. If a term has multiple words, it must be enclosed in double quotes. In this example we assume that the Title must have a value, but the Artists are optional. The following resource XML could be used:

<resource>         
	<location>               
		<if column="TitMainTitle" filled="yes">                
			<text>http://www.google.com/search?hl=en&amp;q=%22</text>                
			<value column="TitMainTitle" format="url" />                
			<text>%22</text>                
			<if column="CreCreatorName" filled="yes">                
				<text>&amp;q=%22</text>                
				<value column="CreCreatorName" rows="all" separator=" " format="url"/>                
				<text>%22</text>                
			</if>                
		</if>
	</location>
</resource>

Notice how %22 must be used to encode a double quote in a URL. The complete Registry entry would look like:

Key Setting
Key 1 Group
Key 2 Default
Key 3 Table
Key 4 ecatalogue
Key 5 Resource
Key 6 Search Google for work
Value <resource><location><if column="TitMainTitle" filled="yes"> <text>http://www.google.com/search?hl=en&amp;q=%22</text> <value column="TitMainTitle" format="url" /> <text>%22</text> <if column="CreCreatorName" filled="yes"><text>&amp;q=%22</text><value column="CreCreatorName" rows="all" separator=" " format="url"/><text>%22</text></if></if></location></resource>

GBIF (Global Biodiversity Information Facility) provides a portal to taxonomic information (amongst other things). In this example we use the Genus (IdeGenus), Species (IdeSpecies) and Subspecies (IdeSubspecies) to access the portal. If any of these ranks is available, the search is possible.

The format of a URL for GBIF is:

http://www.gbif.net/portal/ecat_search.jsp?countryKey=0&nextTask=ecat_search.jsp?countryKey=0&nextTask=ecat_search.jsp&search=terms

where terms is a taxonomic name (genus species subspecies). The following resource XML could be used:

<resource>                           
	<location>                            
		<if column="IdeGenus" filled="yes">                            
			<text>http://www.gbif.net/portal/ecat_search.jsp?countryKey=0&amp;nextTask=ecat_search.jsp&amp;search=</text>                            
			<value column="IdeGenus" format="url" />                            
			<if column="IdeSpecies" filled="yes">
				<text>+</text>                            
				<value column="IdeSpecies" format="url"/>                            
			</if>                            
			<if column="IdeSubspecies" filled="yes">                            
				<text>+</text>                            
				<value column="IdeSubspecies" format="url"/>                            
			</if>                            
		</if>                            
	</location>                           
	<location>                            
		<if column="IdeSpecies" filled="yes">                            
			<text>http://www.gbif.net/portal/ecat_search.jsp?countryKey=0&amp;nextTask=ecat_search.jsp&amp;search=</text>                            
			<value column="IdeSpecies" format="url" />                            
			<value column="IdeSpecies" format="url" />                            
			<if column="IdeSubspecies" filled="yes">                            
				<text>+</text>                            
				<value column="IdeSubspecies" format="url"/>                            
			</if>                            
		</if>                            
	</location>                            
	<location>                            
		<if column="IdeSubspecies" filled="yes">                            
			<text>http://www.gbif.net/portal/ecat_search.jsp?countryKey=0&amp;nextTask=ecat_search.jsp&amp;search=</text>                            
			<value column="IdeSubspecies" format="url" />
		</if>                            
	</location>                            
</resource>

The complete Registry entry would be:

Key Setting
Key 1 Group
Key 2 Default
Key 3 Table
Key 4 ecatalogue
Key 5 Resource
Key 6 Search GBIF
Value <resource><location><if column="IdeGenus" filled="yes"><text>http://www.gbif.net/portal/ecat_search.jsp?countryKey=0&amp;nextTask=ecat_search.jsp&amp;search=</text><value column="IdeGenus" format="url" /><if column="IdeSpecies" filled="yes"><text>+</text><value column="IdeSpecies" format="url"/></if><if column="IdeSubspecies" filled="yes"><text>+</text><value column="IdeSubspecies" format="url"/></if></if></location><location><if column="IdeSpecies" filled="yes"> <text>http://www.gbif.net/portal/ecat_search.jsp?countryKey=0&amp;nextTask=ecat_search.jsp&amp;search=</text><value column="IdeSpecies" format="url" /> <if column="IdeSubspecies" filled="yes"><text>+</text><value column="IdeSubspecies" format="url"/></if> </if></location><location><if column="IdeSubspecies" filled="yes"><text>http://www.gbif.net/portal/ecat_search.jsp?countryKey=0&amp;nextTask=ecat_search.jsp&amp;search=</text><value column="IdeSubspecies" format="url" /> </if></location></resource>