Triggers

Triggers are a means of defining a function that will be called at a particular execution point (often referred to as a hook). EPrints repository software facilitates this as often a repository may want to carry out a particular task when a specific event occurs (or is about to occur). EPrints has many different types of trigger some are generic and some are applied to specific dataset. The following are those most commonly implemented:

Repository Triggers

EP_TRIGGER_LOG

When logging messages to standard error.

EP_TRIGGER_BOILERPLATE_RDF

When generating the boilerplate RDF for the repository.

EP_TRIGGER_REPOSITORY_RDF

When generating repository specific RDF.

EP_TRIGGER_BEGIN

When an EPrints::Repository object is created.

EP_TRIGGER_BEGIN_REQUEST

At the start of an HTTP request being processed.

EP_TRIGGER_END_REQUEST

At the end of processing an HTTP request.

EP_TRIGGER_END

Just before an EPrints::Repository object is destroyed.

EP_TRIGGER_DOC_URL_REWRITE

When rewriting an URL for a document so it can be responded to with the correct resource.

Example

Send the coversheeted version of the document rather than the original.

$c->add_trigger( EP_TRIGGER_DOC_URL_REWRITE, sub
{
    my( %args ) = @_;

    my( $request, $doc, $relations, $filename ) = @args{qw( request document relations filename )};
    return EP_TRIGGER_OK unless defined $doc && ref $doc eq "EPrints::DataObj::Document"; # To avoid missing field error with dark documents that do not get coversheeted.

    # check document is a pdf
    my $format = $doc->value( "format" ); # back compatibility
    my $mime_type = defined $doc->value( "mime_type" ) ? $doc->value( "mime_type" ) : "";
    return EP_TRIGGER_OK unless( $format eq "application/pdf" || $mime_type eq "application/pdf" || $filename =~ /\.pdf$/i );

    # ignore thumbnails e.g. http://.../8381/1.haspreviewThumbnailVersion/jacqueline-lane.pdf
    foreach my $rel ( @{$relations || []} )
    {
        return EP_TRIGGER_OK if( $rel =~ /^is\w+ThumbnailVersionOf$/ );
    }

    # ignore volatile documents
   return EP_TRIGGER_OK if $doc->has_relation( undef, "isVolatileVersionOf" );

    my $session = $doc->get_session;
    my $eprint = $doc->get_eprint;

    # search for a coversheet that can be applied to this document
    my $coversheet = EPrints::DataObj::Coversheet->search_by_eprint( $session, $eprint );
    return EP_TRIGGER_OK unless( defined $coversheet );

    # check whether there is an existing covered version and whether it needs to be regenerated
    my $current_cs_id = $doc->get_value( 'coversheetid' ) || -1; # coversheet used to cover document
    my $coverdoc; # existing covered version

    if( $coversheet->get_id == $current_cs_id )
    {
        # get the covered version of the document
        $coverdoc = $coversheet->get_coversheet_doc( $doc );
    }

    if( defined $coverdoc )
    {
        # return the covered version
        $coverdoc->set_value( "security", $doc->get_value( "security" ) );
        $request->pnotes( document => $coverdoc );
        $request->pnotes( dataobj => $coverdoc );

        # Only update request filename to coverdoc's filename if it is defined and the document filename matches that used in the request.  
        # If the document filename does not match that used in the request, then not updating the filename will mean requests with a
        # spurious filename will get a 404 error rather than returning the document under a spurious filename.
        $request->pnotes( filename => $coverdoc->get_main ) if defined $coverdoc->get_main && defined $doc->get_main && $filename eq $doc->get_main;
    }
 
    # return the uncovered document

    return EP_TRIGGER_DONE;

}, priority => 100 );

EP_TRIGGER_MEDIA_INFO

When extracting media information about a file (e.g. MIME type, resolution if image/video, duration if audio/video, etc.).

Example

Set the mime_type index for <code$epdata to whatever is determined from the file extension using the mimemap index.

$c->add_trigger( EP_TRIGGER_MEDIA_INFO, sub {
    my( %params ) = @_;

    my $epdata = $params{epdata};
    my $filename = $params{filename};
    my $repo = $params{repository};

    return 0 if defined $epdata->{mime_type};

    if( $filename=~m/\.([^.]+)$/ )
    {
        my $suffix = "\L$1";
        $epdata->{mime_type} = $repo->config( "mimemap", $suffix );
    }

    return 0;
}, priority => 5000);

EP_TRIGGER_INDEX_FIELDS

When fields are being indexed.

Example

Also index fields in the Xapian index.

