Difference between revisions of "API:EPrints/Session"

From EPrints Documentation
Jump to: navigation, search
Line 2: Line 2:
 
This page has been automatically generated from the EPrints source. Any wiki changes made between the 'Pod2Wiki=*' and 'End of Pod2Wiki' comments will be lost.
 
This page has been automatically generated from the EPrints source. Any wiki changes made between the 'Pod2Wiki=*' and 'End of Pod2Wiki' comments will be lost.
 
  -->{{Pod2Wiki}}{{API:Source|file=EPrints/Session.pm|package_name=EPrints::Session}}[[Category:API|Session]]<!-- End of Pod2Wiki -->
 
  -->{{Pod2Wiki}}{{API:Source|file=EPrints/Session.pm|package_name=EPrints::Session}}[[Category:API|Session]]<!-- End of Pod2Wiki -->
<!-- Pod2Wiki=head_name -->'''EPrints::Session''' - Single connection to the EPrints system
+
<!-- Pod2Wiki=head_name -->=NAME=
__TOC__
+
'''EPrints::Session''' - Single connection to the EPrints system
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_description -->=DESCRIPTION=
 
<!-- Pod2Wiki=head_description -->=DESCRIPTION=
 
This module is not really a session. The name is out of date, but hard to change.
 
This module is not really a session. The name is out of date, but hard to change.
 +
 
EPrints::Session represents a connection to the EPrints system. It connects to a single EPrints repository, and the database used by that repository. Thus it has an associated EPrints::Database and EPrints::Repository object.
 
EPrints::Session represents a connection to the EPrints system. It connects to a single EPrints repository, and the database used by that repository. Thus it has an associated EPrints::Database and EPrints::Repository object.
 +
 
Each "session" has a "current language". If you are running in a  multilingual mode, this is used by the HTML rendering functions to choose what language to return text in.
 
Each "session" has a "current language". If you are running in a  multilingual mode, this is used by the HTML rendering functions to choose what language to return text in.
 +
 
The "session" object also knows about the current apache connection, if there is one, including the CGI parameters.  
 
The "session" object also knows about the current apache connection, if there is one, including the CGI parameters.  
 +
 
If the connection requires a username and password then it can also  give access to the EPrints::DataObj::User object representing the user who is causing this request.  
 
If the connection requires a username and password then it can also  give access to the EPrints::DataObj::User object representing the user who is causing this request.  
 +
 
The session object also provides many methods for creating XHTML  results which can be returned via the web interface.  
 
The session object also provides many methods for creating XHTML  results which can be returned via the web interface.  
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_new -->==new==
 
<!-- Pod2Wiki=item_new -->==new==
Line 18: Line 25:
  
 
Create a connection to an EPrints repository which provides access  to the database and to the repository configuration.
 
Create a connection to an EPrints repository which provides access  to the database and to the repository configuration.
 +
 
This method can be called in two modes. Setting $mode to 0 means this is a connection via a CGI web page. $repository_id is ignored, instead the value is taken from the "PerlSetVar EPrints_ArchiveID" option in the apache configuration for the current directory.
 
This method can be called in two modes. Setting $mode to 0 means this is a connection via a CGI web page. $repository_id is ignored, instead the value is taken from the "PerlSetVar EPrints_ArchiveID" option in the apache configuration for the current directory.
 +
 
If this is being called from a command line script, then $mode should be 1, and $repository_id should be the ID of the repository we want to connect to.
 
If this is being called from a command line script, then $mode should be 1, and $repository_id should be the ID of the repository we want to connect to.
 +
 
$mode : mode = 0    - We are online (CGI script) mode = 1    - We are offline (bin script) $repository_id is repository_id mode = 2    - We are online, but don't create a CGI query (so we
 
$mode : mode = 0    - We are online (CGI script) mode = 1    - We are offline (bin script) $repository_id is repository_id mode = 2    - We are online, but don't create a CGI query (so we
 
  don't consume the data).
 
  don't consume the data).
 +
 
$noise is the level of debugging output. 0 - silent 1 - quietish 2 - noisy 3 - debug all SQL statements 4 - debug database connection
 
$noise is the level of debugging output. 0 - silent 1 - quietish 2 - noisy 3 - debug all SQL statements 4 - debug database connection
  Under normal conditions use "0" for online and "1" for offline.
+
   
 +
Under normal conditions use "0" for online and "1" for offline.
 +
 
 
$nocheckdb - if this is set to 1 then a connection is made to the database without checking that the tables exist.  
 
$nocheckdb - if this is set to 1 then a connection is made to the database without checking that the tables exist.  
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_request -->==get_request==
 
<!-- Pod2Wiki=item_get_request -->==get_request==
Line 31: Line 45:
  
 
Return the Apache request object (from mod_perl) or undefined if  this isn't a CGI script.
 
Return the Apache request object (from mod_perl) or undefined if  this isn't a CGI script.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_query -->==get_query==
 
<!-- Pod2Wiki=item_get_query -->==get_query==
Line 37: Line 52:
  
 
Return the CGI.pm object describing the current HTTP query, or  undefined if this isn't a CGI script.
 
Return the CGI.pm object describing the current HTTP query, or  undefined if this isn't a CGI script.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_terminate -->==terminate==
 
<!-- Pod2Wiki=item_terminate -->==terminate==
Line 43: Line 59:
  
 
Perform any cleaning up necessary, for example SQL cache tables which are no longer needed.
 
Perform any cleaning up necessary, for example SQL cache tables which are no longer needed.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_language_related_methods -->==Language Related Methods==
 
<!-- Pod2Wiki=head_language_related_methods -->==Language Related Methods==
Line 51: Line 68:
  
 
Given an repository object and a Apache (mod_perl) request object, this method decides what language the session should be.
 
Given an repository object and a Apache (mod_perl) request object, this method decides what language the session should be.
 +
 
First it looks at the HTTP cookie "eprints_lang", failing that it looks at the prefered language of the request from the HTTP header, failing that it looks at the default language for the repository.
 
First it looks at the HTTP cookie "eprints_lang", failing that it looks at the prefered language of the request from the HTTP header, failing that it looks at the default language for the repository.
 +
 
The language ID it returns is the highest on the list that the given eprint repository actually supports.
 
The language ID it returns is the highest on the list that the given eprint repository actually supports.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_change_lang -->===change_lang===
 
<!-- Pod2Wiki=item_change_lang -->===change_lang===
Line 59: Line 79:
  
 
Change the current language of the session. $newlangid should be a valid country code for the current repository.
 
Change the current language of the session. $newlangid should be a valid country code for the current repository.
 +
 
An invalid code will cause eprints to terminate with an error.
 
An invalid code will cause eprints to terminate with an error.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_html_phrase -->===html_phrase===
 
<!-- Pod2Wiki=item_html_phrase -->===html_phrase===
Line 66: Line 88:
  
 
Return an XHTML DOM object describing a phrase from the phrase files.
 
Return an XHTML DOM object describing a phrase from the phrase files.
 +
 
$phraseid is the id of the phrase to return. If the same ID appears in both the repository-specific phrases file and the system phrases file then the repository-specific one is used.
 
$phraseid is the id of the phrase to return. If the same ID appears in both the repository-specific phrases file and the system phrases file then the repository-specific one is used.
 +
 
If the phrase contains &lt;ep:pin&gt; elements, then each one should have an entry in %inserts where the key is the "ref" of the pin and the value is an XHTML DOM object describing what the pin should be  replaced with.
 
If the phrase contains &lt;ep:pin&gt; elements, then each one should have an entry in %inserts where the key is the "ref" of the pin and the value is an XHTML DOM object describing what the pin should be  replaced with.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_phrase -->===phrase===
 
<!-- Pod2Wiki=item_phrase -->===phrase===
Line 74: Line 99:
  
 
Performs the same function as html_phrase, but returns plain text.
 
Performs the same function as html_phrase, but returns plain text.
 +
 
