View source for Files/Coverpage / CoverLatex plugins

== Coverpage / CoverLatex plugins ==

This is a plugin that prepends coverpages to documents. It uses a
convert plugin to generate the actual pages.

The shipped implementation (<tt>CoverLatex</tt>) uses a citation XML template
to generate LaTeX source, compiles that into a PDF coverpage and
prepends it using <tt>pdftk</tt>.

Coverpage versions of the documents are updated and saved when
documents are requested: The plugin uses the new
<tt>EP_TRIGGER_DOC_URL_REWRITE</tt> trigger introduced in EPrints
3.2.1. Coverpage documents are refreshed when the corresponding
document or when the associated eprint metadata changes.

The plugin also integrates into the upload workflow: If a PDF is
encrypted and thus prepending a coverpage isn't possible, a warning is
printed. Besides the "coverpage" metafield of the document is set to
<tt>FALSE</tt> to indicate that future attempts to generate a coverpage are
unnecessary.

It uses document relations (<tt>isCoverPageVersionOf</tt>, <tt>hasCoverPageVersion</tt>)
to connect the original document to its coverpage version.  Discovery
of an appropriate conversion plugin is done via the "<tt>can_convert</tt>"
method of the Convert module.



== Installation ==


* unpack the [http://files.eprints.org/588 extension package] in your archive directory (<tt>/opt/eprint3/archives/ARCHIVE_ID/</tt>)

* edit <tt>cfg/cfg.d/coverpage.pl</tt>

* edit the citation file <tt>cfg/citations/eprint/coverpage_latex.xml</tt> and the corresponding phrases <tt>cfg/lang/en/phrases/coverpage.xml</tt>.

* add a coverpage field to <tt>cfg/cfg.d/document_fields.pl</tt>:
<pre>
$c->{fields}->{document} = [
        {
                name => "coverpage",
                type => "boolean",
                input_style => 'radio',
        },
];
</pre>

* run
   <tt>epadmin update_database_structure ''archiveid''</tt>

* add the coverpage field to <tt>cfg/workflows/eprint/default.xml</tt>:
<pre>
    <component type="Documents">
[...]
      <field ref="coverpage" />
    </component>
</pre>

* add the following code to <tt>validate_document()</tt> in <tt>cfg/cfg.d/document_validate.pl</tt>:
<pre>
        my $cp = $session->plugin('Coverpage');
        if ($cp) {
          my $cp_switch = $document->get_value('coverpage') || '';
          if ($cp_switch ne 'FALSE') {
            my $conv_plugin = $cp->get_conversion_plugin($document);
            if ($conv_plugin) {
              my @conv_problems = $conv_plugin->validate($document);
              if (@conv_problems) {
                # pdf is encrypted
                push @problems, @conv_problems;
                $session->log("coverpage conversion problems, setting coverpage to false");
                $document->set_value('coverpage', 'FALSE');
                $document->commit;
              }
            } else {
              # doc type not supported
            }
          } else {
            # coverpage disabled
            $cp->remove_coverpage($document);
            my $fieldname = $session->make_element( "span", class=>"ep_problem_field:documents" );
            push @problems, $session->html_phrase('validate:coverpage_disabled',
                                                  fieldname => $fieldname);
          }
        }
</pre>