Editing Triggers (section)

== Dataset Triggers ==
=== EP_TRIGGER_CREATED ===
When a new data object is being created.

==== Example ====
Creates a default list object for a user.
 $c->add_dataset_trigger(
     'user',
     EPrints::Const::EP_TRIGGER_CREATED,
     sub {
         my (%args) = @_;
         my ( $session, $user ) = @args{qw( repository dataobj )};
         EPrints::Lists::Utils::create_default_list( $session, $user );
     }
 );

=== EP_TRIGGER_RDF ===
When RDF for a data object is being generated.

==== Example ====
Adds certain SKOS triples to RDF output.
 $c->add_dataset_trigger( "eprint", EP_TRIGGER_RDF, sub {
     my( %o ) = @_;
     my $eprint = $o{"dataobj"};
     my $eprint_uri = "<".$eprint->uri.">";
 
     return if ! $eprint->dataset->has_field( "subjects" );
     return if ! $eprint->is_set( "subjects" );
 
     foreach my $subject_id ( @{$eprint->get_value( "subjects" )} )
     {
         my $subject = $o{repository}->dataset( "subject" )->dataobj( $subject_id );
         if( $subject )
         {
             my $subject_uri = "<".$subject->uri.">";
             $o{graph}->add(
                 subject => $subject_uri,
                 predicate => "rdf:type",
                 object => "skos:Concept" );
             foreach my $name ( @{$subject->get_value( "name" )} )
             {
                 $o{graph}->add(
                     subject => $subject_uri,
                     predicate => "skos:prefLabel",
                     object => $name->{name},
                     type => "literal",
                     lang => $name->{lang} );
             }
             $o{graph}->add(
                 subject => $eprint_uri,
                 predicate => "dct:subject",
                 object => $subject_uri );
         }
     }
 });

=== EP_TRIGGER_DEFAULTS ===
When a new data object is setting its default values.  (<font style="color: red;">Not currently implemented</font>. You can use <code>$c->{set_&lt;DATASET&gt;_defaults}</code> setting in [[document_fields_default.pl]], [[eprint_fields_default.pl]] or [[user_fields_default.pl]] instead).

=== EP_TRIGGER_STATUS_CHANGE ===
When the status of a data object changes, (e.g. when an eprint is moved to the live archive).

==== Example ====
Add an indexer task to coin/mint a DataCite DOI for the eprint.
 $c->add_dataset_trigger( "eprint", EP_TRIGGER_STATUS_CHANGE , sub {
     my ( %params ) = @_;
 
     my $repository = $params{repository};
 
     return undef if (!defined $repository);
 
     if (defined $params{dataobj}) {
         my $dataobj = $params{dataobj};
         my $eprint_id = $dataobj->id;
         $repository->dataset( "event_queue" )->create_dataobj({
             pluginid => "Event::DataCiteEvent",
             action => "datacite_doi",
             params => [$dataobj->internal_uri],
         });
     }
 
 });

=== EP_TRIGGER_BEFORE_COMMIT ===
Just before the changes to a data object are saved to the database.

==== Example ====
Set or otherwise tidy up the <code>path</code> field for the list object.
 $c->add_dataset_trigger( "list", EPrints::Const::EP_TRIGGER_BEFORE_COMMIT, sub {
     my (%args) = @_;
     my ( $session, $list ) = @args{qw( repository dataobj )};
     if ( !$list->is_set("path") ) {
         $list->set_value( "path", EPrints::DataObj::List::tidy_path( $list->get_value("title") ) );
     }
     else {
         my $path = $list->get_value("path");
         my $tidy_path = EPrints::DataObj::List::tidy_path($path);
         $list->set_value( "path", $tidy_path ) if $path ne $tidy_path;
     }
 });

=== EP_TRIGGER_AFTER_COMMIT ===
Just after the changes to a data object have been saved to the database.

==== Example ====
Remove the cache static page for the user's profile, so that it can be re-generated and re-cached.
 $c->add_dataset_trigger( "user", EPrints::Const::EP_TRIGGER_AFTER_COMMIT, sub {
     my( %params ) = @_;
 
     my $repo = $params{repository};
     my $user = $params{dataobj};
     my $changed = $params{changed};
 
     if( scalar( keys %{$changed||{}} ) )
     {
         $user->remove_static();
     }
 });

=== EP_TRIGGER_VALIDATE ===
When the data object fields are being checked for their validity. (<font style="color: red;">Not currently implemented.</font>  Either use [[#EP_TRIGGER_VALIDATE_FIELD|EP_TRIGGER_VALIDATE_FIELD]] or <code>$c->{set_&lt;DATASET&gt;_automatic_fields}</code> setting in [[document_fields_automatic.pl]], [[eprint_fields_automatic.pl]] or [[user_fields_automatic.pl]]).

=== EP_TRIGGER_WARNINGS ===
When a data objects is generating warnings about its state (e.g. missing or inappropriate metadata field values).  (<font style="color: red;">Not currently implemented</font>. use <code>$c->{&lt;DATASET&gt;_warnings}</code> setting, e.g. <code>$c->{eprint_warnings}</code> in [[eprint_warnings.pl]]).

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

==== Example ====
Generate special preview versions for certain documents.
 $c->add_dataset_trigger( "document", EPrints::Const::EP_TRIGGER_FILES_MODIFIED, sub
 {
     my( %args ) = @_;
     my( $session, $doc ) = @args{qw( repository dataobj )};
 
     my $eprint = $doc->get_parent;
 
     # abridged from bin/generate_previews
     my $dir = $session->get_repository->get_conf("archiveroot" )."/cfg/static/previews/".$eprint->get_id;
 
     return  unless $doc->get_value("main") =~ /\.(pdf|doc|docx|xls|xlsx|ppt|pptx|md)$/i or  $doc->get_value( "format" ) eq "code";
 
     $dir .= "/" . $doc->get_id;
     my $preview_source = $session->get_repository->get_conf("archiveroot" ) . "/cfg/static/previews/" . $eprint->get_id . "/" . $doc->get_id;
 
     # clear any old versions
     if( -e $preview_source ) 
     {
         remove_tree $preview_source;
     }
 
     my $file_path = $doc->local_path . '/' . $doc->get_main;
 
     my $script = $session->get_repository->get_conf("base_path") . "/ingredients/preview_generate/bin/previews/make_pages.sh";
     if( $doc->get_value( "format" ) eq "code" )
     {
         $script = $session->get_repository->get_conf("base_path") . /ingredients/preview_generate/bin/previews/make_code_preview.sh";
     }
 
     my $docid = $doc->get_id;
     `$script "$file_path" "$dir" "$docid"`;
 
     $eprint->generate_static();
 });

=== EP_TRIGGER_REMOVED ===
When a data object is destroyed.

==== Example ====
Remove indexing from Xapian if eprint is removed.
 $c->add_dataset_trigger( "eprint", EP_TRIGGER_REMOVED, sub {
     my( %params ) = @_;
 
     my $repo = $params{repository};
     my $dataobj = $params{dataobj};
     my $dataset = $dataobj->dataset;
 
     if( !$repo->config( 'xapian', 'enabled' ) )
     {
         return;
     }
     EPrints::DataObj::EventQueue->create_unique( $repo, {
         pluginid => "Event::Xapian",
         action => "remove_index",
         params => [$dataobj->get_id],
     });
     return EP_TRIGGER_OK;
 });