All HTML elements will be removed, &lt;br&gt; and &lt;p&gt; will be converted  into breaks in the text. &lt;img&gt; tags will be replaced with their  "alt" values.
 
All HTML elements will be removed, &lt;br&gt; and &lt;p&gt; will be converted  into breaks in the text. &lt;img&gt; tags will be replaced with their  "alt" values.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_lang -->===get_lang===
 
<!-- Pod2Wiki=item_get_lang -->===get_lang===
Line 81: Line 108:
  
 
Return the EPrints::Language object for this sessions current  language.
 
Return the EPrints::Language object for this sessions current  language.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_langid -->===get_langid===
 
<!-- Pod2Wiki=item_get_langid -->===get_langid===
Line 87: Line 115:
  
 
Return the ID code of the current language of this session.
 
Return the ID code of the current language of this session.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_best_language -->===best_language===
 
<!-- Pod2Wiki=item_best_language -->===best_language===
Line 93: Line 122:
  
 
$repository is the current repository. $lang is the prefered language.
 
$repository is the current repository. $lang is the prefered language.
 +
 
%values contains keys which are language ids, and values which is text or phrases in those languages, all translations of the same  thing.
 
%values contains keys which are language ids, and values which is text or phrases in those languages, all translations of the same  thing.
 +
 
This function returns one of the values from %values based on the  following logic:
 
This function returns one of the values from %values based on the  following logic:
 +
 
If possible, return the value for $lang.
 
If possible, return the value for $lang.
 +
 
Otherwise, if possible return the value for the default language of this repository.
 
Otherwise, if possible return the value for the default language of this repository.
 +
 
Otherwise, if possible return the value for "en" (English).
 
Otherwise, if possible return the value for "en" (English).
 +
 
Otherwise just return any one value.
 
Otherwise just return any one value.
 +
 
This means that the view sees the best possible phrase.  
 
This means that the view sees the best possible phrase.  
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_view_name -->===get_view_name===
 
<!-- Pod2Wiki=item_get_view_name -->===get_view_name===
Line 106: Line 143:
  
 
Return a UTF8 encoded string containing the human readable name of the /view/ section with the ID $viewid.
 
Return a UTF8 encoded string containing the human readable name of the /view/ section with the ID $viewid.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_accessor_methods -->==Accessor Methods==
 
<!-- Pod2Wiki=head_accessor_methods -->==Accessor Methods==
Line 114: Line 152:
  
 
Return the current EPrints::Database connection object.
 
Return the current EPrints::Database connection object.
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_storage -->===get_storage===
 
  
  $store = $session-&gt;get_storage
 
 
Return the storage control object.
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_repository -->===get_repository===
 
<!-- Pod2Wiki=item_get_repository -->===get_repository===
Line 126: Line 159:
  
 
Return the EPrints::Repository object associated with the Session.
 
Return the EPrints::Repository object associated with the Session.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_url -->===get_url===
 
<!-- Pod2Wiki=item_get_url -->===get_url===
Line 132: Line 166:
  
 
Utility method to get various URLs. See [[API:EPrints/URL|EPrints::URL]]. With no arguments returns the same as get_uri().
 
Utility method to get various URLs. See [[API:EPrints/URL|EPrints::URL]]. With no arguments returns the same as get_uri().
 +
 
   # Return the current static path
 
   # Return the current static path
 
   $session-&gt;get_url( path =&gt; "static" );
 
   $session-&gt;get_url( path =&gt; "static" );
 +
 
 
   # Return the current cgi path
 
   # Return the current cgi path
 
   $session-&gt;get_url( path =&gt; "cgi" );
 
   $session-&gt;get_url( path =&gt; "cgi" );
 +
 
 
   # Return a full URL to the current cgi path
 
   # Return a full URL to the current cgi path
 
   $session-&gt;get_url( host =&gt; 1, path =&gt; "cgi" );
 
   $session-&gt;get_url( host =&gt; 1, path =&gt; "cgi" );
 +
 
 
   # Return a full URL to the static path under HTTP
 
   # Return a full URL to the static path under HTTP
 
   $session-&gt;get_url( scheme =&gt; "http", host =&gt; 1, path =&gt; "static" );
 
   $session-&gt;get_url( scheme =&gt; "http", host =&gt; 1, path =&gt; "static" );
 +
 
 
   # Return a full URL to the image 'foo.png'
 
   # Return a full URL to the image 'foo.png'
 
   $session-&gt;get_url( host =&gt; 1, path =&gt; "images", "foo.png" );
 
   $session-&gt;get_url( host =&gt; 1, path =&gt; "images", "foo.png" );
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_uri -->===get_uri===
 
<!-- Pod2Wiki=item_get_uri -->===get_uri===
Line 148: Line 188:
  
 
Returns the URL of the current script. Or "undef".
 
Returns the URL of the current script. Or "undef".
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_full_url -->===get_full_url===
 
<!-- Pod2Wiki=item_get_full_url -->===get_full_url===
Line 154: Line 195:
  
 
Returns the URL of the current script plus the CGI params.
 
Returns the URL of the current script plus the CGI params.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_noise -->===get_noise===
 
<!-- Pod2Wiki=item_get_noise -->===get_noise===
Line 160: Line 202:
  
 
Return the noise level for the current session. See the explaination under EPrints::Session-&gt;new()
 
Return the noise level for the current session. See the explaination under EPrints::Session-&gt;new()
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_online -->===get_online===
 
<!-- Pod2Wiki=item_get_online -->===get_online===
Line 166: Line 209:
  
 
Return true if this script is running via CGI, return false if we're on the command line.
 
Return true if this script is running via CGI, return false if we're on the command line.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_secure -->===get_secure===
 
<!-- Pod2Wiki=item_get_secure -->===get_secure===
Line 172: Line 216:
  
 
Returns true if we're using HTTPS/SSL (checks get_online first).
 
Returns true if we're using HTTPS/SSL (checks get_online first).
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_dom_related_methods -->==DOM Related Methods==
 
<!-- Pod2Wiki=head_dom_related_methods -->==DOM Related Methods==
 
These methods help build XML. Usually, but not always XHTML.
 
These methods help build XML. Usually, but not always XHTML.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_make_element -->===make_element===
 
<!-- Pod2Wiki=item_make_element -->===make_element===
Line 181: Line 227:
  
 
Return a DOM element with name ename and the specified attributes.
 
Return a DOM element with name ename and the specified attributes.
 +
 
eg. $session-&gt;make_element( "img", src =&gt; "/foo.gif", alt =&gt; "my pic" )
 
eg. $session-&gt;make_element( "img", src =&gt; "/foo.gif", alt =&gt; "my pic" )
 +
 
Will return the DOM object describing:
 
Will return the DOM object describing:
 +
 
&lt;img src="/foo.gif" alt="my pic" /&gt;
 
&lt;img src="/foo.gif" alt="my pic" /&gt;
 +
 
Note that in the call we use "=&gt;" not "=".
 
Note that in the call we use "=&gt;" not "=".
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_make_indent -->===make_indent===
 
<!-- Pod2Wiki=item_make_indent -->===make_indent===
Line 191: Line 242:
  
 
Return a DOM object describing a C.R. and then $width spaces. This is used to make nice looking XML for things like the OAI interface.
 
Return a DOM object describing a C.R. and then $width spaces. This is used to make nice looking XML for things like the OAI interface.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_make_comment -->===make_comment===
 
<!-- Pod2Wiki=item_make_comment -->===make_comment===
Line 197: Line 249:
  
 
Return a DOM object describing a comment containing $text.
 
Return a DOM object describing a comment containing $text.
 +
 
eg.
 
eg.
 +
 
&lt;!-- this is a comment --&gt;
 
&lt;!-- this is a comment --&gt;
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_make_text -->===make_text===
 
<!-- Pod2Wiki=item_make_text -->===make_text===
Line 205: Line 260:
  
 
Return a DOM object containing the given text. $text should be UTF-8 encoded.
 
