Creating Links in ESP Pages

This page describes how to make links and bookmarks of various sorts in ESP pages.

Internal links

To create a link to another page within the site (i.e., an internal link) use the <esp:link> tag together with the page attribute. To create a link to a bookmarked point in a page (within the site), use the <esp:link> tag together with the bookmark attribute.

<esp:link
	page="example"
	bookmark="example"
	title="Example title"
	accesskey="X"
>
	Inline content (optional)
</esp:link>

page: Optional. The id of another page within the site. Must be present if there is no bookmark attribute.
bookmark: Optional. The id of a bookmark on this page or (if a page attribute is given) another page. Must be present if there is no page attribute.
title: Optional. Title text for the link (read by screen readers, displayed as a yellow 'tool-tip' in standard browsers). Overrides any title text that is automatically generated. If title="", no title text is present on the link on the final page.
accesskey: Optional. Define an access key for this link. Overrides any access key specified in structure.xml. Use not recommended.

NB. If the element has content (i.e., contains text), this content becomes the link. If the element has no content, the name of the destination page (or title of the destination bookmark) is used as the link text. This usage is recommended, because it guarantees that the link text is consistent with any changes made to the destination page name or bookmark title.

External links

The <esp:link> tag is used to create links and is equivalent to the HTML tag <a href="...">. To create a link to an external web page use the <esp:link> tag together with the url attribute.

<esp:link
	url="http://www.example.com/"
	site-name="Example and Sons Ltd."
	title="Example title"
	accesskey="X"
	hide-print="yes"
>
	Inline content (optional)
</esp:link>

url: Mandatory. The URL of the external website. Will usually begin http://....
site-name: Optional. Used as the link text if element is empty. Used in automatically generated title text if the element is not empty and the title attribute is not specified.
title: Optional. Title text for the link. Overrides any title text (after the words "External site") that is automatically generated.
accesskey: Optional. Defines an access key for this link. Use not recommended.
hide-print="yes": If present this prevents the default behaviour, which is to show the URL of an external link in square brackets after the link text when the page is printed.

NB. If the element has content (i.e., contains text), this content becomes the link. If the element has no content, the site-name or (failing that) url attribute is used as the link text.

Some URLs include the & (ampersand) character. For such URLs, you must substitute the entity & in place of the ampersand or else ESP will return an error when you build the site.

You must link to other web pages, whether on Oracc or elsewhere, using full URLs, not the short forms ("tiny URLs") offered by services such as tiny.cc.

Links to downloads

Sometimes you may want to link to a resource within the site which is not a page with an id, for example, a downloadable PDF file or a KMZ file to open in Google Earth.

Files for download should be placed in the 00res/downloads folder or one of its subfolders.

Then use the <esp:link> tag together with the url attribute (as described in the section on External links) and begin the URL with the ~ character: this will be replaced with the root of the site (known as a relative URL). For example,

<esp:link url="/doc/downloads/example.pdf" title="blah">... </esp:link>

<esp:link url="/doc/downloads/adian_eski_kalak.kmz" 
   title="View location of Adian using Google Earth">View location 
   using Google Earth</esp:link>

Links to standalone large images

It is possible to link directly to a standalone larger version of an image, which is not a page with an id.

All large versions images should be placed in the 00res/images folder, or one of its subfolders.

Linking to a large standalone image uses the same method as linking to a downloadable file. Use the <esp:link> tag together with the url attribute (as described in the section on External links) and begin the URL with a / character followed the name of the project. For instance:

<esp:link url="/saao/knpp/images/essentials/kingsadvisors/bm-ane-124537-large.jpg" 
   title="blah">...</esp:link>

Links within captions

The <esp:link> element can be used within the <esp:image> element (described on the Images page) to:

make images into links;
add a text link within an image caption.

Most commonly, both types will be links to larger versions of images. If these larger images are on external web pages, you should use the url attribute to specify the URL of the image (described in the External links section). Otherwise, specify the location of the large image within the site using the ~ character to create a relative URL to the correct folder (described in the section on Links to downloadable content).

The example below shows how to use the <esp:link> element within the <esp:image> element to (a) make an image into a link to an external web page and (b) create a text link within the image caption.

<esp:image file="essentials/assurbanipalslibrary/ps086972_m.jpg" 
description="Cuneiform tablet telling the legend of Ishtar's descent 
to the Underworld" position="float">
   
   <esp:link  url="http://www.thebritishmuseum.ac.uk/blah1/" 
   title="Large image of Cuneiform tablet telling the legend of 
   Ishtar's descent to the Underworld" hide-print="yes"/>

   <esp:caption>This tablet, telling the myth of the goddess 
   Ishtar's visit to her sister, the underworld goddess Ereshkigal, 
   ends with a colophon describing it as the property of Assurbanipal, 
   'king of the world, king of the land of Ashur'; from Assurbanipal's
   Library in Nineveh (BM K 162). Photo © The British Museum. 

       <esp:link url="http://www.thebritishmuseum.ac.uk/blah2/"
       title="Large image of Cuneiform tablet telling the legend of 
       Ishtar's descent to the Underworld" hide-print="yes">View  
       large image on the British Museum's website</esp:link>.

    </esp:caption>

