Resource Registry entry

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

The Vitalware Resource utility can be used from within a record to:

  • Open / display a document (typically though not necessarily an HTML document).
  • Search the Internet using details of 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 Resources utility appears under the Tools menu (Tools>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 Tools>Resources menu.

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 Tools>Resources, the Resources sub menu will display two entries: Search Google and Search GBIF. However, when fred selects Tools>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 KE Software home page if selected:

<resource>
   <location>
      <text>http://www.kesoftware.com/</text>
   </location>
</resource>

In versions of Vitalware after 2.0 the XML parser used by Vitalware was replaced with the Microsoft parser. A consequence of this is that when the ampersand (&) character is used in a Resource definition, it needs to be specified as:

&amp;

For instance, up to and including Vitalware 2.0, the following is acceptable:

hl=en&q=%22

In versions of Vitalware after 2.0, the following is required:

hl=en&amp;q=%22

This documentation assumes that you are using a version of Vitalware > 2.0 and ampersands are specified as:

&amp;

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.kesoftware.com/. If a user selected this resource from the Resources sub menu, their browser would start up and display the KE Software 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 NamOrganisation column as a search term for Google:

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

The <value> tag gets the data from the specified column attribute (in this case NamOrganisation) 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 NamOrganisation contains KE Software, the output from the above Resource would be http://www.google.com/search?hl=en&amp;q=KE+Software, which would initiate a Google search for the term KE Software, displaying the 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 Organisation Name (NamOrganisation) and Department (NamDepartment) 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="NamOrganisation" format="url" />
      <text>+</text>
      <value column="NamDepartment" format="url" />
      <text>%22</text>
   </location>
</resource>

If we have an Organisation name of KE Software and a Department of Development, the document path generated would be http://www.google.com/search?hl=en&amp;q=%22KE+Software+Development%22

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 Organisation Name and Department 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 Organisation and Department fields contain values:

<resource>
   <location>
      <if column="NamOrganisation" filled="yes">
         <if column="NamDepartment" filled="yes">
            <text>http://www.google.com/search?hl=en&amp;q=%22</text>
            <value column="NamOrganisation" format="url"/>
            <text>+</text>
            <value column="NamDepartment" 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="NamOrganisation" filled="yes"> is true if NamOrganisation 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 Organisation and Department 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 Organisation and Department values to the menu caption displayed:

<resource>
	<location>
		<if column="NamOrganisation" filled="yes">
			<if column="NamDepartment" filled="yes">
				<text>http://www.google.com/search?hl=en&amp;q=%22</text>
				<value column="NamOrganisation" format="url"/>
				<text>+</text>
				<value column="NamDepartment" format="url"/>
				<text>%22</text>
			<title>
				<text>Lookup Google for "</text>
				<value column="NamOrganisation"/>
				<text> </text>
				<value column="NamDepartment"/>
				<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 Organisation and / or Department fields are filled:

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

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