Return a DOM object containing the given text. $text should be UTF-8 encoded.
 +
 
Characters will be treated as _text_ including &lt; &gt; etc.
 
Characters will be treated as _text_ including &lt; &gt; etc.
 +
 
eg.
 
eg.
 +
 
$session-&gt;make_text( "This is &lt;b&gt; an example" );
 
$session-&gt;make_text( "This is &lt;b&gt; an example" );
 +
 
Would return a DOM object representing the XML:
 
Would return a DOM object representing the XML:
 +
 
"This is &amp;lt;b&amp;gt; an example"
 
"This is &amp;lt;b&amp;gt; an example"
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_make_javascript -->===make_javascript===
 
<!-- Pod2Wiki=item_make_javascript -->===make_javascript===
Line 216: Line 277:
  
 
Return a new DOM "script" element containing $code in javascript. %attribs will be added to the script element, similar to make_element().
 
Return a new DOM "script" element containing $code in javascript. %attribs will be added to the script element, similar to make_element().
 +
 
E.g.
 
E.g.
 +
 
   &lt;script type="text/javascript"&gt;
 
   &lt;script type="text/javascript"&gt;
 
   // &lt;![CDATA[
 
   // &lt;![CDATA[
Line 222: Line 285:
 
   // ]]&gt;
 
   // ]]&gt;
 
   &lt;/script&gt;
 
   &lt;/script&gt;
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_make_doc_fragment -->===make_doc_fragment===
 
<!-- Pod2Wiki=item_make_doc_fragment -->===make_doc_fragment===
Line 228: Line 292:
  
 
Return a new XML document fragment. This is an item which can have XML elements added to it, but does not actually get rendered itself.
 
Return a new XML document fragment. This is an item which can have XML elements added to it, but does not actually get rendered itself.
 +
 
If appended to an element then it disappears and its children join the element at that point.
 
If appended to an element then it disappears and its children join the element at that point.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_xhtml_related_methods -->==XHTML Related Methods==
 
<!-- Pod2Wiki=head_xhtml_related_methods -->==XHTML Related Methods==
 
These methods help build XHTML.
 
These methods help build XHTML.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_ruler -->===render_ruler===
 
<!-- Pod2Wiki=item_render_ruler -->===render_ruler===
Line 238: Line 305:
  
 
Return an HR. in ruler.xml
 
Return an HR. in ruler.xml
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_nbsp -->===render_nbsp===
 
<!-- Pod2Wiki=item_render_nbsp -->===render_nbsp===
Line 244: Line 312:
  
 
Return an XHTML &amp;nbsp; character.
 
Return an XHTML &amp;nbsp; character.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_data_element -->===render_data_element===
 
<!-- Pod2Wiki=item_render_data_element -->===render_data_element===
Line 250: Line 319:
  
 
This is used to help render neat XML data. It returns a fragment  containing an element of name $elementname containing the value $value, the element is indented by $indent spaces.
 
This is used to help render neat XML data. It returns a fragment  containing an element of name $elementname containing the value $value, the element is indented by $indent spaces.
 +
 
The %opts describe any extra attributes for the element
 
The %opts describe any extra attributes for the element
 +
 
eg. $session-&gt;render_data_element( 4, "foo", "bar", class=&gt;"fred" )
 
eg. $session-&gt;render_data_element( 4, "foo", "bar", class=&gt;"fred" )
 +
 
would return a XML DOM object describing:
 
would return a XML DOM object describing:
 
     &lt;foo class="fred"&gt;bar&lt;/foo&gt;
 
     &lt;foo class="fred"&gt;bar&lt;/foo&gt;
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_link -->===render_link===
 
<!-- Pod2Wiki=item_render_link -->===render_link===
Line 260: Line 333:
  
 
Returns an HTML link to the given uri, with the optional $target if it needs to point to a different frame or window.
 
Returns an HTML link to the given uri, with the optional $target if it needs to point to a different frame or window.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_row -->===render_row===
 
<!-- Pod2Wiki=item_render_row -->===render_row===
Line 266: Line 340:
  
 
Return the key and values in a DOM encoded HTML table row. eg.
 
Return the key and values in a DOM encoded HTML table row. eg.
 +
 
  &lt;tr&gt;&lt;th&gt;$key:&lt;/th&gt;&lt;td&gt;$value[0]&lt;/td&gt;&lt;td&gt;...&lt;/td&gt;&lt;/tr&gt;
 
  &lt;tr&gt;&lt;th&gt;$key:&lt;/th&gt;&lt;td&gt;$value[0]&lt;/td&gt;&lt;td&gt;...&lt;/td&gt;&lt;/tr&gt;
 +
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_language_name -->===render_language_name===
 
<!-- Pod2Wiki=item_render_language_name -->===render_language_name===
Line 278: Line 354:
  
 
Return a DOM object containing the description of the specified type in the type set. eg. "eprint", "article"
 
Return a DOM object containing the description of the specified type in the type set. eg. "eprint", "article"
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_type_name -->===get_type_name===
 
<!-- Pod2Wiki=item_get_type_name -->===get_type_name===
Line 284: Line 361:
  
 
As above, but return a utf-8 string. Used in &lt;option&gt; elements, for example.
 
As above, but return a utf-8 string. Used in &lt;option&gt; elements, for example.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_name -->===render_name===
 
<!-- Pod2Wiki=item_render_name -->===render_name===
Line 290: Line 368:
  
 
$name is a ref. to a hash containing family, given etc.
 
$name is a ref. to a hash containing family, given etc.
 +
 
Returns an XML DOM fragment with the name rendered in the manner of the repository. Usually "John Smith".
 
Returns an XML DOM fragment with the name rendered in the manner of the repository. Usually "John Smith".
 +
 
If $familylast is set then the family and given parts are reversed, eg. "Smith, John"
 
If $familylast is set then the family and given parts are reversed, eg. "Smith, John"
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_option_list -->===render_option_list===
 
<!-- Pod2Wiki=item_render_option_list -->===render_option_list===
Line 298: Line 379:
  
 
This method renders an XHTML &lt;select&gt;. The options are complicated and may change, so it's better not to use it.
 
This method renders an XHTML &lt;select&gt;. The options are complicated and may change, so it's better not to use it.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_single_option -->===render_single_option===
 
<!-- Pod2Wiki=item_render_single_option -->===render_single_option===
Line 304: Line 386:
  
 
Used by render_option_list.
 
Used by render_option_list.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_hidden_field -->===render_hidden_field===
 
<!-- Pod2Wiki=item_render_hidden_field -->===render_hidden_field===
Line 310: Line 393:
  
 
Return the XHTML DOM describing an &lt;input&gt; element of type "hidden" and name and value as specified. eg.
 
Return the XHTML DOM describing an &lt;input&gt; element of type "hidden" and name and value as specified. eg.
 +
 
&lt;input type="hidden" name="foo" value="bar" /&gt;
 
&lt;input type="hidden" name="foo" value="bar" /&gt;
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_upload_field -->===render_upload_field===
 
<!-- Pod2Wiki=item_render_upload_field -->===render_upload_field===
Line 317: Line 402:
  
 
Render into XHTML DOM a file upload form button with the given name.  
 
Render into XHTML DOM a file upload form button with the given name.  
 +
 
eg. &lt;input type="file" name="foo" /&gt;
 
eg. &lt;input type="file" name="foo" /&gt;
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_action_buttons -->===render_action_buttons===
 
<!-- Pod2Wiki=item_render_action_buttons -->===render_action_buttons===
Line 324: Line 411:
  
 
Returns a DOM object describing the set of buttons.
 
Returns a DOM object describing the set of buttons.
 +
 
The keys of %buttons are the ids of the action that button will cause, the values are UTF-8 text that should appear on the button.
 
The keys of %buttons are the ids of the action that button will cause, the values are UTF-8 text that should appear on the button.
 +
 
Two optional additional keys may be used:
 
