Setting up your ESP portal website

This page describes how to configure the parameters, structure, appearance, and privacy preferences of your ESP website. This page is just for managers of ESP projects. If you are editing ESP pages for someone else to install you don't need to read on.

Site parameters (parameters.xml) | Site structure (structure.xml) | Pages | Links | Site style

Site parameters

The parameters of the site are set in the 00web/00config/paramaters.xml file. Here is an example parameters.xml file:

<?xml version="1.0" encoding="utf-8"?>
<param:parameters 
	xmlns:param="http://oracc.org/ns/esp-param/1.0"
        xmlns:esp="http://oracc.org/ns/esp/1.0"
	xmlns="http://www.w3.org/1999/xhtml"
>
	<param:title>The Geography of Knowledge</param:title>
	<param:banner><esp:image file="FILENAME.png" description=""/></param:banner>
	<param:publisher>The GKAB Project</param:publisher>
	<param:host>http://oracc.museum.upenn.edu</param:host>
	<param:root>/cams/gkab</param:root>
	<param:common-headers>
		<meta name="DC.publisher" content="GKAB Project, Department
		of History and Philosophy of Science, University of Cambridge, 
		Free School Lane, Cambridge CB2 3RH, UK"/>
		<meta name="DC.language" scheme="ISO 639-2/T" content="eng"/>
		<meta name="DC.rights.copyright" content="Released under a CC-BY-SA 3.0 license, 2007-12"/>
		<meta name="DC.type" scheme="DCTERMS.DCMIType" 
		content="Text"/> 	
		<meta name="DC.format" content="text/html"/>
	</param:common-headers>
	<param:dc-id-prefix>gkab-oracc-museum-upenn-edu/page/
	</param:dc-id-prefix>
	<param:main-menu-caption>Main menu</param:main-menu-caption>
	<param:footer>
<p><esp:image file="footer/cc88x31.png" description="Oracc's CC
license" position="inline"><esp:link
url="http://creativecommons.org/licenses/by-sa/3.0/" hide-print="yes"
title="Creative Commons Attribution Share-Alike
license"/></esp:image> Released under a <esp:link
page="licensing">Creative Commons Attribution Share-Alike license
3.0</esp:link>,E Robson 2014. <br/>
<small>Oracc uses cookies only to collect Google Analytics data. Read more <esp:link page="privacy">here</esp:link>; see the stats <esp:link url="http://www.seethestats.com/site/oracc.museum.upenn.edu" rel="external">here</esp:link>; opt out <esp:link url="http://tools.google.com/dlpage/gaoptout" rel="external" hide-print="yes">here</esp:link>.</small></p>
	</param:footer>
</param:parameters>

The available elements are described below.

