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

From EPrints Documentation
Jump to: navigation, search
Line 8: Line 8:
 
'''EPrints::Apache::Template''' - Template Applying Module
 
'''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_synopsis -->
 
<!-- Pod2Wiki=head_synopsis -->
 
==SYNOPSIS==
 
==SYNOPSIS==
  &lt;?xml version="1.0" standalone="no"?&gt;
+
<source lang="perl"><?xml version="1.0" standalone="no"?>
  &lt;!DOCTYPE html SYSTEM "entities.dtd"&gt;
+
<!DOCTYPE html SYSTEM "entities.dtd">
  &lt;html xmlns="http://www.w3.org/1999/xhtml" xmlns:epc="http://eprints.org/ep3/control"&gt;
+
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:epc="http://eprints.org/ep3/control">
    &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;
+
  <title><epc:pin ref="title" textonly="yes"/> - <epc:phrase ref="archive_name"/></title>
    ...
+
  ...</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_description -->
 
==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.
+
This module renders HTML page content using a template.
  
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]].
+
Templates are parsed and rendered at server start-up, expanding phrases and any EPC. If you need to include dynamic content in the page use use a pin generated via [[API:EPrints/Apache/Template#Dynamic_Pins|Dynamic Pins]].
  
The page content is added to the template via &lt;epc:pins&gt;.
+
The page title, content and other core page structures are supplied via [[API:EPrints/Apache/Template#Default_Pins|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 -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_static_html_pages -->
<!-- Pod2Wiki=head_custom_pins -->
+
===Static HTML Pages===
===Custom Pins===
+
Static files with the ''.xpage'' extension are rendered using templates:
In <tt>cfg.d/dynamic_template.pl</tt>:
+
  
  $c-&gt;{dynamic_template}-&gt;{function} = sub {
+
<pre>  &lt;?xml version="1.0" encoding="utf-8"  standalone="no"  ?&gt;
    my( $repo, $parts ) = @_;
+
  &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;
     $parts-&gt;{mypin} = $repo-&gt;xml-&gt;create_text_node( "Hello, World!" );
+
     &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;
In <tt>archives/[archiveid]/cfg/templates/default.xml</tt> (copy from <tt>lib/templates/default.xml</tt> if not already exists):
+
    &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>
  
  &lt;epc:pin ref="mypin" /&gt;
+
<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).
 
+
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= -->
</div>
 
 
<!-- Pod2Wiki=head_default_pins -->
 
<!-- Pod2Wiki=head_default_pins -->
 
===Default Pins===
 
===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%; '>
+
* title
<span style='display:none'>User Comments</span>
+
: The title of the page.
<!-- Edit below this comment -->
+
  
 +
* page
 +
: The page content.
  
<!-- Pod2Wiki= -->
+
* login_status_header
</div>
+
: HTML &lt;head&gt; includes for the login status of the user - currently just some JavaScript variables.
<!-- Pod2Wiki=item_title -->
+
====title====
+
  
The title of the page.
+
* head
 +
: Page-specific HTML &lt;head&gt; contents.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
* pagetop
<span style='display:none'>User Comments</span>
+
: (Unused?)
<!-- 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_page -->
+
====page====
+
  
The page content.
+
* 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%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=head_dynamic_pins -->
<!-- Pod2Wiki=item_login_status_header -->
+
===Dynamic Pins===
====login_status_header====
+
In <code>cfg.d/dynamic_template.pl</code>:
  
HTML &lt;head&gt; includes for the login status of the user - currently just some JavaScript variables.
+
<pre>  $c-&gt;{dynamic_template}-&gt;{function} = sub {
 +
    my( $repo, $parts ) = @_;
 +
 
 +
    $parts->{mypin} = $repo->xml->create_text_node( "Hello, World!" );
 +
  };</pre>
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
In <code>archives/[archiveid]/cfg/templates/default.xml</code> (copy from <code>lib/templates/default.xml</code> if not already exists):
<span style='display:none'>User Comments</span>
+
<!-- Edit below this comment -->
+
  
 +
<pre>  &lt;epc:pin ref="mypin" /&gt;</pre>
  
<!-- Pod2Wiki= -->
+
Or, for just the text content of a pin:
</div>
+
<!-- Pod2Wiki=item_head -->
+
====head====
+
  
Page-specific HTML &lt;head&gt; contents.
+
<pre>  &lt;epc:pin ref="mypin" textonly="yes" /&gt;</pre>
  
<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_pagetop -->
+
==METHODS==
====pagetop====
+
 
+
(Unused?)
+
 
+
<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=item_login_status -->
+
==SEE ALSO==
====login_status====
+
The directories scanned for template sources are in [[API:EPrints/Repository#template_dirs|EPrints::Repository/template_dirs]].
  
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.
 
 
Historically this was the login/logout links plus <tt>key_tools</tt> but since 3.3 login/logout are Screen plugins as well.
 
 
<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=item_languages -->
+
==COPYRIGHT==
====languages====
+
Copyright 2000-2011 University of Southampton.
  
The <tt>render_action_link</tt> from [[API:EPrints/Plugin/Screen/SetLang|EPrints::Plugin::Screen::SetLang]].
+
This file is part of EPrints http://www.eprints.org/.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
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.
<span style='display:none'>User Comments</span>
+
<!-- Edit below this comment -->
+
  
 +
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.
  
<!-- Pod2Wiki= -->
+
You should have received a copy of the GNU Lesser General Public License along with EPrints.  If not, see http://www.gnu.org/licenses/.
</div>
+
<!-- Pod2Wiki=head_see_also -->
+
==SEE ALSO==
+
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=_postamble_ -->
<!-- Pod2Wiki=head_copyright -->
+
==COPYRIGHT==
+
<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= -->
 
</div>
 
<!-- Pod2Wiki=_postamble_ --><!-- Edit below this comment -->
 

Revision as of 15:53, 16 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.3, 3.2) | Revision Log | Before editing this page please read Pod2Wiki


NAME

EPrints::Apache::Template - Template Applying Module


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


DESCRIPTION

This module renders HTML page content using a template.

Templates are parsed and rendered at server start-up, expanding phrases and any EPC. If you need to include dynamic content in the page use use a pin generated via Dynamic Pins.

The page title, content and other core page structures are supplied via Default Pins.


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

  • title
The title of the page.
  • page
The page content.
  • login_status_header
HTML <head> includes for the login status of the user - currently just some JavaScript variables.
  • head
Page-specific HTML <head> contents.
  • pagetop
(Unused?)
  • 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.


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