Two optional additional keys may be used:
 +
 
_order =&gt; [ "action1", "action2" ]
 
_order =&gt; [ "action1", "action2" ]
 +
 
will force the buttons to appear in a set order.
 
will force the buttons to appear in a set order.
 +
 
_class =&gt; "my_css_class"  
 
_class =&gt; "my_css_class"  
 +
 
will add a class attribute to the &lt;div&gt; containing the buttons to  allow additional styling.
 
will add a class attribute to the &lt;div&gt; containing the buttons to  allow additional styling.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_internal_buttons -->===render_internal_buttons===
 
<!-- Pod2Wiki=item_render_internal_buttons -->===render_internal_buttons===
Line 336: Line 430:
  
 
As for render_action_buttons, but creates buttons for actions which will modify the state of the current form, not continue with whatever process the form is part of.
 
As for render_action_buttons, but creates buttons for actions which will modify the state of the current form, not continue with whatever process the form is part of.
 +
 
eg. the "More Spaces" button and the up and down arrows on multiple type fields.
 
eg. the "More Spaces" button and the up and down arrows on multiple type fields.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_form -->===render_form===
 
<!-- Pod2Wiki=item_render_form -->===render_form===
Line 343: Line 439:
  
 
Return a DOM object describing an HTML form element.  
 
Return a DOM object describing an HTML form element.  
 +
 
$method should be "get" or "post"
 
$method should be "get" or "post"
 +
 
$dest is the target of the form. By default the current page.
 
$dest is the target of the form. By default the current page.
 +
 
eg.
 
eg.
 +
 
$session-&gt;render_form( "GET", "http://example.com/cgi/foo" );
 
$session-&gt;render_form( "GET", "http://example.com/cgi/foo" );
 +
 
returns a DOM object representing:
 
returns a DOM object representing:
 +
 
&lt;form method="get" action="http://example.com/cgi/foo" accept-charset="utf-8" /&gt;
 
&lt;form method="get" action="http://example.com/cgi/foo" accept-charset="utf-8" /&gt;
 +
 
If $method is "post" then an addition attribute is set: enctype="multipart/form-data"  
 
If $method is "post" then an addition attribute is set: enctype="multipart/form-data"  
 +
 
This just controls how the data is passed from the browser to the CGI library. You don't need to worry about it.
 
This just controls how the data is passed from the browser to the CGI library. You don't need to worry about it.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_subjects -->===render_subjects===
 
<!-- Pod2Wiki=item_render_subjects -->===render_subjects===
Line 357: Line 462:
  
 
Return as XHTML DOM a nested set of &lt;ul&gt; and &lt;li&gt; tags describing part of a subject tree.
 
Return as XHTML DOM a nested set of &lt;ul&gt; and &lt;li&gt; tags describing part of a subject tree.
 +
 
$subject_list is a array ref of subject ids to render.
 
$subject_list is a array ref of subject ids to render.
 +
 
$baseid is top top level node to render the tree from. If only a single subject is in subject_list, all subjects up to $baseid will still be rendered. Default is the ROOT element.
 
$baseid is top top level node to render the tree from. If only a single subject is in subject_list, all subjects up to $baseid will still be rendered. Default is the ROOT element.
 +
 
If $currentid is set then the subject with that ID is rendered in &lt;strong&gt;
 
If $currentid is set then the subject with that ID is rendered in &lt;strong&gt;
 +
 
$linkmode can 0, 1, 2 or 3.
 
$linkmode can 0, 1, 2 or 3.
 +
 
0. Don't link the subjects.
 
0. Don't link the subjects.
 +
 
1. Links subjects to the URL which edits them in edit_subjects.
 
1. Links subjects to the URL which edits them in edit_subjects.
 +
 
2. Links subjects to "subjectid.html" (where subjectid is the id of  the subject)
 
2. Links subjects to "subjectid.html" (where subjectid is the id of  the subject)
 +
 
3. Links the subjects to "subjectid/".  $sizes must be set. Only  subjects with a size of more than one are linked.
 
3. Links the subjects to "subjectid/".  $sizes must be set. Only  subjects with a size of more than one are linked.
 +
 
4. Links the subjects to "../subjectid/".  $sizes must be set. Only  subjects with a size of more than one are linked.
 
4. Links the subjects to "../subjectid/".  $sizes must be set. Only  subjects with a size of more than one are linked.
 +
 
$sizes may be a ref. to hash mapping the subjectid's to the number of items in that subject which will be rendered in brackets next to each subject.
 
$sizes may be a ref. to hash mapping the subjectid's to the number of items in that subject which will be rendered in brackets next to each subject.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_error -->===render_error===
 
<!-- Pod2Wiki=item_render_error -->===render_error===
Line 373: Line 489:
  
 
Renders an error page with the given error text. A link, with the text $back_to_text, is offered, the destination of this is $back_to, which should take the user somewhere sensible.
 
Renders an error page with the given error text. A link, with the text $back_to_text, is offered, the destination of this is $back_to, which should take the user somewhere sensible.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_render_input_form -->===render_input_form===
 
<!-- Pod2Wiki=item_render_input_form -->===render_input_form===
Line 379: Line 496:
  
 
Return a DOM object representing an entire input form.
 
Return a DOM object representing an entire input form.
 +
 
%params contains the following options:
 
%params contains the following options:
 +
 
dataset: The EPrints::Dataset to which the form relates, if any.
 
dataset: The EPrints::Dataset to which the form relates, if any.
 +
 
fields: a reference to an array of EPrint::MetaField objects, which describe the fields to be added to the form.
 
fields: a reference to an array of EPrint::MetaField objects, which describe the fields to be added to the form.
 +
 
values: a set of default values. A reference to a hash where the keys are ID's of fields, and the values are the default values for those fields.
 
values: a set of default values. A reference to a hash where the keys are ID's of fields, and the values are the default values for those fields.
 +
 
show_help: if true, show the fieldhelp phrase for each input  field.
 
show_help: if true, show the fieldhelp phrase for each input  field.
 +
 
show_name: if true, show the fieldname phrase for each input  field.
 
show_name: if true, show the fieldname phrase for each input  field.
 +
 
buttons: a description of the buttons to appear at the bottom of the form. See render_action_buttons for details.
 
buttons: a description of the buttons to appear at the bottom of the form. See render_action_buttons for details.
 +
 
top_buttons: a description of the buttons to appear at the top of the form (optional).
 
top_buttons: a description of the buttons to appear at the top of the form (optional).
 +
 
default_action: the id of the action to be performed by default,  ie. if the user pushes "return" in a text field.
 
default_action: the id of the action to be performed by default,  ie. if the user pushes "return" in a text field.
 +
 
dest: The URL of the target for this form. If not defined then the current URI is used.
 
dest: The URL of the target for this form. If not defined then the current URI is used.
 +
 
type: if this form relates to a user or an eprint, the type of eprint/user can effect what fields are flagged as required. This param contains the ID of the eprint/user if any, and if relevant.
 
type: if this form relates to a user or an eprint, the type of eprint/user can effect what fields are flagged as required. This param contains the ID of the eprint/user if any, and if relevant.
 +
 
staff: if true, this form is being presented to repository staff  (admin, or editor). This may change which fields are required.
 
staff: if true, this form is being presented to repository staff  (admin, or editor). This may change which fields are required.
 +
 
hidden_fields: reference to a hash. The keys of which are CGI keys and the values are the values they are set to. This causes hidden form elements to be set, so additional information can be passed.
 
hidden_fields: reference to a hash. The keys of which are CGI keys and the values are the values they are set to. This causes hidden form elements to be set, so additional information can be passed.
 +
 
object: The DataObj which this form is editing, if any.
 
object: The DataObj which this form is editing, if any.
 +
 
comment: not yet used.
 
comment: not yet used.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_methods_relating_to_the_current_xhtml_page -->==Methods relating to the current XHTML page==
 