<param:title>Text</param:title>: Provides the title for the site as a whole. Also used in creating citations.
<param:banner><esp:image file="FILENAME.png" description=""/></param:banner>: Optional. Allows you to place a banner in the form of an image at the top of your home page. Content must be esp:image.
<param:publisher>Text</param:publisher>: Used in creating citations.
<param:host>http://www.servername.ext</param:host> and <param:root>/path/to/site/root</param:root>: Describe where the site home page is located. For example, if the home page is at http://oracc.museum.upenn.edu/cams/gkab/, the host is http://oracc.museum.upenn.edu and the root is /cams/gkab. Note that neither should end with a slash.
<param:common-headers>inline content</param:common-headers>: Any elements within this element are copied directly to the head element of all pages of the site. This can be used, for example, for Dublin Core [http://dublincore.org/] metadata items that are the same on all pages, such as DC.publisher.
<param:dc-id-prefix>Text</param:dc-id-prefix>: The text content of this element is prefixed to each page's id to form a Dublin Core [http://dublincore.org/] identifier for each page. This is to ensure that the identifier is globally unique.
<param:main-menu-caption>Text</param:main-menu-caption>: Optional. If this is present, the main menu is captioned with the supplied text.
<param:footer>Arbitrary block and/or inline content<param:footer>: Any elements within this element are copied directly to the footer area of all pages of the site. By default it should include a link to your licensing page, the project name and date.

Site structure

The structure of the site is defined in the file 00web/00config/structure.xml. Here is an example structure.xml file:

<?xml version="1.0" encoding="utf-8"?>
<struct:page 
	xmlns:struct="http://oracc.org/ns/esp-struct/1.0"
        xmlns:wm="http://oracc.org/ns/esp/1.0"
	xmlns="http://www.w3.org/1999/xhtml"
	file="home.xml" id="home" accesskey="1" type="page">
  <struct:link url="http://oracc.org/dccmt/corpus" id="corpus" title="Corpus"/>
  <struct:page file="bibliography.xml" id="bibliography" accesskey="2" type="page"/>
  <struct:page file="metrology.xml" id="metrology" accesskey="3" type="page"/>
  <struct:page file="updates.xml" id="updates" accesskey="4" type="page"/>
  <struct:page file="about.xml" id="about" accesskey="6" type="page">
    <struct:page file="404.xml" id="404" hide-menu-link="yes" type="page"/>
    <struct:page file="accesskeys.xml" id="accesskeys" accesskey="0" type="page"/>
    <struct:page file="cookies.xml" id="cookies" accesskey="7"  type="page"/>
    <struct:page file="licensing.xml" id="licensing" accesskey="8"  type="page"/>
    <struct:page file="standards.xml" id="standards" type="page"/>
    <struct:page file="sitemap.xml" id="sitemap" accesskey="9"  type="page"/>
   </struct:page>
</struct:page>

As seen above, the file usually contains only <struct:page> and <struct:link>elements. The nesting of these elements defines the structure of the site.

Pages

The <struct:page> element is used as described below:

<struct:page 
id="example"
file="example.xml"
accesskey="0"
hide-menu-link="yes"
>
	Other <struct:page> elements (optional)
</struct:page>

id: Mandatory. The unique identifier for the page. Other pages will link to this page using its id. Give pages ids according to a logical and memorable system: any value can be chosen that you are happy to be open to the public (it may be used in metadata fields).
file: Optional. The location of the XML file containing the information for this page, relative to the pages folder in the site-content folder (if the file attribute is not present, the page's information must be present inside the <struct:page> element itself, but this is not recommended). Name the XML files, and place them inside folders in the site-content/pages folder, according to a logical and memorable system. No trace of the file names or locations will be present anywhere in the public site.
accesskey: Optional. This defines an access key to be used to access this page from other pages on the site. However, note that the access key will only work on pages on which there is a link to the target page.
hide-menu-link="yes": Optional. The presence of this attribute determines whether or not a link to the page is displayed in the navigation menu. Note that the 404.xml page is usually hidden.

The <struct:page> element can contain other <struct:page> elements; these are then 'children' (i.e., sub-pages) of this page in the site structure.

Links

You can reference external links in structure.xml by using the struct:link element. This has the following attributes:

id

Mandatory. The unique identifier for the page. Other pages will link to this page using its id. Give pages ids according to a logical and memorable system: any value can be chosen that you are happy to be open to the public (it may be used in metadata fields).

title

Mandatory. The text that is used in the menu when displaying the link entry.

url

Mandatory. The URL for the resource which is usually external to the ESP site, but may be local. The URL is handled according to the following rules:

If the URL begins with http:// or / it is passed through unmodified
Otherwise, the URL is treated the same way as any other esp:link, i.e., it is taken to be relative to the ESP portal's top level directory.

A common application of this feature is to create a link in the menu to reach a corpus referenced by the portal. To include such a link, you can simply include struct:link in the appropriate place in structure.xml. For example, to link to the SAAo corpus one could write:

  <struct:link id="SAAo" title="Browse SAAo Corpus" url="/SAAo/corpus"/>

Site style

Some aspects of the visual appearance of the site are hard-coded (you cannot change them). Others defined in the file 00lib/p3colours.txt. We give instructions on how to edit this file on the Colours configuration page.

Next steps

You are now ready to create content for your ESP website.

All system elements are described in detail on the pages on Creating web content and Embedding images and other files. They are also listed in alphabetical order on the ESP Elements page.

18 Dec 2019 osc at oracc dot org

Ruth Horry & Eleanor Robson

Ruth Horry & Eleanor Robson, 'Setting up your ESP portal website', Oracc: The Open Richly Annotated Cuneiform Corpus, Oracc, 2019 [http://oracc.museum.upenn.edu/doc/help/portals/espsetup/]