Editing Branding with confidence (section)

===Changing the page layout===

Every page in your repository is displayed using a single template. A custom layout can be applied to your repository pages by editing this template.

Copy the default layout to your repository:

 cp lib/templates/default.xml archives/ARCHIVEID/cfg/templates/default.xml

Open the template file for your repository:

 archives/ARCHIVEID/cfg/templates/default.xml

The template is an XHTML file with some additional syntax (see [[API:EPrints/Apache/Template]]).

====Pins====

You will notice a number of epc:pin elements. These tell EPrints how to combine the template with page-specific content to build each individual page.

'''Example

<source lang="xml">
    <div>
      <div class="ep_tm_page_content">
        <h1 class="ep_tm_pagetitle">
          <epc:pin ref="title"/>
        </h1>
        <epc:pin ref="page"/>
      </div>
    </div>
</source>

This part of the template lays out the main content area of the page (the ''page'' pin) which is centered on the page.

You can incorporate the epc:pin elements however you like into your new layout (although note that the head pin should always be inside the head section of the template, and the pagetop pin should be at the start of the body section). You can also define new pins (see below).

====Configuration Strings====

There are also a number of epc:print elements in the default template which are useful for including configuration values in the template.

'''Example

<source lang="html4strict">
<style type="text/css" media="screen">@import url(<epc:print expr="$config{base_url}"/>/style/auto.css);</style>
</source>

This extract from the head section of the template shows how an epc:print element is used to refer to the base URL of the repository. This avoids hardcoding URLs into the template (which is good for maintainability - if the repository URL should change, you do not have to change the template).

Configuration values can also be used inside attributes, using the {...} syntax.

'''Example

<source lang="html4strict">
<a href="{$config{frontpage}}"><img alt="Logo" src="{$config{site_logo}}" /></a>
</source>

This extract shows how the URL of both the front page of the repository and the logo are derived from the configuration rather than being hard coded directly into the template.

====Template checklist====

A typical repository page layout will include:

# the correct XML declaration at the top of the file
# a head section (load default and custom stylesheets, ''title'' and ''head'' pins)
# a body section, containing:
## ''pagetop'' pin
## header (repository title and logo)
## navigation menu (links to browse, search etc.)
## quick search box
## toolbar (''login_status'' and ''toolbar'' pins)
## main content area (''title'' and ''page'' pins)
## footer (copyright notice etc.)

====Loading the new template====

Load your new template by running:

 bin/epadmin reload ARCHIVEID

====Dealing with template errors====

A common cause of errors when loading a new template is that the template is not ''well formed''. The template is in XHTML syntax, and therefore must follow the rules for writing well-formed XML documents:

* http://en.wikipedia.org/wiki/XML#Well-formed_documents

'''Example

You get the following error when reloading the template:

 parser error : Opening and ending tag mismatch: img line 25 and div

Open the template file, and look for an img tag on line 25:

 <img src="/images/mylogo.gif"> 

The problem is that the img tag is opened, but there is no closing img tag. The img element is empty, so we can add a self-closing tag to make the eleemtn well formed:

 <img src="/images/mylogo.gif" /> 

'''Example

 parser error : Opening and ending tag mismatch: p line 60 and body

Open the template file and look for the p tag on line 60:

<pre>
 <p>This repository is maintained by the <b>Library and Computing team</b>.
</pre>

There is no closing p tag. The p element is not empty, so we add a closing p tag at the end of the paragraph to make the element well formed:

<pre>
 <p>This repository is maintained by the <b>Library and Computing team</b>.</p>
</pre>