<!-- Pod2Wiki=head_methods_relating_to_the_current_xhtml_page -->==Methods relating to the current XHTML page==
Line 402: Line 535:
  
 
Write an .html file plus a set of files describing the parts of the page for use with the dynamic template option.
 
Write an .html file plus a set of files describing the parts of the page for use with the dynamic template option.
 +
 
File base is the name of the page without the .html suffix.
 
File base is the name of the page without the .html suffix.
 +
 
parts is a reference to a hash containing DOM trees.
 
parts is a reference to a hash containing DOM trees.
 +
 
If $wrote_files is defined then any filenames written are logged in it as keys.
 
If $wrote_files is defined then any filenames written are logged in it as keys.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_prepare_page -->===prepare_page===
 
<!-- Pod2Wiki=item_prepare_page -->===prepare_page===
Line 411: Line 548:
  
 
Create an XHTML page for this session.  
 
Create an XHTML page for this session.  
 +
 
$parts is a hash of XHTML elements to insert into the pins in the template. Usually: title, page. Maybe pagetop and head.
 
$parts is a hash of XHTML elements to insert into the pins in the template. Usually: title, page. Maybe pagetop and head.
 +
 
If template is set then an alternate template file is used.
 
If template is set then an alternate template file is used.
 +
 
This function only builds the page it does not output it any way, see the methods below for that.
 
This function only builds the page it does not output it any way, see the methods below for that.
 +
 
Options include:
 
Options include:
 +
 
page_id=&gt;"id to put in body tag" template=&gt;"The template to use instead of default."
 
page_id=&gt;"id to put in body tag" template=&gt;"The template to use instead of default."
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_send_page -->===send_page===
 
<!-- Pod2Wiki=item_send_page -->===send_page===
Line 422: Line 565:
  
 
Send a web page out by HTTP. Only relevant if this is a CGI script. build_page must have been called first.
 
Send a web page out by HTTP. Only relevant if this is a CGI script. build_page must have been called first.
 +
 
See send_http_header for an explanation of %httpopts
 
See send_http_header for an explanation of %httpopts
 +
 
Dispose of the XML once it's sent out.
 
Dispose of the XML once it's sent out.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_page_to_file -->===page_to_file===
 
<!-- Pod2Wiki=item_page_to_file -->===page_to_file===
Line 430: Line 576:
  
 
Write out the current webpage to the given filename.
 
Write out the current webpage to the given filename.
 +
 
build_page must have been called first.
 
build_page must have been called first.
 +
 
Dispose of the XML once it's sent out.
 
Dispose of the XML once it's sent out.
 +
 
If $wrote_files is set then keys are created in it for each file created.
 
If $wrote_files is set then keys are created in it for each file created.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_set_page -->===set_page===
 
<!-- Pod2Wiki=item_set_page -->===set_page===
Line 439: Line 589:
  
 
Erase the current page for this session, if any, and replace it with the XML DOM structure described by $newhtml.
 
Erase the current page for this session, if any, and replace it with the XML DOM structure described by $newhtml.
 +
 
This page is what is output by page_to_file or send_page.
 
This page is what is output by page_to_file or send_page.
 +
 
$newhtml is a normal DOM Element, not a document object.
 
$newhtml is a normal DOM Element, not a document object.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_clone_for_me -->===clone_for_me===
 
<!-- Pod2Wiki=item_clone_for_me -->===clone_for_me===
Line 447: Line 600:
  
 
XML DOM items can only be added to the document which they belong to.
 
XML DOM items can only be added to the document which they belong to.
 +
 
A EPrints::Session has it's own XML DOM DOcument.  
 
A EPrints::Session has it's own XML DOM DOcument.  
 +
 
This method copies an XML node from _any_ document. The copy belongs to this sessions document.
 
This method copies an XML node from _any_ document. The copy belongs to this sessions document.
 +
 
If $deep is set then the children, (and their children etc.), are  copied too.
 
If $deep is set then the children, (and their children etc.), are  copied too.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_redirect -->===redirect===
 
<!-- Pod2Wiki=item_redirect -->===redirect===
Line 456: Line 613:
  
 
Redirects the browser to $url.
 
Redirects the browser to $url.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_not_found -->===not_found===
 
<!-- Pod2Wiki=item_not_found -->===not_found===
Line 462: Line 620:
  
 
Send a 404 Not Found header. If $message is undef sets message to 'Not Found' but does '''NOT''' print an error message, otherwise defaults to the normal 404 Not Found type response.
 
Send a 404 Not Found header. If $message is undef sets message to 'Not Found' but does '''NOT''' print an error message, otherwise defaults to the normal 404 Not Found type response.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_send_http_header -->===send_http_header===
 
<!-- Pod2Wiki=item_send_http_header -->===send_http_header===
Line 468: Line 627:
  
 
Send the HTTP header. Only makes sense if this is running as a CGI  script.
 
Send the HTTP header. Only makes sense if this is running as a CGI  script.
 +
 
Opts supported are:
 
Opts supported are:
 +
 
content_type. Default value is "text/html; charset=UTF-8". This sets the http content type header.
 
content_type. Default value is "text/html; charset=UTF-8". This sets the http content type header.
 +
 
lang. If this is set then a cookie setting the language preference is set in the http header.
 
lang. If this is set then a cookie setting the language preference is set in the http header.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_input_methods -->==Input Methods==
 
<!-- Pod2Wiki=head_input_methods -->==Input Methods==
 
These handle input from the user, browser and apache.
 
These handle input from the user, browser and apache.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_param -->===param===
 
<!-- Pod2Wiki=item_param -->===param===
Line 480: Line 644:
  
 
Passes through to CGI.pm param method.
 
Passes through to CGI.pm param method.
 +
 
$value = $session-&gt;param( $name ): returns the value of CGI parameter $name.
 
$value = $session-&gt;param( $name ): returns the value of CGI parameter $name.
 +
 
$value = $session-&gt;param( $name ): returns the value of CGI parameter $name.
 
$value = $session-&gt;param( $name ): returns the value of CGI parameter $name.
 +
 
@values = $session-&gt;param: returns an array of the names of all the CGI parameters in the current request.
 
@values = $session-&gt;param: returns an array of the names of all the CGI parameters in the current request.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_have_parameters -->===have_parameters===
 
<!-- Pod2Wiki=item_have_parameters -->===have_parameters===
Line 489: Line 657:
  
 
Return true if the current script had any parameters (post or get)
 
Return true if the current script had any parameters (post or get)
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_current_user -->===current_user===
 
<!-- Pod2Wiki=item_current_user -->===current_user===
Line 495: Line 664:
  
 
Return the current EPrints::DataObj::User for this session.
 
Return the current EPrints::DataObj::User for this session.
 +
 
Return undef if there isn't one.
 
Return undef if there isn't one.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_seen_form -->===seen_form===
 
<!-- Pod2Wiki=item_seen_form -->===seen_form===
Line 502: Line 673:
  
 
Return true if the current request contains the values from a form generated by EPrints.
 
Return true if the current request contains the values from a form generated by EPrints.
 +
 
This is identified by a hidden field placed into forms named _seen with value "true".
 
This is identified by a hidden field placed into forms named _seen with value "true".
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_internal_button_pressed -->===internal_button_pressed===
 
<!-- Pod2Wiki=item_internal_button_pressed -->===internal_button_pressed===
Line 509: Line 682:
  
 
Return true if a button has been pressed in a form which is intended to reload the current page with some change.
 
Return true if a button has been pressed in a form which is intended to reload the current page with some change.
 +
 
Examples include the "more spaces" button on multiple fields, the  "lookup" button on succeeds, etc.
 
Examples include the "more spaces" button on multiple fields, the  "lookup" button on succeeds, etc.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_action_button -->===get_action_button===
 
<!-- Pod2Wiki=item_get_action_button -->===get_action_button===
Line 516: Line 691:
  
 
Return the ID of the eprint action button which has been pressed in a form, if there was one. The name of the button is "_action_"  followed by the id.  
 
