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

From EPrints Documentation
Jump to: navigation, search
 
(7 intermediate revisions by 2 users 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.4 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' comments will be lost.
−
  -->{{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 -->
+
  -->{{API}}{{Pod2Wiki}}{{API:Source|file=EPrints/Apache/Template.pm|package_name=EPrints::Apache::Template}}[[Category:API|TEMPLATE]][[Category:API:EPrints/Apache|TEMPLATE]]<div><!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name -->
 
<!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name -->
 
==NAME==
 
==NAME==
−
EPrints::Apache::Template - renders a page using a template
+
'''EPrints::Apache::Template''' - Template Applying Module
  
 +
<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 -->
 +
==DESCRIPTION==
 +
When HTML pages are served by EPrints they are processed through a  template written in XML. Most repositories will have two templates -  ''default.xml'' for HTTP and ''secure.xml'' for HTTPS.
 +
 +
Templates are parsed at '''server start-up''' and any included phrases  are replaced at that point. Because templates persist over the  lifetime of a server you do not typically perform any logic within  the template itself, instead use a pin generated via [[API:EPrints/Apache/Template#Custom_Pins|Custom Pins]].
 +
 +
The page content is added to the template via <tt>&lt;epc:pins</tt>&gt;.
 +
 +
<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 -->
 +
 +
 +
<!-- Pod2Wiki= -->
 +
</div>
 
<!-- Pod2Wiki=head_synopsis -->
 
<!-- Pod2Wiki=head_synopsis -->
−
==SYNOPSIS==
+
===Synopsis===
−
<source lang="html
+
  &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;
 +
    &lt;head&gt;
 +
      &lt;title&gt;&lt;epc:pin ref="title" textonly="yes"/&gt; - &lt;epc:phrase ref="archive_name"/&gt;&lt;/title&gt;
 +
    ...
 +
 
 +
<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 -->
  
−
"><?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></source>
 
  
 +
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=head_custom_pins -->
 +
===Custom Pins===
 +
In ''cfg.d/dynamic_template.pl'':
 +
 +
  $c-&gt;{dynamic_template}-&gt;{function} = sub {
 +
    my( $repo, $parts ) = @_;
 +
 
 +
    $parts-&gt;{mypin} = $repo-&gt;xml-&gt;create_text_node( "Hello, World!" );
 +
  };
 +
 
 +
In ''archives/[archiveid]/cfg/templates/default.xml'' (copy from  ''lib/templates/default.xml'' if not already exists):
 +
 +
  &lt;epc:pin ref="mypin" /&gt;
 +
 
 +
Or, for just the text content of a pin:
 +
 +
  &lt;epc:pin ref="mypin" textonly="yes" /&gt;
 +
 
 +
<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= -->
−
<!-- Pod2Wiki=head_description -->
+
</div>
−
==DESCRIPTION==
+
<!-- Pod2Wiki=head_default_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.
+
===Default Pins===
 +
<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.
 
  
−
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.
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_title -->
 +
====title====
  
−
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.
+
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%; '>
 +
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
−
<!-- Pod2Wiki=head_static_html_pages -->
+
</div>
−
===Static HTML Pages===
+
<!-- Pod2Wiki=item_page -->
−
Static files with the ''.xpage'' extension are rendered using templates:
+
====page====
 +
 
 +
The page content.
 +
 
 +
<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 -->
  
−
<pre>  &lt;?xml version="1.0" encoding="utf-8"  standalone="no"  ?&gt;
 
−
  &lt;!DOCTYPE page SYSTEM "entities.dtd" &gt;
 
−
  &lt;xpage:page xmlns="http://www.w3.org/1999/xhtml" xmlns:xpage="http://eprints.org/ep3/xpage" xmlns:epc="http://eprints.org/ep3/control"&gt;
 
−
    &lt;xpage:template&gt;default&lt;/xpage:template&gt;
 
−
    &lt;xpage:head&gt;
 
−
      &lt;style type="text/css"&gt;h1 { text-weight: bold }&lt;/style&gt;
 
−
    &lt;/xpage:head&gt;
 
−
    &lt;xpage:title&gt;My first XPage&lt;/xpage:title&gt;
 
−
    &lt;xpage:body&gt;
 
−
      Writing XPages is easy.
 
−
    &lt;/xpage:body&gt;
 
−
  &lt;/xpage:page&gt;</pre>
 
  
−
<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).
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_login_status_header -->
 +
====login_status_header====
  
 +
HTML <tt>&lt;head</tt>&gt; includes for the login status of the user - currently  just some JavaScript variables.
 +
 +
<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= -->
−
<!-- Pod2Wiki=head_default_pins -->
+
</div>
−
===Default Pins===
+
<!-- Pod2Wiki=item_head -->
−
* head
+
====head====
−
: Page-specific HTML &lt;head&gt; contents.
 
  
−
* title
+
Page-specific HTML <tt>&lt;head</tt>&gt; contents.
−
: The title of the page.
 
  
−
* page
+
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
−
: The page content.
+
<span style='display:none'>User Comments</span>
 +
<!-- 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.
 
  
−
: Historically this was the login/logout links plus <code>key_tools</code> but since 3.3 login/logout are Screen plugins as well.
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_pagetop -->
 +
====pagetop====
  
−
* languages
+
(Unused?)
−
: The <code>render_action_link</code> from [[API:EPrints/Plugin/Screen/SetLang|EPrints::Plugin::Screen::SetLang]].
 
  
−
* pagetop - <em>unused</em>
+
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
−
* login_status_header - <em>unused</em>
+
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
−
<!-- Pod2Wiki=head_dynamic_pins -->
+
</div>
−
===Dynamic Pins===
+
<!-- Pod2Wiki=item_login_status -->
−
In <code>cfg.d/dynamic_template.pl</code>:
+
====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  <tt>&lt;ul</tt>&gt; list.
  
−
<pre>  $c-&gt;{dynamic_template}-&gt;{function} = sub {
+
Historically this was the login/logout links plus <tt>key_tools</tt> but since  3.3 login/logout are Screen plugins as well.
−
    my( $repo, $parts ) = @_;
 
−
 
 
−
    $parts->{mypin} = $repo->xml->create_text_node( "Hello, World!" );
 
−
  };</pre>
 
  
−
In <code>archives/[archiveid]/cfg/templates/default.xml</code> (copy from <code>lib/templates/default.xml</code> if not already exists):
+
<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 -->
  
−
<pre>  &lt;epc:pin ref="mypin" /&gt;</pre>
 
  
−
Or, for just the text content of a pin:
+
<!-- Pod2Wiki= -->
 +
</div>
 +
<!-- Pod2Wiki=item_languages -->
 +
====languages====
  
−
<pre> &lt;epc:pin ref="mypin" textonly="yes" /&gt;</pre>
+
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_methods -->
 
<!-- Pod2Wiki=head_methods -->
 
==METHODS==
 
==METHODS==
 +
<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=item_handler -->
 +
===handler===
 +
 +
$rc = EPrints::Apache::Template::handler( $r )
 +
Handler for applying site layout templates.
 +
 +
<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 -->
 +
 +
 +
<!-- Pod2Wiki= -->
 +
</div>
 
<!-- Pod2Wiki=head_see_also -->
 
<!-- Pod2Wiki=head_see_also -->
 
==SEE ALSO==
 
==SEE ALSO==
−
The directories scanned for template sources are in [[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==
−
Copyright 2000-2012 University of Southampton.
+
{{API:Copyright}}
−
 
+
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
−
This file is part of EPrints http://www.eprints.org/.
+
<span style='display:none'>User Comments</span>
−
 
 
−
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= -->
−
<!-- Pod2Wiki=_postamble_ -->
+
</div>
−
<!-- Edit below this comment -->
+
<!-- Pod2Wiki=_postamble_ --><!-- Edit below this comment -->

Latest revision as of 17:25, 15 March 2023

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 - Template Applying Module

User Comments


DESCRIPTION

When HTML pages are served by EPrints they are processed through a template written in XML. Most repositories will have two templates - default.xml for HTTP and secure.xml for HTTPS.

Templates are parsed at server start-up and any included phrases are replaced at that point. Because templates persist over the lifetime of a server you do not typically perform any logic within the template itself, instead use a pin generated via Custom Pins.

The page content is added to the template via <epc:pins>.

User Comments


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>
   ...

User Comments


Custom 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" />

User Comments


Default Pins

User Comments


title

The title of the page.

User Comments


page

The page content.

User Comments


login_status_header

HTML <head> includes for the login status of the user - currently just some JavaScript variables.

User Comments


head

Page-specific HTML <head> contents.

User Comments


pagetop

(Unused?)

User Comments


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.

User Comments


languages

The render_action_link from EPrints::Plugin::Screen::SetLang.

User Comments


METHODS

User Comments


handler

$rc = EPrints::Apache::Template::handler( $r )

Handler for applying site layout templates.

User Comments


SEE ALSO

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

User Comments


COPYRIGHT

© Copyright 2023 University of Southampton.

EPrints 3.4 is supplied by EPrints Services.

http://www.eprints.org/eprints-3.4/

LICENSE

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

EPrints 3.4 and this file are released under the terms of the GNU Lesser General Public License version 3 as published by the Free Software Foundation unless otherwise stated.

EPrints 3.4 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 3.4. If not, see http://www.gnu.org/licenses/.

User Comments


Retrieved from ‘https://wiki.eprints.org/w/index.php?title=API:EPrints/Apache/Template&oldid=15686’