XML manipulation of the Abstract page using a Bazaar Module

Before you can carry out the work outlined on this page you will need to prepare your package by following the steps on the XML manipulation of the EPrints Workflow using a Bazaar Package page up until the start of Exercise 1.

In this exercise we are going to manipulate the abstract page by changing the citation XML which is displayed on various parts of the rendered abstract page.

Pre-Requisits

To do this exercise you will need:

• A live EPrint record of type article. Training repositories should come set up with the test data.
• A rights field added to the EPrints workflow and filled in for this eprint.

To add the rights field is simply a replication of the XML manipulation of the EPrints Workflow using a Bazaar Package exercise, with the following code block to manipulate the workflow needing to be added to enable:

 my $filename = $repository->config( "config_path" )."/workflows/eprint/default.xml";
 
 my $string = '
 <workflow xmlns="http://eprints.org/ep3/workflow" xmlns:epc="http://eprints.org/ep3/control">
       <stage name="core">
       <component type="Field::Multi">
       <epc:if test="type = 'article'">
       <field ref="copyright_holders"/>
       </epc:if>
       </component>
       </stage>
 </workflow>
 ';
 
 EPrints::XML::add_to_xml( $filename, $string, $self->{package_name} );

 Don't forget the equivalent code block in disable to remove it again.

Exercise 1

We are going to directly manipulate the EPrints summary page to add the copyright holder data directly below the main citation. This could be done with the citation file in exactly the same way, we have just chosen to do the XML manipulation on the summary_page.xml instead.

Firstly we fetch the citation (code needed in both the enable and disable methods).

 my $citation = $repository->dataset( "eprint" )->citation( "summary_page" );
 
 my $filename = $citation->{filename};

Then we specify our xml to add in enable

 $string = "
 <cite:citation xmlns='http://www.w3.org/1999/xhtml' xmlns:epc='http://eprints.org/ep3/control' xmlns:cite='http://eprints.org/ep3/citation'>
   <p style='margin-bottom: 1em'>
      <div align='center'>
        <i>
          <epc:foreach expr='copyright_holders' iterator='item'>
            <epc:print expr='\$item'/><br/>
          </epc:foreach>
        </i>
      </div>
   </p>
 </cite:citation>
 ";

Apply it.

   EPrints::XML::add_to_xml( $filename,$string,$self->{package_name} );

Along with the 2 lines from earlier we need to call the inverse operation in disable to remove the stuff the package has added:

   EPrints::XML::remove_package_from_xml($filename,$self->{package_name} );

Note that this is same call as the workflow XML removal, just with a different filename.

Expiring your Abstract Pages

Due the fact we are adding to the abstract pages of an eprint record we need to expire them so that next time they are requested they are re-drawn. This code needs to be added to both the enable and disable methods.

 unless( $repository->expire_abstracts() )
 {
      $self->{processor}->add_message( "warning","You need to regenerate abstracts" ); 
 }

This is an example of returning a code which is not true or false. In this case the code means "I was successful but the user needs to do something extra".

Testing

This time to test you can just add some copyright holder metadata to an article and then refresh that articles abstract to see if it worked.

Exercise 2 - Overriding whole sections of the abstract page

This feature allows you to replace entire sections of the abstract page with your own code.

This is a simple enough operation to do, instead of simply matching XML elements and adding ones that aren't there like we have been doing up to this point, we now specify a flag on an element to begin the replacement.

See if you can work out what this piece of XML will do, why not add it to your package and try it.

 <cite:citation xmlns='http://www.w3.org/1999/xhtml' xmlns:epc='http://eprints.org/ep3/control' xmlns:cite='http://eprints.org/ep3/citation'>
   <epc:set operation='replace' name='docs' expr='\$item.documents()'>Hello</epc:set>
 </cite:citation>

Other Possible Operations (r6016)

• replace: Causes the node you are defining to replace any node which has exactly the same definition.
• disbale: Disables any node with the exact same attributes.

Currently there is no add_node_after or add_node_before operation however these are being looked into.

Exercise 3

Our copyright section doesn't really say what it is all about, how about adding a phrase, clue:

 <epc:phrase ref="myphrase_ref"/>

Exercise 4

Select any section on the abstract page to replace and see if you can replace it with something much prettier. Could you recognise the epub format and display this in a specific way which is different to other articles.

Final Note

In these exercises I keep overriding the return code each time an operation is performed and not returning. Final versions of packages should decide what to do with the return codes at each stage and when and what to finally return. The return codes are going to replaced by constants in the near future.