$c->add_trigger( EP_TRIGGER_INDEX_FIELDS, sub {
    my( %params ) = @_;

    my $repo = $params{repository};
    my $dataobj = $params{dataobj};
    my $dataset = $dataobj->dataset;

    if( !$repo->config( 'xapian', 'enabled' ) )
    {
        return;
    }

   if( !$dataset->indexable )
   {
       $repo->log( "Xapian::Index: dataset %s is not indexable", $dataset->id );
       return;
   }

   # caches the Xapian indexing module in the current EPrints::Repository object
   # only relevant when a full dataset re-indexing is performed (to avoid re-connecting
   # to the Xapian DB too often)
   my $indexer = $repo->{_xapian_indexer};
   if( !defined $indexer )
   {
       $indexer = $repo->{_xapian_indexer} = EPrints::Xapian::Index->new(
           repository => $repo,
           dataset => $dataset,
       );
   }

   if( !defined $indexer )
   {
       $repo->log( "Failed to load EPrints::Xapian::Index" );
       return;
   }

   $indexer->index_dataobj( $dataobj );

   return EP_TRIGGER_OK;
} );

EP_TRIGGER_INDEX_REMOVED

When fields are being removed from the index.

EP_TRIGGER_URL_REWRITE

When rewriting an URL so it can be responded to with the correct resource.

Example

Use the MePrints handler for serving profile pages.

$c->add_trigger( EP_TRIGGER_URL_REWRITE, sub
{
    my( %args ) = @_;

    my( $uri, $rc, $request ) = @args{ qw( uri return_code request ) };

   if( defined $uri && ($uri =~ m#^/profile/(.*)$# ) )
   {
       $request->handler('perl-script');
       $request->set_handlers(PerlResponseHandler => [ 'EPrints::Plugin::MePrints::MePrintsHandler' ] );
       ${$rc} = EPrints::Const::OK;
   }

   return EP_TRIGGER_OK;

}, priority => 100 );

EP_TRIGGER_VALIDATE_FIELD

When a metadata field is being validated.

EP_TRIGGER_LOCAL_SITEMAP_URLS

When generating URLs to add to the repository sitemap (i.e. sitemap.xml).

Example

Add creators browse view pages to sitemap.

$c->add_trigger( EP_TRIGGER_LOCAL_SITEMAP_URLS, sub
{
    my( %args ) = @_;

    my( $repository, $urlset ) = @args{qw( repository urlset )};

    $urlset->appendChild( EPrints::Utils::make_sitemap_url( $repository, {
        loc => $repository->config( "base_url" ).'/view/creators/',
        changefreq => 'monthly'
    } ) );

   return EP_TRIGGER_OK;
});

EP_TRIGGER_DYNAMIC_TEMPLATE

When the dynamic template for a web page response to a request is being generated.

Example

$c->add_trigger( $EPrints::Plugin::Stats::EP_TRIGGER_DYNAMIC_TEMPLATE, sub
{
    my( %args ) = @_;

    my( $repo, $pins ) = @args{qw/ repository pins/};

    my $protocol = $repo->get_secure ? 'https':'http';

    my $head = $repo->make_doc_fragment;

    $head->appendChild( $repo->make_javascript( undef,
        src => "$protocol://www.google.com/jsapi"
    ) );

    $head->appendChild( $repo->make_javascript( 'google.charts.load("current", {packages:["corechart", "geochart"]});' ) );

    if( defined $pins->{'utf-8.head'} )
    {
        $pins->{'utf-8.head'} .= $repo->xhtml->to_xhtml( $head );
    }

    if( defined $pins->{head} )
    {
        $head->appendChild( $pins->{head} );
        $pins->{head} = $head;
    }
    else
    {
        $pins->{head} = $head;
    }

    return EP_TRIGGER_OK;
} );

EP_TRIGGER_THUMBNAIL_TYPES

When determining what thumbnails types to generate for (a) file(s) associated with a document.

Dataset Triggers

• EP_TRIGGER_CREATED - When a new data object is being created.
• EP_TRIGGER_RDF - When RDF for a data object is being generated.
• EP_TRIGGER_DEFAULTS - When a new data object is setting its default values
• EP_TRIGGER_STATUS_CHANGE - When the status of a data object changes, (e.g. when an eprint is moved to the live archive).
• EP_TRIGGER_BEFORE_COMMIT - Just before the changes to a data object are saved to the database.
• EP_TRIGGER_AFTER_COMMIT - Just after the changes to a data object have been saved to the database.
• EP_TRIGGER_VALIDATE - When the data object fields are being checked for their validity.
• EP_TRIGGER_WARNINGS - When a data objects is generating warnings about its state (e.g. missing or inappropriate metadata field values).
• EP_TRIGGER_FILES_MODIFIED - When a file associated with a data object has been modified (e.g. new thumbnails will need to be generated if the file they are based on has changed or added).
• EP_TRIGGER_REMOVED - When a data object is destroyed.