Return the ID of the eprint action button which has been pressed in a form, if there was one. The name of the button is "_action_"  followed by the id.  
 +
 
This also handles the .x and .y inserted in image submit.
 
This also handles the .x and .y inserted in image submit.
 +
 
This is designed to get back the name of an action button created by render_action_buttons.
 
This is designed to get back the name of an action button created by render_action_buttons.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_internal_button -->===get_internal_button===
 
<!-- Pod2Wiki=item_get_internal_button -->===get_internal_button===
Line 524: Line 702:
  
 
Return the id of the internal button which has been pushed, or  undef if one wasn't.
 
Return the id of the internal button which has been pushed, or  undef if one wasn't.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_client -->===client===
 
<!-- Pod2Wiki=item_client -->===client===
Line 530: Line 709:
  
 
Return a string representing the kind of browser that made the  current request.
 
Return a string representing the kind of browser that made the  current request.
 +
 
Options are GECKO, LYNX, MSIE4, MSIE5, MSIE6, ?.
 
Options are GECKO, LYNX, MSIE4, MSIE5, MSIE6, ?.
 +
 
GECKO covers mozilla and firefox.
 
GECKO covers mozilla and firefox.
 +
 
? is what's returned if none of the others were matched.
 
? is what's returned if none of the others were matched.
 +
 
These divisions are intended for modifying the way pages are rendered not logging what browser was used. Hence merging mozilla and firefox.
 
These divisions are intended for modifying the way pages are rendered not logging what browser was used. Hence merging mozilla and firefox.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_http_status -->===get_http_status===
 
<!-- Pod2Wiki=item_get_http_status -->===get_http_status===
Line 540: Line 724:
  
 
Return the status of the current HTTP request.
 
Return the status of the current HTTP request.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_methods_related_to_plugins -->==Methods related to Plugins==
 
<!-- Pod2Wiki=head_methods_related_to_plugins -->==Methods related to Plugins==
Line 548: Line 733:
  
 
Return the plugin with the given pluginid, in this repository or, failing that, from the system level plugins.
 
Return the plugin with the given pluginid, in this repository or, failing that, from the system level plugins.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_plugin_list -->===plugin_list===
 
<!-- Pod2Wiki=item_plugin_list -->===plugin_list===
Line 554: Line 740:
  
 
Return either a list of all the plugins available to this repository or return a list of available plugins which can accept the given  restrictions.
 
Return either a list of all the plugins available to this repository or return a list of available plugins which can accept the given  restrictions.
 +
 
Restictions:
 
Restictions:
 
  vary depending on the type of the plugin.
 
  vary depending on the type of the plugin.
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_get_plugins -->===get_plugins===
 
 
  @plugins = $session-&gt;get_plugins( [ $params, ] %restrictions )
 
  
Returns a list of plugin objects that conform to %restrictions (may be empty).
 
If $params is given uses that hash reference to initialise the plugins. Always passes this session to the plugin constructor method.
 
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_other_methods -->==Other Methods==
 
<!-- Pod2Wiki=head_other_methods -->==Other Methods==
Line 571: Line 752:
  
 
This function is currently buggy so just returns the time in seconds.
 
This function is currently buggy so just returns the time in seconds.
 +
 
Return the time of day in seconds, but to a precision of microseconds.
 
Return the time of day in seconds, but to a precision of microseconds.
 +
 
Accuracy depends on the operating system etc.
 
Accuracy depends on the operating system etc.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_mail_administrator -->===mail_administrator===
 
<!-- Pod2Wiki=item_mail_administrator -->===mail_administrator===
Line 579: Line 763:
  
 
Sends a mail to the repository administrator with the given subject and message body.
 
Sends a mail to the repository administrator with the given subject and message body.
 +
 
$subjectid is the name of a phrase in the phrase file to use for the subject.
 
$subjectid is the name of a phrase in the phrase file to use for the subject.
 +
 
$messageid is the name of a phrase in the phrase file to use as the basis for the mail body.
 
$messageid is the name of a phrase in the phrase file to use as the basis for the mail body.
 +
 
%inserts is a hash. The keys are the pins in the messageid phrase and the values the utf8 strings to replace the pins with.
 
%inserts is a hash. The keys are the pins in the messageid phrase and the values the utf8 strings to replace the pins with.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=item_destroy -->===destroy===
 
<!-- Pod2Wiki=item_destroy -->===destroy===
Line 588: Line 776:
  
 
Destructor. Don't call directly.
 
Destructor. Don't call directly.
 +
 
<!-- End of Pod2Wiki -->
 
<!-- End of Pod2Wiki -->
 
<!-- Pod2Wiki=head_undocumented_methods -->=UNDOCUMENTED METHODS=
 
<!-- Pod2Wiki=head_undocumented_methods -->=UNDOCUMENTED METHODS=

Revision as of 18:29, 11 August 2009

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

Contents

NAME

EPrints::Session - Single connection to the EPrints system

DESCRIPTION

This module is not really a session. The name is out of date, but hard to change.

EPrints::Session represents a connection to the EPrints system. It connects to a single EPrints repository, and the database used by that repository. Thus it has an associated EPrints::Database and EPrints::Repository object.

Each "session" has a "current language". If you are running in a multilingual mode, this is used by the HTML rendering functions to choose what language to return text in.

The "session" object also knows about the current apache connection, if there is one, including the CGI parameters.

If the connection requires a username and password then it can also give access to the EPrints::DataObj::User object representing the user who is causing this request.

The session object also provides many methods for creating XHTML results which can be returned via the web interface.

new

 $session = EPrints::Session->new( $mode, [$repository_id], [$noise], [$nocheckdb] )

Create a connection to an EPrints repository which provides access to the database and to the repository configuration.

This method can be called in two modes. Setting $mode to 0 means this is a connection via a CGI web page. $repository_id is ignored, instead the value is taken from the "PerlSetVar EPrints_ArchiveID" option in the apache configuration for the current directory.

If this is being called from a command line script, then $mode should be 1, and $repository_id should be the ID of the repository we want to connect to.

$mode : mode = 0 - We are online (CGI script) mode = 1 - We are offline (bin script) $repository_id is repository_id mode = 2 - We are online, but don't create a CGI query (so we

don't consume the data).

$noise is the level of debugging output. 0 - silent 1 - quietish 2 - noisy 3 - debug all SQL statements 4 - debug database connection

Under normal conditions use "0" for online and "1" for offline.

$nocheckdb - if this is set to 1 then a connection is made to the database without checking that the tables exist.

get_request

 $request = $session->get_request;

Return the Apache request object (from mod_perl) or undefined if this isn't a CGI script.

get_query

 $query = $session->get_query;

Return the CGI.pm object describing the current HTTP query, or undefined if this isn't a CGI script.

terminate

 $session->terminate

Perform any cleaning up necessary, for example SQL cache tables which are no longer needed.

Language Related Methods

get_session_language

 $langid = EPrints::Session::get_session_language( $repository, $request )

Given an repository object and a Apache (mod_perl) request object, this method decides what language the session should be.

First it looks at the HTTP cookie "eprints_lang", failing that it looks at the prefered language of the request from the HTTP header, failing that it looks at the default language for the repository.

The language ID it returns is the highest on the list that the given eprint repository actually supports.

change_lang

 $session->change_lang( $newlangid )

Change the current language of the session. $newlangid should be a valid country code for the current repository.

An invalid code will cause eprints to terminate with an error.

html_phrase

 $xhtml_phrase = $session->html_phrase( $phraseid, %inserts )

Return an XHTML DOM object describing a phrase from the phrase files.

$phraseid is the id of the phrase to return. If the same ID appears in both the repository-specific phrases file and the system phrases file then the repository-specific one is used.

If the phrase contains <ep:pin> elements, then each one should have an entry in %inserts where the key is the "ref" of the pin and the value is an XHTML DOM object describing what the pin should be replaced with.

