Difference between revisions of "API:EPrints/Apache/Template"

From EPrints Documentation
Jump to: navigation, search
(16 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
<!-- Pod2Wiki=_preamble_  
 
<!-- Pod2Wiki=_preamble_  
 
This page has been automatically generated from the EPrints 3.2 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
 
This page has been automatically generated from the EPrints 3.2 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
  -->{{API}}{{Pod2Wiki}}{{API:Source|file=EPrints/Apache/Template.pm|package_name=EPrints::Apache::Template}}[[Category:API|TEMPLATE]][[Category:API:EPrints/Apache|TEMPLATE]][[Category:API:EPrints/Apache/Template|TEMPLATE]]<div><!-- Edit below this comment -->
+
  -->{{API}}{{Pod2Wiki}}{{API:Source|file=perl_lib/EPrints/Apache/Template.pm|package_name=EPrints::Apache::Template}}[[Category:API|TEMPLATE]][[Category:API:EPrints/Apache|TEMPLATE]][[Category:API:EPrints/Apache/Template|TEMPLATE]]<div><!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name -->
 
<!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name -->
 
==NAME==
 
==NAME==
'''EPrints::Apache::Template''' - Template Applying Module
+
EPrints::Apache::Template - renders a page using a template
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_synopsis -->
<!-- Pod2Wiki=head_description -->
+
==SYNOPSIS==
==DESCRIPTION==
+
<source lang="xml"><?xml version="1.0" standalone="no"?>
When HTML pages are served by EPrints they are processed through a template file. There are typically two template files, one for HTTP and one for HTTPS (if configured).
+
<!DOCTYPE html SYSTEM "entities.dtd">
 
+
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epc="http://eprints.org/ep3/control">
Templates are parsed at the server start-up which expands any included phrases. The resulting document is split into chunks where a chunk is either a section of XHTML or an &lt;epc:pin&gt;. Pins are replaced with the page content.
+
   <head>
 
+
    <title><epc:pin ref="title" textonly="yes"/> - <epc:phrase ref="archive_name"/></title>
&lt;source lang="html"&gt; &lt;?xml version="1.0" standalone="no"?&gt; &lt;!DOCTYPE html SYSTEM "entities.dtd"&gt; &lt;html xmlns="http://www.w3.org/1999/xhtml" xmlns:epc="http://eprints.org/ep3/control"&gt;
+
    <epc:pin ref="head" />
   &lt;head&gt;
+
  </head>
      &lt;title&gt;&lt;epc:pin ref="title" textonly="yes"/&gt; - &lt;epc:phrase ref="archive_name"/&gt;&lt;/title&gt; &lt;/source&gt;
+
  <body>
 +
    <div><epc:pin ref="login_status" /> <epc:pin ref="languages" /></div>
 +
    <h1><epc:pin ref="title" /></h1>
 +
    <p><epc:pin ref="body" /></p>
 +
  </body>
 +
</html></source>
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_description -->
<!-- Pod2Wiki=head_pins -->
+
==DESCRIPTION==
===Pins===
+
Templates are used to generate the basic layout of the pages in your repository. Different templates can be used to customise sub-sections, or even individual pages.
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
  
 +
A template file is written in XML and contains a mix of HTML elements and dynamic pins. Pins are locators for content that, when a page is requested, are replaced with the page's title, content etc.
  
<!-- Pod2Wiki= -->
+
See [[API:EPrints/Apache/Template#Default_Pins|Default Pins]] for the basic pins available for all pages and [[API:EPrints/Apache/Template#Dynamic_Pins|Dynamic Pins]] for how to create dynamic content.
</div>
 
<!-- Pod2Wiki=item_title -->
 
====title====
 
  
The title of the page.
+
Template files are read from [[API:EPrints/Repository#template_dirs|EPrints::Repository/template_dirs]]. If you need to customise the template you should copy it into your repository, rather than editing the system-wide template.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_static_html_pages -->
<!-- Pod2Wiki=item_page -->
+
===Static HTML Pages===
====page====
+
Static files with the ''.xpage'' extension are rendered using templates:
  
The page content.
+
<source lang="xml"><?xml version="1.0" encoding="utf-8"  standalone="no"  ?>
 +
<!DOCTYPE page SYSTEM "entities.dtd" >
 +
<xpage:page xmlns="http://www.w3.org/1999/xhtml" xmlns:xpage="http://eprints.org/ep3/xpage" xmlns:epc="http://eprints.org/ep3/control">
 +
<xpage:template>default</xpage:template>
 +
<xpage:head>
 +
<style type="text/css">h1 { text-weight: bold }</style>
 +
</xpage:head>
 +
<xpage:title>My first XPage</xpage:title>
 +
<xpage:body>
 +
Writing XPages is easy.
 +
</xpage:body>
 +
</xpage:page></source>
 +
 
 +
<code>&lt;xpage:template&gt;</code> is a special pin that, instead of supplying content to the template, changes the template used for rendering. The content is just the template name (without the ''.xml'' extension).
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_default_pins -->
<!-- Pod2Wiki=item_login_status_header -->
+
===Default Pins===
====login_status_header====
+
* head
 +
: Page-specific HTML &lt;head&gt; contents.
  
HTML &lt;head&gt; includes for the login status of the user - currently just some JavaScript variables.
+
* title
 +
: The title of the page.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
* page
<span style='display:none'>User Comments</span>
+
: The page content.
<!-- Edit below this comment -->
 
  
 +
* login_status
 +
: A menu containing [[API:EPrints/Plugin/Screen|EPrints::Plugin::Screen]]s that appear in <code>key_tools</code>. The content from each plugin's <code>render_action_link</code> is rendered as a HTML &lt;ul&gt; list.
  
<!-- Pod2Wiki= -->
+
: Historically this was the login/logout links plus <code>key_tools</code> but since 3.3 login/logout are Screen plugins as well.
</div>
 
<!-- Pod2Wiki=item_head -->
 
====head====
 
  
Page-specific HTML &lt;head&gt; contents.
+
* languages
 +
: The <code>render_action_link</code> from [[API:EPrints/Plugin/Screen/SetLang|EPrints::Plugin::Screen::SetLang]].
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
* pagetop - <em>unused</em>
<span style='display:none'>User Comments</span>
+
* login_status_header - <em>unused</em>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_dynamic_pins -->
<!-- Pod2Wiki=item_pagetop -->
+
===Dynamic Pins===
====pagetop====
+
In <code>cfg.d/dynamic_template.pl</code>:
  
(Unused?)
+
<source lang="perl">$c->{dynamic_template}->{function} = sub {
 +
my( $repo, $parts ) = @_;
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
$parts->{mypin} = $repo->xml->create_text_node( "Hello, World!" );
<span style='display:none'>User Comments</span>
+
};</source>
<!-- Edit below this comment -->
 
  
 +
In <code>archives/[archiveid]/cfg/templates/default.xml</code> (copy from <code>lib/templates/default.xml</code> if not already exists):
  
<!-- Pod2Wiki= -->
+
<source lang="perl"><epc:pin ref="mypin" /></source>
</div>
 
<!-- Pod2Wiki=item_login_status -->
 
====login_status====
 
  
A menu containing [[API:EPrints/Plugin/Screen|EPrints::Plugin::Screen]]s that appear in <tt>key_tools</tt>. The content from each plugin's <tt>render_action_link</tt> is rendered as a HTML &lt;ul&gt; list.
+
Or, for just the text content of a pin:
  
Historically this was the login/logout links plus <tt>key_tools</tt> but since 3.3 login/logout are Screen plugins as well.
+
<source lang="perl"><epc:pin ref="mypin" textonly="yes" /></source>
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_methods -->
<!-- Pod2Wiki=item_languages -->
+
==METHODS==
====languages====
 
 
 
The <tt>render_action_link</tt> from [[API:EPrints/Plugin/Screen/SetLang|EPrints::Plugin::Screen::SetLang]].
 
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
 
 
<!-- Pod2Wiki=head_see_also -->
 
<!-- Pod2Wiki=head_see_also -->
 
==SEE ALSO==
 
==SEE ALSO==
[[API:EPrints/Repository#template_dirs|EPrints::Repository/template_dirs]]
+
The directories scanned for template sources are in [[API:EPrints/Repository#template_dirs|EPrints::Repository/template_dirs]].
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
 
 
<!-- Pod2Wiki=head_copyright -->
 
<!-- Pod2Wiki=head_copyright -->
 
==COPYRIGHT==
 
==COPYRIGHT==
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #ccepadding: 0em 1em 0em 1em; font-size: 80%; '>
+
Copyright 2000-2012 University of Southampton.
<span style='display:none'>User Comments</span>
+
 
 +
This file is part of EPrints http://www.eprints.org/.
 +
 
 +
EPrints is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
 +
 
 +
EPrints is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
 +
 
 +
You should have received a copy of the GNU Lesser General Public License along with EPrints.  If not, see http://www.gnu.org/licenses/.
 +
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=_postamble_ -->
<!-- Pod2Wiki=_postamble_ --><!-- Edit below this comment -->
+
<!-- Edit below this comment -->

Revision as of 11:16, 18 April 2012

EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects


API: Core API

Latest Source Code (3.4, 3.3) | Revision Log | Before editing this page please read Pod2Wiki


NAME

EPrints::Apache::Template - renders a page using a template


SYNOPSIS

<?xml version="1.0" standalone="no"?>
<!DOCTYPE html SYSTEM "entities.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epc="http://eprints.org/ep3/control">
  <head>
    <title><epc:pin ref="title" textonly="yes"/> - <epc:phrase ref="archive_name"/></title>
    <epc:pin ref="head" />
  </head>
  <body>
    <div><epc:pin ref="login_status" /> <epc:pin ref="languages" /></div>
    <h1><epc:pin ref="title" /></h1>
    <p><epc:pin ref="body" /></p>
  </body>
</html>


DESCRIPTION

Templates are used to generate the basic layout of the pages in your repository. Different templates can be used to customise sub-sections, or even individual pages.

A template file is written in XML and contains a mix of HTML elements and dynamic pins. Pins are locators for content that, when a page is requested, are replaced with the page's title, content etc.

See Default Pins for the basic pins available for all pages and Dynamic Pins for how to create dynamic content.

Template files are read from EPrints::Repository/template_dirs. If you need to customise the template you should copy it into your repository, rather than editing the system-wide template.


Static HTML Pages

Static files with the .xpage extension are rendered using templates:

<?xml version="1.0" encoding="utf-8"  standalone="no"  ?>
<!DOCTYPE page SYSTEM "entities.dtd" >
<xpage:page xmlns="http://www.w3.org/1999/xhtml" xmlns:xpage="http://eprints.org/ep3/xpage" xmlns:epc="http://eprints.org/ep3/control">
	<xpage:template>default</xpage:template>
	<xpage:head>
		<style type="text/css">h1 { text-weight: bold }</style>
	</xpage:head>
	<xpage:title>My first XPage</xpage:title>
	<xpage:body>
		Writing XPages is easy.
	</xpage:body>
</xpage:page>

<xpage:template> is a special pin that, instead of supplying content to the template, changes the template used for rendering. The content is just the template name (without the .xml extension).


Default Pins

  • head
Page-specific HTML <head> contents.
  • title
The title of the page.
  • page
The page content.
  • login_status
A menu containing EPrints::Plugin::Screens that appear in key_tools. The content from each plugin's render_action_link is rendered as a HTML <ul> list.
Historically this was the login/logout links plus key_tools but since 3.3 login/logout are Screen plugins as well.
  • languages
The render_action_link from EPrints::Plugin::Screen::SetLang.
  • pagetop - unused
  • login_status_header - unused


Dynamic Pins

In cfg.d/dynamic_template.pl:

$c->{dynamic_template}->{function} = sub {
	my( $repo, $parts ) = @_;

	$parts->{mypin} = $repo->xml->create_text_node( "Hello, World!" );
};

In archives/[archiveid]/cfg/templates/default.xml (copy from lib/templates/default.xml if not already exists):

<epc:pin ref="mypin" />

Or, for just the text content of a pin:

<epc:pin ref="mypin" textonly="yes" />


METHODS

SEE ALSO

The directories scanned for template sources are in EPrints::Repository/template_dirs.


COPYRIGHT

Copyright 2000-2012 University of Southampton.

This file is part of EPrints http://www.eprints.org/.

EPrints is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

EPrints is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with EPrints. If not, see http://www.gnu.org/licenses/.