Link Content to Pages and Databases

roseList documents mentioning Link Content to Pages and Databases

Introduction

This manual provides instructions for encoders, editors, and contributors working on MoEML’s XML documents. Please do not hesitate to contact the MoEML team for additional assistance.
Because MoEML’s practices are always being updated, please refer back to this manual frequently.
MoEML uses links to connect strings of text to different parts of the website. Links can also connect strings of text to external web pages. Depending on what type of content the string of text contains, different encoding practices are used.

Link to MoEML Webpages

The following section outlines how to encode internal links to (1) other documents (2) different sections within the same document.

Link to Another Document

Link to another MoEML webpage using a mol:uri pointer and the page’s @xml:id as follows:
Consult <ref target="mol:editorial_style">Editorial Style</ref> for more information.
A complete list of MoEML’s @xml:ids can be found on the XML Identification List.
The above example links to the top of the referenced web page. To link to a specific section of a MoEML webpage, enter a @target value that contains a mol:uri pointer and the page’s @xml:id followed by a number sign (#) and the @xml:id attached to the <div> in the document you want to link to. Generally speaking, the @xml:id for a <div> in a document will always consist of the document’s @xml:id followed by an underscore character (_) and a word or phrase that describes the <div>. For example, there is a <div> in the Whitefriars Theatre encyclopedia article with the @xml:id "WHIT17_managers". Link to this <div> as follows:
As discussed in the <ref target="mol:WHIT17#WHIT17_managers">earlier section</ref>...
Some pages on the MoEML site are not derived from TEI documents which have @xml:id attributes; they are generated by queries running on the xml source which collect information from across the collection. Some examples of such pages are the azindex.htm page and the many table-of-content pages generated from the MoEML document type taxonomy, such as mdtlist:EncyclopediaTopic. It is incorrect to link to these pages using the mol: protocol; instead, for the A-Z Index page, create a link like this:
<ref target="azindex.htm">A-Z Index</ref>
For the document type taxonomy pages, use the mdtlist: protocol:
<ref target="mdtlist:mdtEncyclopediaTopic">Encyclopedia Topics</ref>
There is one additional way to link to taxonomy pages: by default, they show all the documents in a category, but another variant shows instead all the subcategories. For example,
<ref target="mdtlist:mdtEncyclopediaLocation_subcategories">Placeography</ref>

Link within the Same Document

As per usual, use a <ref> tag with a @target element to link to different section within the document. The @target value should consist of a number sign (#) followed by the <div>’s @xml:id ("#xml:id"). For example, if I wanted to encode a link to the Introduction of this page (@xml:id="linking_intro"), I would use the following code:
Here is a link to the <ref target="#linking_intro">introduction</ref>.

Link to External Web Pages

Link to an external web page thus:
Consult the <ref target="http://www.tei-c.org/release/doc/tei-p5-doc/en/html/">TEI
                        Guidelines</ref> for more information.

Link to YouTube Videos

External YouTube videos render in a CSS lightbox within the MoEML website. We link to YouTube videos using the <media> element. Consider, for instance, the following example from index.xml in which the encoder provides a link to Janelle Jenstad’s UVic Faces of Research interview on YouTube:
<p>
        <media rend="youtubeEmbed" n="klkLh76fOc8" url="https://www.youtube.com/watch?v=klkLh76fOc8" mimeType="video/x-flv" width="560px" height="315px">
            <desc><title level="m">MoEML</title> Director Janelle Jenstad introduces the project.</desc>
        </media>
    </p>
Note that the <media> element uses six attributes to define the video settings:
  • The @rend attribute will always have a value of "youtubeEmbed", which tells the XSLT that it needs to create a lightbox.
  • The @n value contains the id of the video on YouTube.
  • The @url value contains the url address of the video on YouTube.
  • The @mimeType attribute will normally have a value of "video/x-flv", which specifies the proper multimedia internet mail extension (MIME) media type. As YouTube transitions from Flash to HTML5 video, this may change.
  • The @width and @height values for a YouTube video will normally be "560px" and "315px" respectively; these values come from YouTube’s instructions for embedding the video.
There is a <desc> element nested inside the <media> element. Whatever text string is inside the <desc> element renders as a link to the video. Because the text renders as a link, the text string cannot contain any other links. Note, for instance, that, in the previous example, Janelle Jenstad’s name is not linked to her entry in PERS1.xml.

Link to Audio Files

In order to link to an audio file in a born-digital or primary source document, the file must first be uploaded to the binary docs folder in eXist. Write a description of the audio and tag it using a <ref> element with a @target attribute pointing to the audio file’s URL. For example, see how we link to the Smiths’ Song in Scott Trudell’s Sounds of Pageantry article:
<p><ref target="docs/plumly_smiths_song.mp3">Listen to the Smiths’ Song</ref>, read by <ref target="http://www.poets.org/poetsorg/poet/stanley-plumly">Stanley Plumly, poet laureate of the state of Maryland</ref>.</p>
Note that the binary docs folder is represented as simply docs/ in the URL path.

Encode Graphics

To include a graphic on a page on the site, first create the graphic and save it in the graphics folder within the MoEML subversion repository. Make sure that the file has a sensible filename (no spaces, no capitals, no punctuation, etc.), then add and commit the file to SVN. Screenshots go in a subfolder in SVN called graphics/screenshots. We use screenshots in our documentation to demonstrate encoding practices. Digital facsimiles of early books (of our copy of the 1633 Stow, for example) go in the facsimiles folder in SVN.
Next, upload the graphic to eXist, saving it in /db/data/graphics.
Once it is uploaded, you can refer to it in an XML file as follows:
<graphic url="graphics/InsertFileName" width="100%" height="100%"></graphic>
The @width and @height attributes determine how large the graphic will be relative to the containing space. Unless the image is small, you will most likely want to insert a @width and @height value of "100%"; that said, it is possible to scale the graphic in any way using other values. If you desire to use the same values for both @width and @height, you need only proclaim one of the two attributes. Consider the following example:
<graphic url="graphics/InsertFileName" width="80%"></graphic>
In this example, the @height attribute will automatically be determined by the browser as proportionate to the @width attribute.
In most cases, when you are inserting a graphic into a born-digital document, you will want to supply a caption for it. This is done by putting the <graphic> element into a <figure> element, and adding a <figDesc> element containing the caption:
<figure style="float: left; width: 12em; margin-right: 1em;">
    <graphic url="graphics/web_team_photos_2013_new/kim_mclean-fiander.jpg" width="100%"></graphic>
    <figDesc><name ref="mol:MCFI1">Kim McLean Fiander</name> (Asst. Project Director &
      Research Fellow)</figDesc>
  </figure>
The <graphic> element always comes first, followed by the <figDesc>. In the output, the caption will automatically be set to the same width as the graphic, so it wraps appropriately. Note that you can use CSS in the @style attribute to control the position and size of the image and its caption on the page; here, the containing <figure> element is set to a width of 200 pixels, with a right margin of 1 em, while the graphic is set to be 100% of that width, so it will also be 200 pixels wide, and the caption will have the same width. The figure block will have a margin of 1em, and it is floated to the left, so the text will flow around it to the right with a space of 1 em between the right edge of the image and the left edge of the text. You can spend a lot of time experimenting with the various CSS options and the resulting layout on the page; this is useful if you’re interested in learning CSS, but less so if you’re just trying to get some work done, so if you’re having trouble getting your images to display the way you want them, talk to one of the programmers.
The <figure> element is also used in primary source document transcriptions, where it typically does not contain a <graphic> element; instead, the <figDesc> alone is used to provide a brief description of an ornamental feature on a page.

Markup (Tag) and Pull Data from Databases

MoEML marks up all early modern London locations, people, events, and livery companies, in addition to bibliographical references. Each entry in these databases is assigned a unique @xml:id, which is used as the target in XML tags. For a complete list of all @xml:ids in use by MoEML, refer to MoEML’s list of @xml:ids.

Link to Location Files

To mark up a string of text containing a location, simply create a <ref> link (as above) to that location’s encyclopedia page. Remember to use the "mol:uri" pointer to specify that the item is part of the MoEML project. For example,
The <ref target="mol:COCK5">Cockpit</ref>, also known as the <ref target="mol:COCK5">Phoenix</ref>, was an indoor commercial playhouse planned and built by the theatre entrepreneur and actor Christopher Beeston.
Note that the definite article (i.e., the) is not included in the <ref> tag.

Link to People in PERS1.xml

To tag people, use the <name> element with a @ref value of "mol:" followed by the person’s @xml:id, which links to that person’s entry in the personography database. For example,
<name ref="mol:HENS1">Philip Henslowe</name>
It is not uncommon to come across literary persons who have similar roles, but are distinct characters. For example, in Greek mythology, Chthoon is the personification of earth; in Roman mythology, Terra is the personification of earth. After properly tagging these characters following the distinctions outlined in the Encode Persons page in Praxis, it may be necessary to add an editorial note in the literary text that explains the use of different names for the same essential character.

Link to Reference Material in BIBL1.xml

To tag reference material in parentheses, use a <ref> element with a @type value of "bibl" and a @target value containing a "mol:uri" pointer followed by the source’s @xml:id, which links the string of text to the source’s entry in the bibliography database. Note that the rendering system does not automatically supply parentheses for in-text references, so you will need to supply them yourself. For example,
Over time, however, what had once been a thriving community had dwindled to no more than sixteen or seventeen monks who relied on renting out empty rooms for income (<ref type="bibl" target="mol:CHAM1">Chambers 476</ref>).

Link to Two or More Works by the Same Author in BIBL1.xml

When citing two or more works by the same author in a document, include both the author’s name and a short title for the cited monograph/article in the parenthetical citation. Tag the citation as per usual, using the <ref> element with a @target value containing a "mol:uri" pointer followed by the source’s @xml:id. Within the <ref> tag, make sure to use the <title> tag with a @level value of either "m" (for monograph) or "a" (for article) to tag the monograph or article title . For example,
The Honest Whore plays, the first written by Middleton and Dekker, and the second by Dekker alone, were initially played at the Fortune in the early Jacobean period, but later revived at the Cockpit around 1635 (<ref type="bibl" target="mol:GURR8">Gurr, <title level="m">Shakespearean Stage</title> 292</ref>).
For more information about the <title> element, see documentation on using TEI to tag text styles.

Link to Webpages in BIBL1.xml

In most cases, cited websites will have only one entry in the BIBL1.xml database (i.e., individual parts/articles within websites are not given individual entries in BIBL1.xml). When referring to different parts or articles within a single website, parenthesize the website title (or, in some instances, the surname of the website’s author) and the title of the part/article. Link the website title (or author’s surname) to the BIBL1.xml entry for the website and link the title of the part/article to the http:// address for the part/article. For example,
Archaeological excavations have found evidence of rubbish pits likely associated with the processing of animal carcasses for furs and hides (<ref type="bibl" target="mol:LAAR1"><title level="m">LAARC</title></ref> <ref target="http://archive.museumoflondon.org.uk/laarc/catalogue/siteinfo.asp?id=19649&code=FEU08&terms=Fenchurch&search=simple&go=Go"><title level="a">Site Record FEU008</title></ref>).

Link to Cited MoEML Content

Referencing a MoEML page as a bibliographic item within a MoEML page is distinct from simply linking to a MoEML page. To cite a MoEML page as a bibliographic item, use the <ref> element with a @type value of "mol:bibl". Most often, this practice will be used to cite MoEML’s editions of library texts or encyclopedia articles. Cite these pages as if they were a standard part/article from a website. For example,
<ref target="mol:SHOR1">Shoreditch</ref> followed Roman roads near Kingsland Road, a continuation of Ermine Street, and <ref target="mol:OLDS1">Old Street</ref>, a continuation of <ref target="mol:WATL1">Waitling</ref> or <ref target="mol:WATL1">Watling Street</ref> (<ref type="mol:bibl" target="mol:SHOR2">Campbell</ref>).
The citation will appear in a pop-up and in the list of references at the bottom of the page. The citation is generated dynamically through the metadata (particularly the <respStmt>s) in the <teiHeader>. See Create a MoEML <teiHeader> for more information regarding document metadata.

Link to ODNB Articles in BIBL1.xml

The practice of citing websites, not parts/articles, does not apply to Oxford Dictionary of National Bibliography (ODNB) articles. Individual ODNB articles are given individual entries in BIBL1.xml. When citing an ODNB article, parenthesize only the author’s surname. Link the author’s surname to the BIBL1.xml entry for his/her article using the <ref> element with a @type value of "bibl" and a @target value containing a mol:uri pointing to the author’s article in BIBL1. For example,
A memorial near his grave, paid for by his wife, still exists today (<ref type="bibl" target="mol:BEER3">Beer</ref>).

Link to BHO Monographs in BIBL1.xml

The practice of citing websites, not parts/articles, also does not apply to British History Online (BHO) editions of monographs such as Stow (1603) and Harben (1918). Like ODNB articles, BHO editions are given individual entries in BIBL1.xml. When citing a BHO edition in text, parenthesize the author’s surname, a semicolon, and BHO. Link the author’s surname to the BIBL1.xml entry for the BHO edition of his/her monograph and link the BHO acronym to the url for the webpage containing the quote or source. For example,
The Wrestlers was a house in Bishopsgate Ward located on the north side of Camomile Street, near the city wall and Bishopsgate (<ref type="bibl" target="mol:STOW15">Stow</ref>; <ref target="http://www.british-history.ac.uk/report.aspx?compid=60032">BHO</ref>).

Encode Non-parenthetical Links to BIBL1.xml

When citing a source without parentheses, hyperlink either the author’s name or the work’s title (but not both) where it appears in the text. If both the author and title are present, hyperlink the author’s name. For example,
<ref type="bibl" target="mol:STRA2">Marta Straznicky</ref>’s <title level="m">The End(s) of Discord in The Shoemaker’s Holiday</title> describes the role of festivities as a means of public regulation in early modern London.

Encode Block Quotations

Block quotes are encoded differently than in-line quotations. To encode a block quote, nest a <quote> element and a <bibl> element inside a <cit> element. Use the <quote> element to tag the text being quoted by the author; use the <bibl> element to tag the parenthetical citation associated with it. The parenthetical citation should also include a <ref> element that links to an entry in BIBL1.xml or, in the cases listed above, to an outside URL. Note that the parentheses around the citation will render automatically.
The following example from CHAR3.xml shows how to encode a block quotation:
<cit>
<quote>This Song being ended, they went to revelling till ten of the clock the next day, by which time, they having ſatiſfied themselves with chamber exerciſe, they fetcht a walk towards <ref target="mol:SMIT1">Smithfield</ref>, and went into <ref target="mol:CHAR3">Charter-houſe lane</ref>, where they had a leſſon played on the Organs, danced mixed dances [...] After this, ſome of the creatures went into rooms apart to milk and fodder; and others (whose chiefeſt pleasure was in drinking) ſung [a] catch.</quote>
<bibl><ref type="bibl" target="mol:READ3">Reading sig. A3v</ref></bibl></cit>
When rendered, the previous code generates the following block quote:
This Song being ended, they went to revelling till ten of the clock the next day, by which time, they having ſatiſfied themselves with chamber exerciſe, they fetcht a walk towards Smithfield, and went into Charter-houſe lane, where they had a leſſon played on the Organs, danced mixed dances [...] After this, ſome of the creatures went into rooms apart to milk and fodder; and others (whose chiefeſt pleasure was in drinking) ſung [a] catch.
(Reading sig. A3v)

More Information

For more information about MoEML’s in-text citation practices, see documentation on styling parenthetical citations.
For information about how to encode reference material in the project’s bibliography, see documentation on the BIBL1.xml database.

Link to Glossary Terms in GLOSS1.xml

To link a term somewhere on the website to its corresponding entry in the GLOSS1.xml database, tag it with a <term> element and a @corresp attribute containing a value of "molgls:" and then the term’s @xml:id. For example,
<term corresp="molgls:LIVE101">livery company</term>
If the term does not yet have a database entry, create one or contact the MoEML team.

Link to Organizations in ORGS1.xml

To tag a string of text referencing an organization, use the <name> element with a @type value of "org" and a @ref value of "mol:" followed by the organization’s @xml:id. This process links the string of text to the organization’s entry in the orgography database. For example,
the <name type="org" ref="mol:KIME1">King’s Men</name>
Note that the definite article (i.e., the) is not included in the <ref> tag.

Link to Related Documents in LINKS1.xml

Although individual documents contain lists of related documents when rendered on the live site, links between related documents are encoded wholly inside the LINKS1.xml database and require no input in individual documents. For further information, see documentation regarding how to use the LINKS1.xml database.

References