API:EPrints/Plugin/Screen

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

PARAMETERS

action_icon

  $self->{action_icon} = {
    move_archive => "action_approve.png",
    review_move_archive => "action_approve.png",
  };

Use an icon instead of a button for the given actions. The image name is relative to style/images/.

actions

  $self->{actions} = [qw( clear update cancel )];

A list of actions that are supported by this screen.

appears

  $self->{appears} = [
    place => "eprint_summary_page_actions",
    position => 100,
  ];

Controls where links/buttons to this plugin will appear.

place

The string-constant name of the list to appear in. Other plugins will refer to this via the list_items and related methods.

position

The relative position in the list to appear at. Higher means later in the list.

action

The optional action that this button will trigger.

icon

  $self->{icon} = "action_view.png";

Use an icon instead of a button for links to this screen. The image name is relative to style/images/.

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

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

API:EPrints/Plugin/Screen

Contents