Difference between revisions of "How to make a Screen perform Actions"

From EPrints Documentation
Jump to: navigation, search
m (Where to go after the action completes: Added details about redirecting to an absolute url and changed pre tags to source tags on this section)
 
(19 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
[[Category:Howto]][[Category:Plugins]]
 +
 
  Works in EPrints 3.2+
 
  Works in EPrints 3.2+
  
 
Please read the page on [[How_to_make_a_Screen_for_the_Admin_Section]] as this extends that information.
 
Please read the page on [[How_to_make_a_Screen_for_the_Admin_Section]] as this extends that information.
 +
 +
NOTE: in this page, $s is the ''session'' or ''repository'' object, and $f is the (x)html DOM fragment
 +
 +
The action buttons are the functionality that make the work... well, flow.
 +
 +
You need to define the "screen" (perl package) that contains the actions, and what the actions are.
  
 
===What's happening===
 
===What's happening===
  
 
The process has four parts:
 
The process has four parts:
 +
# Register the ''actions'' with the EPrints system
 
# Some ''action'' buttons
 
# Some ''action'' buttons
 +
# Some ''action'' routines
 
## A ''allow'' routine
 
## A ''allow'' routine
 
## An ''action'' routine
 
## An ''action'' routine
# Some packages to process the actions
+
### These routines could all be contained in the one package
## The routines could all be contained in the one package
+
### These routines could be spread out over several packages
## The routines could be spread out over several packages
 
# Some ''action'' routines
 
 
# Where to go after the ''action'' completes
 
# Where to go after the ''action'' completes
 +
 +
===Getting actions recognised===
 +
Before a Screen will even consider processing an action, it need to register those actions with the system. This is defined in <code>$self->{actions}</code> in the <code>new</code> method:
 +
 +
<pre>
 +
sub new {
 +
  my ( $class, %params ) = @_;
 +
 +
  my $self = $class->SUPER::new(%params);
 +
 +
  $self->{actions}
 +
      = [qw/new edit cancel view netunlink netlink repounlink repolink/];
 +
 +
  $self->{appears} = .....
 +
 +
  ## any other code.....
 +
 +
  return $self;
 +
} ## end sub new
 +
 +
</pre>
 +
Note that the terms listed in the <code>$self->{actions}</code> array are the same terms as keys in the action buttons.
  
 
===Making the buttons===
 
===Making the buttons===
The action buttons are the functionality that make the work... well, flow.
+
The Buttons are the form submit buttons, the things that make the work flow to the next stage.
 
 
You need to define the "screen" (perl package) that contains the actions, and what the actions are.
 
  
 
The <code>$s->render_action_buttons</code> function takes a hash, which describes the set of buttons to display:
 
The <code>$s->render_action_buttons</code> function takes a hash, which describes the set of buttons to display:
Line 47: Line 75:
  
 
===Where the actions are processed===
 
===Where the actions are processed===
 +
The actions are processed in a "Screen", a perl package.
 +
The form being submitted therefor needs to contain a reference to that package:
 +
 +
    $f->appendChild( $s->render_hidden_field( "screen", "Orgs"));
 +
 +
This would call the package <code>EPrints::Plugin::Screen::Orgs</code>, and try to process the selected action in there
 +
 +
(Yes, this means that one can have the same action in multiple Screens, as well as multiple action in the same Screen)
 +
 +
===Processing the actions===
 +
The EPrints processor system calls a specified action in a named package (as detailed above)
 +
 +
For each possible action, two functions needed: <code>allow_''action''</code> and <code>action_''action''</code>... where ''action'' is the key given in the buttons hash above.
 +
 +
====The ''allow'' test====
 +
The EPrints processor will always test to see if the user is permitted to perform an action.
 +
A "True" return will permit the action.
 +
<pre>
 +
sub allow_cancel
 +
{
 +
  return 1; # everyone can do this "cancel" action
 +
}
 +
 +
sub allow_update
 +
{
 +
    my( $self ) = @_;
 +
    return $self->can_edit; # Only users who have "can_edit" permissions can do this "update" action
 +
}
 +
</pre>
 +
 +
====The actual ''action'' routines====
 +
Assuming that the user is permitted to do the action, then EPrints processor will call the appropriate action routine:
 +
<pre>
 +
sub action_cancel
 +
{
 +
    my( $self ) = @_;
 +
 +
    # Do stuff
 +
 +
}
 +
</pre>
 +
 +
====Getting the parameters====
 +
The parameters are collected from the session:
 +
 +
  my $oname = $self->{session}->param( 'oarj_oname' );
 +
 +
One could be a bit more conservative:
 +
 +
<pre>
 +
  my %params;
 +
 +
  # Have we got any parameters (should be a yes, actions are set in parameters)
 +
  if ($self->{session}->have_parameters)
 +
  {
 +
 +
    # Get a list of all the parameters passed in
 +
    my @param_list = $self->{session}->param;
 +
 +
    # build up a hash of all the parameters
 +
    foreach my $p (@param_list) {
 +
        $params{$p} = $self->{session}->param( $p );
 +
    }
 +
  };
 +
</pre>
 +
 +
.... of course one would assume that, having written the action handler, you know what parameters to expect, and can just ask for them directly!
 +
 +
===Where to go after the action completes===
 +
By default, the EPrints processor will then render whatever's in the render routine for the package that the action routines are in.
 +
If you want the EPrints processor to use a different package to render something to the page, then:
 +
<source lang="perl">
 +
sub action_cancel
 +
{
 +
    my( $self ) = @_;
 +
 +
    # Do stuff
 +
    $self->{processor}->{screenid} = "My::Package";
 +
}
 +
</source>
 +
will call the <code>render</code> routine in the package <code>EPrints::Plugin::Screen::My::Package</code> whilst:
 +
<source lang="perl">
 +
sub action_cancel
 +
{
 +
    my( $self ) = @_;
 +
 +
    # Do stuff
 +
    $self->{processor}->{redirect} = "http://wiki.eprints.org";
 +
}
 +
</source>
 +
will redirect the page to the url specified (in this case to the wiki homepage)
 +
 +
Return to the main [[Screen_Plugins]] page.

Latest revision as of 09:06, 11 May 2016


Works in EPrints 3.2+

Please read the page on How_to_make_a_Screen_for_the_Admin_Section as this extends that information.

NOTE: in this page, $s is the session or repository object, and $f is the (x)html DOM fragment

The action buttons are the functionality that make the work... well, flow.

You need to define the "screen" (perl package) that contains the actions, and what the actions are.

What's happening

The process has four parts:

  1. Register the actions with the EPrints system
  2. Some action buttons
  3. Some action routines
    1. A allow routine
    2. An action routine
      1. These routines could all be contained in the one package
      2. These routines could be spread out over several packages
  4. Where to go after the action completes

Getting actions recognised

Before a Screen will even consider processing an action, it need to register those actions with the system. This is defined in $self->{actions} in the new method:

sub new {
  my ( $class, %params ) = @_;

  my $self = $class->SUPER::new(%params);

  $self->{actions}
      = [qw/new edit cancel view netunlink netlink repounlink repolink/];

  $self->{appears} = .....

  ## any other code.....
 
  return $self;
} ## end sub new

Note that the terms listed in the $self->{actions} array are the same terms as keys in the action buttons.

Making the buttons

The Buttons are the form submit buttons, the things that make the work flow to the next stage.

The $s->render_action_buttons function takes a hash, which describes the set of buttons to display:

    my %buttons = (
		    cancel   => $self->phrase( "action:cancel:title" ), # Is defined as "Cancel"
                    update   => $self->phrase( "action:update:title" ), # Is defined as "Update"
                    _order   => [ "update", "cancel" ],
                    _class   => "ep_form_button_bar"
	          );
    $f->appendChild( $s->render_action_buttons( %buttons ) );
  • cancel => $self->phrase( "action:cancel:title" ) describe one action button: the internal name for the action and the text to be used for that button. You may have any number of buttons.
  • _order is a reference to a list defining the order for the buttons. With nothing defined, the order will be random.
  • _class defines the css class to give to the div that contains the buttons.

The above code would produce the following (x)html:

<div class="ep_form_button_bar">
 <input type="submit" class="ep_form_action_button"
        onclick="return EPJS_button_pushed( '_action_update' )"
        name="_action_update" value="Update">
 <input type="submit" class="ep_form_action_button"
        onclick="return EPJS_button_pushed( '_action_cancel' )"
        name="_action_cancel" value="Cancel">
 </div>

Where the actions are processed

The actions are processed in a "Screen", a perl package. The form being submitted therefor needs to contain a reference to that package:

   $f->appendChild( $s->render_hidden_field( "screen", "Orgs"));

This would call the package EPrints::Plugin::Screen::Orgs, and try to process the selected action in there

(Yes, this means that one can have the same action in multiple Screens, as well as multiple action in the same Screen)

Processing the actions

The EPrints processor system calls a specified action in a named package (as detailed above)

For each possible action, two functions needed: allow_action and action_action... where action is the key given in the buttons hash above.

The allow test

The EPrints processor will always test to see if the user is permitted to perform an action. A "True" return will permit the action.

sub allow_cancel 
{
   return 1; # everyone can do this "cancel" action
}

sub allow_update
{
    my( $self ) = @_;
    return $self->can_edit; # Only users who have "can_edit" permissions can do this "update" action
}

The actual action routines

Assuming that the user is permitted to do the action, then EPrints processor will call the appropriate action routine:

sub action_cancel
{
    my( $self ) = @_;

    # Do stuff

}

Getting the parameters

The parameters are collected from the session:

 my $oname = $self->{session}->param( 'oarj_oname' );

One could be a bit more conservative:

  my %params;

  # Have we got any parameters (should be a yes, actions are set in parameters)
  if ($self->{session}->have_parameters)
  {

     # Get a list of all the parameters passed in
     my @param_list = $self->{session}->param;

     # build up a hash of all the parameters
     foreach my $p (@param_list) {
        $params{$p} = $self->{session}->param( $p );
     }
  };

.... of course one would assume that, having written the action handler, you know what parameters to expect, and can just ask for them directly!

Where to go after the action completes

By default, the EPrints processor will then render whatever's in the render routine for the package that the action routines are in. If you want the EPrints processor to use a different package to render something to the page, then:

sub action_cancel
{
    my( $self ) = @_;

    # Do stuff
    $self->{processor}->{screenid} = "My::Package";
}

will call the render routine in the package EPrints::Plugin::Screen::My::Package whilst:

sub action_cancel
{
    my( $self ) = @_;

    # Do stuff
    $self->{processor}->{redirect} = "http://wiki.eprints.org";
}

will redirect the page to the url specified (in this case to the wiki homepage)

Return to the main Screen_Plugins page.