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

From EPrints Documentation
Jump to: navigation, search
(Created page with '<!-- Pod2Wiki=_preamble_ This page has been automatically generated from the EPrints 3.2 source. Any wiki changes made between the 'Pod2Wiki=*' and 'Edit below this comment' com…')
 
Line 6: Line 6:
 
<!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name -->
 
<!-- Pod2Wiki=_private_ --><!-- Pod2Wiki=head_name -->
 
==NAME==
 
==NAME==
−
EPrints::Plugin::Screen
+
EPrints::Plugin::Screen - dynamic user interface web pages
  
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
Line 12: Line 12:
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
−
@params = $screen-&gt;hidden_bits()
+
<!-- Pod2Wiki=head_description -->
 +
==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 [[API:EPrints/Apache/Template|EPrints::Apache::Template]]. This includes the page title, header elements and page body.
 +
 
 +
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.
 +
 
 +
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.
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_two_requests -->
 +
===Two Requests===
 +
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.
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_three_requests -->
 +
===Three Requests===
 +
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.
 +
 
 +
Some screens override this behaviour and instead will render in response to a POST request.
 +
 
 +
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_methods -->
 +
==METHODS==
 +
<!-- Pod2Wiki=head_hidden_bits -->
 +
===hidden_bits===
 +
 
 +
<source lang="perl">@params = $screen->hidden_bits()
 +
 
 +
</source>
 
Returns a key-value list of values that must be set when referring to this screen.
 
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.
 
At the top-level this is just the 'screen' id.
  
−
$ok = $screen-&gt;verify_csrf()
+
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_verify_csrf -->
 +
===verify_csrf===
 +
 
 +
<source lang="perl">$ok = $screen->verify_csrf()
 +
 
 +
</source>
 
Verify that the CSRF token in the user agent's cookie matches the token passed in the form value.
 
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.
 
If the CSRF check fails no action should be taken as this may be an attempt to forge a request.
  
−
@screen_opts = $screen-&gt;list_items( $list_id, %opts )
+
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_list_items -->
 +
===list_items===
 +
 
 +
<source lang="perl">@screen_opts = $screen->list_items( $list_id, %opts )
 +
 
 +
</source>
 
Returns a list of screens that appear in list $list_id ordered by their position.
 
Returns a list of screens that appear in list $list_id ordered by their position.
  
Line 37: Line 110:
 
   params =&gt; {}</pre>
 
   params =&gt; {}</pre>
  
−
$ok = $screen-&gt;has_action( $action_id )
+
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_has_action -->
 +
===has_action===
 +
 
 +
<source lang="perl">$ok = $screen->has_action( $action_id )
 +
 
 +
</source>
 
Returns true if this screen has an action $action_id.
 
Returns true if this screen has an action $action_id.
  
−
$url = $screen-&gt;action_icon_url( $action )
+
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_action_icon_url -->
 +
===action_icon_url===
 +
 
 +
<source lang="perl">$url = $screen->action_icon_url( $action )
 +
 
 +
</source>
 
Returns the relative URL to the $action icon for this screen.
 
Returns the relative URL to the $action icon for this screen.
  
−
$frag = $screen-&gt;render_action_link()
+
<!-- Edit below this comment -->
 +
 
 +
 
 +
<!-- Pod2Wiki= -->
 +
<!-- Pod2Wiki=head_render_action_link -->
 +
===render_action_link===
 +
 
 +
<source lang="perl">$frag = $screen->render_action_link()
 +
 
 +
</source>
 
Returns a link to this screen.
 
Returns a link to this screen.
  
 +
<!-- Edit below this comment -->
 +
 +
 +
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki=head_copyright -->
 
<!-- Pod2Wiki=head_copyright -->
 
==COPYRIGHT==
 
==COPYRIGHT==

Revision as of 15:57, 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. This includes the page title, header elements and page body.

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.

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.


Two Requests

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.


Three Requests

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.

Some screens override this behaviour and instead will render in response to a POST request.


METHODS

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.


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.


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=10824’