Difference between revisions of "API:EPrints/Plugin/Screen"

From EPrints Documentation
Jump to: navigation, search
Line 16: Line 16:
 
Screen plugins provide the CGI user interface to EPrints. Only "static" pages (summary pages, browse views) are not rendered via screens.
 
Screen plugins provide the CGI user interface to EPrints. Only "static" pages (summary pages, browse views) are not rendered via screens.
  
−
Screens generate elements of the page that are then rendered using the [[API:EPrints/Apache/Template|EPrints::Apache::Template]]. This includes the page title, header elements and page body.
+
Screens generate elements of the page that are then rendered using the [[API:EPrints/Apache/Template|EPrints::Apache::Template]]. These elements include the page title, header elements and page body. Screens can also '''export''' (depending on [[API:EPrints/Plugin/Screen#wishes_to_export|wishes_to_export]]) which allows complete control over the HTTP response.
  
 
Most screens have an interactive element that follow this pattern:
 
Most screens have an interactive element that follow this pattern:
Line 34: Line 34:
 
third request ... back to step 1.
 
third request ... back to step 1.
  
−
Given the server-client nature of Web pages a user interaction will occur over several requests. This can either be in two or three steps in a Screen, depending on whether server-side state is changed. Its important to note, especially for three-step, that any state information needed for the screen to render needs to be persisted in the form submission and the resulting redirect.
+
The exception to this is where [[API:EPrints/Plugin/Screen#redirect_to_me_url|redirect_to_me_url]] is sub-classed to return undef, in which case the screen is expected to render in addition to processing the form request.
 +
 
 +
The reason for using a redirect is that the user will end up on a page that can be reloaded without re-submitting the form. This is particularly important where submitting the action twice may result in an error, for example when deleting an object (can't delete twice!).
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_methods -->
 +
==METHODS==
 +
<!-- Pod2Wiki=head_properties_from -->
 +
===properties_from===
 +
 
 +
<source lang="perl">$screen->properties_from()
 +
 
 +
</source>
 +
Called by the [[API:EPrints/ScreenProcessor|EPrints::ScreenProcessor]] very early in the response process.
 +
 
 +
This method should be used to set up the response by, for example getting CGI query parameters and storing them in the processor object.
 +
 
 +
Because this method is called '''before''' [[API:EPrints/Plugin/Screen#can_be_viewed|can_be_viewed]] no changes to the system should be made here.
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_redirect_to_me_url -->
 +
===redirect_to_me_url===
 +
 
 +
<source lang="perl">$url = $screen->redirect_to_me_url()
 +
 
 +
</source>
 +
If the request is a POST the screen is given an opportunity to redirect the user, avoiding double-POSTs if the user reloads the resulting page.
  
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 40: Line 72:
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
−
<!-- Pod2Wiki=head_two_requests -->
+
<!-- Pod2Wiki=head_render -->
−
===Two Requests===
+
===render===
−
The screen renders a link or GET-method form. When the user follows the link or submits the form the screen renders something different but does not change the state of an object on the server. i.e. if the user were to reload the page they would receive the same response.
+
 
 +
<source lang="perl">$xhtml = $screen->render()
 +
 
 +
</source>
 +
Render the page body.
  
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 48: Line 84:
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
−
<!-- Pod2Wiki=head_three_requests -->
+
<!-- Pod2Wiki=head_render_links -->
−
===Three Requests===
+
===render_links===
−
The screen renders a POST-method form. When the user submits the form the screen makes a change to an object on the server and then returns a '''redirect''' back to the user. The browser requests the new location and the screen renders the new state.
 
  
−
The redirect turns the request from a POST into a GET, which implicitly allows the user to reload the page without causing the change to happen again. This is important where, for example a user might be deleting an object. Attempting to re-submit the form would result in an error.
+
<source lang="perl">$xhtml = $screen->render_links()
  
−
Some screens override this behaviour and instead will render in response to a POST request.
+
</source>
 +
Render any elements for the page &lt;head&gt; section.
  
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 60: Line 96:
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
−
<!-- Pod2Wiki=head_methods -->
 
−
==METHODS==
 
 
<!-- Pod2Wiki=head_hidden_bits -->
 
<!-- Pod2Wiki=head_hidden_bits -->
 
===hidden_bits===
 
===hidden_bits===
Line 71: Line 105:
  
 
At the top-level this is just the 'screen' id.
 
At the top-level this is just the 'screen' id.
 +
 +
Historically render_hidden_bits() - which built up a set of hidden inputs in XHTML - was used but this had the downside of not being usable with GET requests. Screen plugins now have a mix of approaches, so care is needed when sub-classing <code>hidden_bits</code>.
 +
 +
<!-- Edit below this comment -->
 +
 +
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_wishes_to_export -->
 +
===wishes_to_export===
 +
 +
<source lang="perl">$bool = $screen->wishes_to_export()
 +
 +
</source>
 +
If true, instead of calling the render* methods the export* methods will be used.
 +
 +
<!-- Edit below this comment -->
 +
 +
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_export -->
 +
===export===
 +
 +
<source lang="perl">$screen->export()
 +
 +
</source>
 +
Called when [[API:EPrints/Plugin/Screen#wishes_to_export|wishes_to_export]] is true.
 +
 +
This method should generate an HTTP response directly (e.g. by printing to STDOUT).
 +
 +
<!-- Edit below this comment -->
 +
 +
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_export_mimetype -->
 +
===export_mimetype===
 +
 +
<source lang="perl">$mime_type = $screen->export_mimetype()
 +
 +
</source>
 +
Return the MIME type of the HTTP response (as will be generated by [[API:EPrints/Plugin/Screen#export|export]]).
 +
 +
Default is to use "text/plain".
 +
 +
<!-- Edit below this comment -->
 +
 +
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_render_form -->
 +
===render_form===
 +
 +
<source lang="perl">$xhtml = $screen->render_form( [ METHOD [, ACTION ] ] )
 +
 +
</source>
 +
Render an XHTML form that will call this screen. If the METHOD is POST will apply cross-site request forgery protection.
 +
 +
Unless you have a good reason not to you should always use render_form() to add forms to your HTTP response, which ensures the correct context and request protections are in place.
  
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 85: Line 175:
  
 
If the CSRF check fails no action should be taken as this may be an attempt to forge a request.
 
If the CSRF check fails no action should be taken as this may be an attempt to forge a request.
 +
 +
<!-- Edit below this comment -->
 +
 +
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_render_title -->
 +
===render_title===
 +
 +
<source lang="perl">$xhtml = $screen->render_title
 +
 +
</source>
 +
Render the page title.
  
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->

Revision as of 16:17, 25 July 2013

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::Plugin::Screen - dynamic user interface web pages


DESCRIPTION

Screen plugins provide the CGI user interface to EPrints. Only "static" pages (summary pages, browse views) are not rendered via screens.

Screens generate elements of the page that are then rendered using the EPrints::Apache::Template. These elements include the page title, header elements and page body. Screens can also export (depending on wishes_to_export) which allows complete control over the HTTP response.

Most screens have an interactive element that follow this pattern:

first request ...

  • 1. can_be_viewed() grants access
  • 2. properties_from() sets up the response
  • 3. render() includes a form with an action

second request ...

  • 4. properties_from() sets up the response
  • 5. from() identifies the action
  • 6. allow_*() checks access to the specific action
  • 7. action_*() method performs the (probably) side-effecting action
  • 8. redirect_to_me_url() redirects the user back to ...

third request ... back to step 1.

The exception to this is where redirect_to_me_url is sub-classed to return undef, in which case the screen is expected to render in addition to processing the form request.

The reason for using a redirect is that the user will end up on a page that can be reloaded without re-submitting the form. This is particularly important where submitting the action twice may result in an error, for example when deleting an object (can't delete twice!).


METHODS

properties_from

$screen->properties_from()

Called by the EPrints::ScreenProcessor very early in the response process.

This method should be used to set up the response by, for example getting CGI query parameters and storing them in the processor object.

Because this method is called before can_be_viewed no changes to the system should be made here.


redirect_to_me_url

$url = $screen->redirect_to_me_url()

If the request is a POST the screen is given an opportunity to redirect the user, avoiding double-POSTs if the user reloads the resulting page.


render

$xhtml = $screen->render()

Render the page body.


render_links

$xhtml = $screen->render_links()

Render any elements for the page <head> section.


hidden_bits

@params = $screen->hidden_bits()

Returns a key-value list of values that must be set when referring to this screen.

At the top-level this is just the 'screen' id.

Historically render_hidden_bits() - which built up a set of hidden inputs in XHTML - was used but this had the downside of not being usable with GET requests. Screen plugins now have a mix of approaches, so care is needed when sub-classing hidden_bits.


wishes_to_export

$bool = $screen->wishes_to_export()

If true, instead of calling the render* methods the export* methods will be used.


export

$screen->export()

Called when wishes_to_export is true.

This method should generate an HTTP response directly (e.g. by printing to STDOUT).


export_mimetype

$mime_type = $screen->export_mimetype()

Return the MIME type of the HTTP response (as will be generated by export).

Default is to use "text/plain".


render_form

$xhtml = $screen->render_form( [ METHOD [, ACTION ] ] )

Render an XHTML form that will call this screen. If the METHOD is POST will apply cross-site request forgery protection.

Unless you have a good reason not to you should always use render_form() to add forms to your HTTP response, which ensures the correct context and request protections are in place.


verify_csrf

$ok = $screen->verify_csrf()

Verify that the CSRF token in the user agent's cookie matches the token passed in the form value.

If the CSRF check fails no action should be taken as this may be an attempt to forge a request.


render_title

$xhtml = $screen->render_title

Render the page title.


list_items

@screen_opts = $screen->list_items( $list_id, %opts )

Returns a list of screens that appear in list $list_id ordered by their position.

Each screen opt is a hash ref of: 

  screen - screen plugin
  screen_id - screen id
  position - position (positive integer)
  action - the action, if this plugin is for an action list

Incoming opts: 

  filter => 1 or 0 (default 1)
  params => {}


has_action

$ok = $screen->has_action( $action_id )

Returns true if this screen has an action $action_id.


action_icon_url

$url = $screen->action_icon_url( $action )

Returns the relative URL to the $action icon for this screen.


render_action_link

$frag = $screen->render_action_link()

Returns a link to this screen.


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



Retrieved from ‘https://wiki.eprints.org/w/index.php?title=API:EPrints/Plugin/Screen&oldid=10825’