phrase

 $utf8_text = $session->phrase( $phraseid, %inserts )

Performs the same function as html_phrase, but returns plain text.

All HTML elements will be removed, <br> and <p> will be converted into breaks in the text. <img> tags will be replaced with their "alt" values.

get_lang

 $language = $session->get_lang

Return the EPrints::Language object for this sessions current language.

get_langid

 $langid = $session->get_langid

Return the ID code of the current language of this session.

best_language

 $value = EPrints::Session::best_language( $repository, $lang, %values )

$repository is the current repository. $lang is the prefered language.

%values contains keys which are language ids, and values which is text or phrases in those languages, all translations of the same thing.

This function returns one of the values from %values based on the following logic:

If possible, return the value for $lang.

Otherwise, if possible return the value for the default language of this repository.

Otherwise, if possible return the value for "en" (English).

Otherwise just return any one value.

This means that the view sees the best possible phrase.

get_view_name

 $viewname = $session->get_view_name( $dataset, $viewid )

Return a UTF8 encoded string containing the human readable name of the /view/ section with the ID $viewid.

Accessor Methods

get_database

 $db = $session->get_database

Return the current EPrints::Database connection object.

get_repository

 $repository = $session->get_repository

Return the EPrints::Repository object associated with the Session.

get_url

 $url = $session->get_url( [ @OPTS ] [, $page] )

Utility method to get various URLs. See EPrints::URL. With no arguments returns the same as get_uri().

 # Return the current static path
 $session->get_url( path => "static" );
 
 # Return the current cgi path
 $session->get_url( path => "cgi" );
 
 # Return a full URL to the current cgi path
 $session->get_url( host => 1, path => "cgi" );
 
 # Return a full URL to the static path under HTTP
 $session->get_url( scheme => "http", host => 1, path => "static" );
 
 # Return a full URL to the image 'foo.png'
 $session->get_url( host => 1, path => "images", "foo.png" );
 

get_uri

 $uri = $session->get_uri

Returns the URL of the current script. Or "undef".

get_full_url

 $uri = $session->get_full_url

Returns the URL of the current script plus the CGI params.

get_noise

 $noise_level = $session->get_noise

Return the noise level for the current session. See the explaination under EPrints::Session->new()

get_online

 $boolean = $session->get_online

Return true if this script is running via CGI, return false if we're on the command line.

get_secure

 $secure = $session->get_secure

Returns true if we're using HTTPS/SSL (checks get_online first).

DOM Related Methods

These methods help build XML. Usually, but not always XHTML.

make_element

 $dom = $session->make_element( $element_name, %attribs )

Return a DOM element with name ename and the specified attributes.

eg. $session->make_element( "img", src => "/foo.gif", alt => "my pic" )

Will return the DOM object describing:

<img src="/foo.gif" alt="my pic" />

Note that in the call we use "=>" not "=".

make_indent

 $dom = $session->make_indent( $width )

Return a DOM object describing a C.R. and then $width spaces. This is used to make nice looking XML for things like the OAI interface.

make_comment

 $dom = $session->make_comment( $text )

Return a DOM object describing a comment containing $text.

eg.

<!-- this is a comment -->

make_text

 $DOM = $session->make_text( $text )

Return a DOM object containing the given text. $text should be UTF-8 encoded.

Characters will be treated as _text_ including < > etc.

eg.

$session->make_text( "This is <b> an example" );

Would return a DOM object representing the XML:

"This is &lt;b&gt; an example"

make_javascript

 $DOM = $session->make_javascript( $code, %attribs )

Return a new DOM "script" element containing $code in javascript. %attribs will be added to the script element, similar to make_element().

E.g.

 <script type="text/javascript">
 // <![CDATA[
 alert("Hello, World!");
 // ]]>
 </script>
 

make_doc_fragment

 $fragment = $session->make_doc_fragment

Return a new XML document fragment. This is an item which can have XML elements added to it, but does not actually get rendered itself.

If appended to an element then it disappears and its children join the element at that point.

XHTML Related Methods

These methods help build XHTML.

render_ruler

 $ruler = $session->render_ruler

Return an HR. in ruler.xml

render_nbsp

 $nbsp = $session->render_nbsp

Return an XHTML &nbsp; character.

render_data_element

 $xhtml = $session->render_data_element( $indent, $elementname, $value, [%opts] )

This is used to help render neat XML data. It returns a fragment containing an element of name $elementname containing the value $value, the element is indented by $indent spaces.

The %opts describe any extra attributes for the element

eg. $session->render_data_element( 4, "foo", "bar", class=>"fred" )

would return a XML DOM object describing:

   <foo class="fred">bar</foo>

render_link

 $xhtml = $session->render_link( $uri, [$target] )

Returns an HTML link to the given uri, with the optional $target if it needs to point to a different frame or window.

render_row

 $table_row = $session->render_row( $key, @values );

Return the key and values in a DOM encoded HTML table row. eg.

<tr><th>$key:</th><td>$value[0]</td><td>...</td></tr>
 

render_language_name

 $xhtml = $session->render_language_name( $langid ) Return a DOM object containing the description of the specified languagein the current default language, or failing that from languages.xml

render_type_name

 $xhtml = $session->render_type_name( $type_set, $type ) 

Return a DOM object containing the description of the specified type in the type set. eg. "eprint", "article"

get_type_name

 $string = $session->get_type_name( $type_set, $type ) 

As above, but return a utf-8 string. Used in <option> elements, for example.

render_name

 $xhtml_name = $session->render_name( $name, [$familylast] )

$name is a ref. to a hash containing family, given etc.

Returns an XML DOM fragment with the name rendered in the manner of the repository. Usually "John Smith".

If $familylast is set then the family and given parts are reversed, eg. "Smith, John"

render_option_list

 $xhtml_select = $session->render_option_list( %params )

This method renders an XHTML <select>. The options are complicated and may change, so it's better not to use it.

render_single_option

 $option = $session->render_single_option( $key, $desc, $selected )

Used by render_option_list.

render_hidden_field

 $xhtml_hidden = $session->render_hidden_field( $name, $value )

Return the XHTML DOM describing an <input> element of type "hidden" and name and value as specified. eg.

<input type="hidden" name="foo" value="bar" />

render_upload_field

 $xhtml_uploda = $session->render_upload_field( $name )

Render into XHTML DOM a file upload form button with the given name.

eg. <input type="file" name="foo" />

render_action_buttons

 $dom = $session->render_action_buttons( %buttons )

Returns a DOM object describing the set of buttons.

The keys of %buttons are the ids of the action that button will cause, the values are UTF-8 text that should appear on the button.

Two optional additional keys may be used:

_order => [ "action1", "action2" ]

will force the buttons to appear in a set order.

_class => "my_css_class"

will add a class attribute to the <div> containing the buttons to allow additional styling.

render_internal_buttons

 $dom = $session->render_internal_buttons( %buttons )

As for render_action_buttons, but creates buttons for actions which will modify the state of the current form, not continue with whatever process the form is part of.

eg. the "More Spaces" button and the up and down arrows on multiple type fields.

render_form

 $dom = $session->render_form( $method, $dest )

Return a DOM object describing an HTML form element.

$method should be "get" or "post"

$dest is the target of the form. By default the current page.

eg.

$session->render_form( "GET", "http://example.com/cgi/foo" );

returns a DOM object representing:

<form method="get" action="http://example.com/cgi/foo" accept-charset="utf-8" />

If $method is "post" then an addition attribute is set: enctype="multipart/form-data"

This just controls how the data is passed from the browser to the CGI library. You don't need to worry about it.

render_subjects

 $ul = $session->render_subjects( $subject_list, [$baseid], [$currentid], [$linkmode], [$sizes] )

Return as XHTML DOM a nested set of <ul> and <li> tags describing part of a subject tree.

$subject_list is a array ref of subject ids to render.