</esp:image>

Links to other Oracc websites

You may wish to link to a resource on Oracc that is not within the generated site structure. In this case, use a standard absolute URL beginning with the / character. For example, <esp:link url="http://oracc.museum.upenn.edu/cams/gkab/P348777.html" title="blah">...</esp:link<.

Oracc URLs are explained on a separate page.

Inserting page titles, etc.

The <esp:page-name> element can be used to conveniently refer to other pages within the site:

<esp:page-name
	page="example"
/>

Inserts the name of the page with the given id. If you want to refer to a page by name, use this element to ensure that the name remains consistent with any future changes. Always empty.

If you want to refer to a page by title, use the <esp:page-title> element to ensure that the title remains consistent with any future changes. Always empty.

<esp:page-title
	page="example"
/>

Inserts the title of the page with the given id.

Bookmarks

Bookmarking functionality allows you to jump directly to any point on a specific page by following a link.

The <esp:bookmark> element defines the point on a page that may be jumped to directly from a link, either on the same page or on another page. The link to the bookmark is a straightforward <esp:link> element that uses the page attribute.

Bookmarking requires two steps:

placing a <esp:bookmark> element around the text to which you would like to jump:
creating a link to the bookmark using <esp:link>.

The specification of the <esp:bookmark> element is as follows:

<esp:bookmark
	id="example"
	title="Example bookmark"
	hide-highlight="yes"
>
	Inline content (optional)
</esp:bookmark>

id: Mandatory. Identifies the bookmark. Must be unique within the page. Becomes part of the URL for that page/bookmarked section, so as well as being unique, each id should be reasonably short, contain no spaces and no accented characters.
title: Mandatory. Used to describe the point that will be jumped to by a link (e.g. "Jump to description of microscope on this page").
hide-highlight="yes": Optional. By default, the content of the <esp:bookmark> element is highlighted when the bookmark is jumped to. This attribute prevents that behaviour.

NB. The <esp:bookmark> can be empty, i.e., it does not have to be placed around text, but should usually contain a term or short phrase.

Creating links to a bibliography

The Knowledge & Power [http://oracc.museum.upenn.edu/saao/knpp] website is an example of a site that uses bookmarks to create links to the bibliography. At the end of each introductory essay is a link to the relevant bookmarked entry in the bibliography.

So, for example, here are four links, used at the end of an essay to jump to bookmarked entries in the bibliography:

<ul>
	<li><esp:link page="biblio-index" bookmark="faleslanfranchi">Fales and 
Lanfranchi</esp:link>, 'The impact of oracular materials', 1997</li>

	<li><esp:link page="biblio-index" 
bookmark="leichty_1997">Leichty</esp:link>, 'Divination, magic, and 
astrology', 1997</li>

	<li><esp:link page="biblio-index" bookmark="mattila">Mattila</esp:link>, 
<i>The king's magnates</i>, 2000</li>

	<li><esp:link page="biblio-index" 
bookmark="pecirkova">Péçirková</esp:link>, 'Divination and politics', 1985</li>

</ul>

and here is the text that appears on the bibliography page, containing the <esp:bookmark> element:

<p>
   <esp:bookmark id="faleslanfranchi" title="entry">Fales, F.M. and 
   G.B. Lanfranchi</esp:bookmark>, 'The impact of oracular materials on 
   the political utterances and political actions of the Sargonid dynasty', 
   in J.-G. Heintz (ed.), <i>Oracles et propheties dans l'antiquité</i>, 
   Paris: de Boccard, 1997, pp. 99-114.
</p>

<p>
   <esp:bookmark id="leichty_1997" title="entry">Leichty, E.>/esp:bookmark>, 
   'Divination, magic, and astrology in the Assyrian royal court', in 
   S. Parpola and R. Whiting (eds.), <i>Assyria 1995</i>, Helsinki
   1997, pp. 161-164.
</p>

<p>
   <esp:bookmark id="mattila" title="entry>Mattila, R.</esp:bookmark>, 
   <i>The king's magnates: a study of the highest officials 
   of the Neo-Assyrian empire>/i> (State Archives of Assyria 
   Studies 11), Helsinki: Helsinki University Press, 2000.
</p>

<p>
   <esp:bookmark id="pecirkova" title="entry">Péçirková, J.</esp:bookmark>, 
   'Divination and politics in the Late Assyrian empire', <i>Archiv 
   Orientální</i> <b>53</b> (1985), 155-168.
</p>

18 Dec 2019 osc at oracc dot org

Ruth Horry & Eleanor Robson

Ruth Horry & Eleanor Robson, 'Creating Links in ESP Pages', Oracc: The Open Richly Annotated Cuneiform Corpus, Oracc, 2019 [http://oracc.museum.upenn.edu/doc/help/portals/links/]