KULTUR Installation Guide
=========================

KULTUR provides preview-oriented abstract pages and slideshows for multimedia EPrints repositories.

Contents
--------

1 - Requirements
2 - Preparing for Installation
3 - Installing KULTUR
3 - Configuring KULTUR
4 - KULTUR Slideshow

1 Requirements
--------------

KULTUR requires EPrints 3.3 or later, correctly configured to generated image, video and audio previews.

NOTE KULTUR no longer generates video/audio previews as this function is now built in to EPrints 3.3.

2 Preparing for installation
----------------------------

Download KULTUR and unpack in a convenient location (eg. /tmp/kultur).

 $ cd /tmp/kultur
 $ tar xzf kultur-X.X-XXX.tar.gz

3 Installing KULTUR
-------------------

Run the following as the user that EPrints runs as, usually "eprints":

 $ cd /tmp/kultur
 $ cp -R perl_lib/* /opt/eprints3/perl_lib/

For each repository that will use KULTUR:

 $ cp -R local_cfg/* /opt/eprints3/archives/ARCHIVEID/

4 Configuring KULTUR
--------------------

In /opt/eprints3/perl_lib/EPrints.pm make the following change:

...
use EPrints::Script;
use EPrints::Script::Compiler;
use EPrints::Script::Compiled;
use EPrints::Script::Kultur; # Add this line

For each repository that will use KULTUR:

Review the list of deposit types in /opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/kultur.pl. These are the types for which KULTUR will create preview-oriented abstract pages.

Make the following change to /opt/eprints3/archives/ARCHIVEID/cfg/cfg.d/eprint_render.pl:

$c->{eprint_render} = sub
{
	my( $eprint, $repository, $preview ) = @_;
	
	my $succeeds_field = $repository->get_repository->get_dataset( "eprint" )->get_field( "succeeds" );
	my $commentary_field = $repository->get_repository->get_dataset( "eprint" )->get_field( "commentary" );

	my $flags = { 
		has_multiple_versions => $eprint->in_thread( $succeeds_field ),
		in_commentary_thread => $eprint->in_thread( $commentary_field ),
		preview => $preview,
	};
	my %fragments = ();

	# Add the following lines to activate KULTUR abstract pages
	if( defined $repository->config( "kultur" ) )
	{
		my $ktypes = $repository->config( "kultur", "types" );
		$ktypes = [] if !defined $ktypes;

		my $kultur_tabs = undef;
		foreach my $ktype ( @$ktypes )
		{
			if( $eprint->get_value( 'type' ) eq $ktype )
			{
				$kultur_tabs = kultur_eprint_render( $repository, $eprint, $preview );
				last;
			}
		}
		if( defined $kultur_tabs )
		{
			$flags->{kultur} = 1;
			$fragments{kultur_tabs} = $kultur_tabs;
		}
	}

Make the following change to /opt/eprints3/archives/ARCHIVEID/cfg/citations/eprint/summary_page.xml:

<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">
    <epc:print expr="$item.citation('default')" />
  </p>

  <epc:if test="$flags{has_multiple_versions}">
    <div style="margin-bottom: 1em">
      <epc:print expr="$multi_info" />
    </div>
  </epc:if>

  <!-- Add the following lines to activate KULTUR abstract pages -->
  <epc:choose>
   <epc:when test="$flags{kultur}">
    <epc:print expr="$kultur_tabs" />
  </epc:when>
  <epc:otherwise>

  <!-- this is the normal rendering for other types -->
  <epc:set name='docs' expr='$item.documents()'>

    <epc:if test="length($docs) = 0">
      <epc:phrase ref="page:nofulltext" />
      <epc:if test="$item.contact_email().is_set() and eprint_status = 'archive'">
        (<a href="{$config{http_cgiurl}}/request_doc?eprintid={eprintid}"><epc:phrase ref="request:button" /></a>)
      </epc:if>
    </epc:if>

  ...

    <epc:if test="abstract">
    <h2><epc:phrase ref="eprint_fieldname_abstract"/></h2>
    <p style="text-align: left; margin: 1em auto 0em auto"><epc:print expr="abstract" /></p>
  </epc:if>

  <!-- Replace the <table> section with the following: -->
  <epc:print expr="$item.citation('summary_page_metadata')" />

  <!-- close the epc:choose -->
  </epc:otherwise>
  </epc:choose>

Finally, run the following command and then restart apache:

 $ cd /opt/eprints3
 $ bin/epadmin refresh_abstracts ARCHIVEID

5 KULTUR Slideshow (optional)
-----------------------------

To add a slideshow of 10 random images from your repository, make the following change to /opt/eprints3/archives/ARCHIVEID/cfg/lang/en/static/index.xpage:

<epc:print expr="kultur_slideshow(10)" />

To periodically change the contents of the slideshow, create a cron job that will update the page, for example every 2 hours:

 0 */2 * * * /opt/eprints3/bin/generate_static ARCHIVEID