Images in ESP

This page describes how to mark up images in ESP.

Preparing images for the web | Markup for images | Image captions | Externally hosted images | Image maps

Images

Preparing images for the web

Decide on a width for standard-size images and stick to it. (The images on the Knowledge & Power [/saao/knpp] site are 9cm in width but have varying heights.)

If large images are required, create a link to a larger version from the standard-sized image. Choose sizes for large images according to how much detail is required, but remember to keep the file size as small as possible.

Follow the Style Guide when selecting images, writing captions and citing image sources.

Images need to be optimised correctly for use on the web. Please use the following guidelines:

Manipulation: Use a graphics editor to manipulate image size and resolution. Only use a graphics editor with a 'save for web' option. We recommend GIMP [http://www.gimp.org/] (for Windows, Mac, Unix) which is free and has a similar level of functionality to Photoshop.
Resolution and format: Images need to be 72dpi resolution PNG or JPG files. JPG is a compressed format that gives a smaller file size. PNG format gives better quality but larger file size. A good brief guide to optimising images for the web is given by Google Developers [https://developers.google.com/speed/articles/optimizing-images]. As a general rule: use PNG-8 for graphics; use JPG for photographic images and adjust the compression to an acceptable level (the Nimrud project uses compression level 60).
File size: The ESP processor will report a warning if images within xml pages are too large (over XX KB in size).

Store all images for use on the site in your project's 00res/images folder, or in subfolders inside it. To organise your images, consider creating subfolders with the same hierarchy as your site's navigational structure.

Markup for images

Images are inserted using the <esp:image> element. Image width and height are retrieved and used automatically by the processor.

By default, the processor will look for the images in the 00res/images folder. The file attribute within <esp:image> specifies the location of the image relative to the .../images folder. So for an image entitled esarhaddon.jpg located in the folder .../images/contexts, the file attribute should read: file="contexts/esarhaddon.jpg".

Do not include a leading forward slash when specifying the image location (i.e., do not do this: file="/contexts/esarhaddon.jpg") or the image and its caption will not float correctly.

The specification for how to use the <esp:image> element is given below:

<esp:image
	file="example.jpg"
	description="Example image"
	position="float" or position="inline" (default)	
>
        <esp:link url="blah"> (optional)
	<esp:caption>Here is a caption.</esp:caption>
</esp:image>

file: Mandatory. The location of the image relative to the 00res/images folder. Image files must be JPG or GIF format.
description: Mandatory. Will be presented to users of text browsers or screen readers, and is required for WAI [http://www.w3.org/WAI/] compliance. Should give a concise description of the image.
position: Optional. May be float, which causes the image to appear on the right and text to flow around it, or inline (the default), which causes the image to break up the text above and below it. (The images for the Knowledge & Power [http://oracc.museum.upenn.edu/saao/knpp] site are all aligned to the right using the float attribute.)

Image captions

The <esp:image> element can contain a <esp:caption> element, which will display caption text underneath the image. The caption can contain links, e.g., to a large version of the image, as described in the section on Links within image captions.

The <esp:image> element itself may contain zero or one empty <esp:link> elements, which will make the image into a link, as described in the section on Links within image captions.

Linking to large versions of images

It is possible to create a link to a large version of an image using a relative URL. This linked image will appear as a standalone entity, rather than within a page.

Externally hosted images

The <esp:image> tag can be utilised to include images hosted on other websites, using the url attribute instead of the file attribute:

<esp:image
	url="http://www.example.com/example.jpg"
	description="Example image"
	position="left" or position="right"  or position="inline" (default)	
>
Example image caption (optional)
</esp:image>

url: Mandatory. The location of the image.
description: Mandatory. Will be presented to users of text browsers or screen readers, and is required for WAI [http://www.w3.org/WAI/] compliance. Should give a concise description of the image.
position: Optional. May be right or left which causes the image to appear on the right/left and text to flow around it, or inline (the default), which causes the image to break up the text above and below it. The value right replaces the old value float and gives the same effect.

The element may contain zero or one empty <esp:link> tags, which will end up placed around the image itself. If there is no <esp:link> tag, it may contain zero or one <esp:caption> tags.

Image maps

ESP no longer supports image maps as they are very difficult to scale to fit small screens on hand-held devices. Email osc at oracc dot org to discuss alternatives.

Next steps

Once you have some textual and image content you are ready to check and (re)build your ESP website if you are an ESP site manager. If you are creating ESP content for someone else, ask them to check and upload it for you.

18 Dec 2019 osc at oracc dot org

Ruth Horry & Eleanor Robson

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