$baseid is top top level node to render the tree from. If only a single subject is in subject_list, all subjects up to $baseid will still be rendered. Default is the ROOT element.

If $currentid is set then the subject with that ID is rendered in <strong>

$linkmode can 0, 1, 2 or 3.

0. Don't link the subjects.

1. Links subjects to the URL which edits them in edit_subjects.

2. Links subjects to "subjectid.html" (where subjectid is the id of the subject)

3. Links the subjects to "subjectid/". $sizes must be set. Only subjects with a size of more than one are linked.

4. Links the subjects to "../subjectid/". $sizes must be set. Only subjects with a size of more than one are linked.

$sizes may be a ref. to hash mapping the subjectid's to the number of items in that subject which will be rendered in brackets next to each subject.

render_error

 $session->render_error( $error_text, $back_to, $back_to_text )

Renders an error page with the given error text. A link, with the text $back_to_text, is offered, the destination of this is $back_to, which should take the user somewhere sensible.

render_input_form

 $dom = $session->render_input_form( %params )

Return a DOM object representing an entire input form.

%params contains the following options:

dataset: The EPrints::Dataset to which the form relates, if any.

fields: a reference to an array of EPrint::MetaField objects, which describe the fields to be added to the form.

values: a set of default values. A reference to a hash where the keys are ID's of fields, and the values are the default values for those fields.

show_help: if true, show the fieldhelp phrase for each input field.

show_name: if true, show the fieldname phrase for each input field.

buttons: a description of the buttons to appear at the bottom of the form. See render_action_buttons for details.

top_buttons: a description of the buttons to appear at the top of the form (optional).

default_action: the id of the action to be performed by default, ie. if the user pushes "return" in a text field.

dest: The URL of the target for this form. If not defined then the current URI is used.

type: if this form relates to a user or an eprint, the type of eprint/user can effect what fields are flagged as required. This param contains the ID of the eprint/user if any, and if relevant.

staff: if true, this form is being presented to repository staff (admin, or editor). This may change which fields are required.

hidden_fields: reference to a hash. The keys of which are CGI keys and the values are the values they are set to. This causes hidden form elements to be set, so additional information can be passed.

object: The DataObj which this form is editing, if any.

comment: not yet used.

Methods relating to the current XHTML page

write_static_page

 $session->write_static_page( $filebase, $parts, [$page_id], [$wrote_files] )

Write an .html file plus a set of files describing the parts of the page for use with the dynamic template option.

File base is the name of the page without the .html suffix.

parts is a reference to a hash containing DOM trees.

If $wrote_files is defined then any filenames written are logged in it as keys.

prepare_page

 $session->prepare_page( $parts, %options )

Create an XHTML page for this session.

$parts is a hash of XHTML elements to insert into the pins in the template. Usually: title, page. Maybe pagetop and head.

If template is set then an alternate template file is used.

This function only builds the page it does not output it any way, see the methods below for that.

Options include:

page_id=>"id to put in body tag" template=>"The template to use instead of default."

send_page

 $session->send_page( %httpopts )

Send a web page out by HTTP. Only relevant if this is a CGI script. build_page must have been called first.

See send_http_header for an explanation of %httpopts

Dispose of the XML once it's sent out.

page_to_file

 $session->page_to_file( $filename, [$wrote_files] )

Write out the current webpage to the given filename.

build_page must have been called first.

Dispose of the XML once it's sent out.

If $wrote_files is set then keys are created in it for each file created.

set_page

 $session->set_page( $newhtml )

Erase the current page for this session, if any, and replace it with the XML DOM structure described by $newhtml.

This page is what is output by page_to_file or send_page.

$newhtml is a normal DOM Element, not a document object.

clone_for_me

 $copy_of_node = $session->clone_for_me( $node, [$deep] )

XML DOM items can only be added to the document which they belong to.

A EPrints::Session has it's own XML DOM DOcument.

This method copies an XML node from _any_ document. The copy belongs to this sessions document.

If $deep is set then the children, (and their children etc.), are copied too.

redirect

 $session->redirect( $url, [%opts] )

Redirects the browser to $url.

not_found

 $session->not_found( [ $message ] )

Send a 404 Not Found header. If $message is undef sets message to 'Not Found' but does NOT print an error message, otherwise defaults to the normal 404 Not Found type response.

send_http_header

 $session->send_http_header( %opts )

Send the HTTP header. Only makes sense if this is running as a CGI script.

Opts supported are:

content_type. Default value is "text/html; charset=UTF-8". This sets the http content type header.

lang. If this is set then a cookie setting the language preference is set in the http header.

Input Methods

These handle input from the user, browser and apache.

param

 $value or @values = $session->param( $name )

Passes through to CGI.pm param method.

$value = $session->param( $name ): returns the value of CGI parameter $name.

$value = $session->param( $name ): returns the value of CGI parameter $name.

@values = $session->param: returns an array of the names of all the CGI parameters in the current request.

have_parameters

 $bool = $session->have_parameters

Return true if the current script had any parameters (post or get)

current_user

 $user = $session->current_user

Return the current EPrints::DataObj::User for this session.

Return undef if there isn't one.

seen_form

 $boolean = $session->seen_form

Return true if the current request contains the values from a form generated by EPrints.

This is identified by a hidden field placed into forms named _seen with value "true".

internal_button_pressed

 $boolean = $session->internal_button_pressed( $buttonid )

Return true if a button has been pressed in a form which is intended to reload the current page with some change.

Examples include the "more spaces" button on multiple fields, the "lookup" button on succeeds, etc.

get_action_button

 $action_id = $session->get_action_button

Return the ID of the eprint action button which has been pressed in a form, if there was one. The name of the button is "_action_" followed by the id.

This also handles the .x and .y inserted in image submit.

This is designed to get back the name of an action button created by render_action_buttons.

get_internal_button

 $button_id = $session->get_internal_button

Return the id of the internal button which has been pushed, or undef if one wasn't.

client

 $client = $session->client

Return a string representing the kind of browser that made the current request.

Options are GECKO, LYNX, MSIE4, MSIE5, MSIE6, ?.

GECKO covers mozilla and firefox.

? is what's returned if none of the others were matched.

These divisions are intended for modifying the way pages are rendered not logging what browser was used. Hence merging mozilla and firefox.

get_http_status

 $status = $session->get_http_status

Return the status of the current HTTP request.

Methods related to Plugins

plugin

 $plugin = $session->plugin( $pluginid )

Return the plugin with the given pluginid, in this repository or, failing that, from the system level plugins.

plugin_list

 @plugin_ids  = $session->plugin_list( %restrictions )

Return either a list of all the plugins available to this repository or return a list of available plugins which can accept the given restrictions.

Restictions:

vary depending on the type of the plugin.

Other Methods

microtime

 $time = EPrints::Session::microtime();

This function is currently buggy so just returns the time in seconds.

Return the time of day in seconds, but to a precision of microseconds.

Accuracy depends on the operating system etc.

mail_administrator

 $foo = $session->mail_administrator( $subjectid, $messageid, %inserts )

Sends a mail to the repository administrator with the given subject and message body.

$subjectid is the name of a phrase in the phrase file to use for the subject.

$messageid is the name of a phrase in the phrase file to use as the basis for the mail body.

%inserts is a hash. The keys are the pins in the messageid phrase and the values the utf8 strings to replace the pins with.

destroy

 $session->DESTROY

Destructor. Don't call directly.

UNDOCUMENTED METHODS

Warning These methods were found in the source code but didn't have any POD associated with them. This may be because we haven't got around to documenting them yet or it could be because they are internal to the API and not intended for use by other parts of EPrints.

allow_anybody

build_page

cache_subjects

get_archive

get_citation_spec

get_citation_type

get_db

get_next_id

get_static_page_conf_file

login

logout

read_params

reload_current_user

render_button

render_input_field

render_message

render_noenter_input_field

render_row_with_help

render_tabs

render_toolbar

render_toolbox

set_cookies

valid_login