Difference between revisions of "API:EPrints/Plugin/Convert"

From EPrints Documentation
Jump to: navigation, search
Line 18: Line 18:
 
Convert plugins may provide conversions from any number of formats to any number of other formats (or not even 'formats' per-se e.g. unpacking/packing archives). A single plugin may represent a particular software package (e.g. ImageMagick) or a common goal (e.g. textifying documents for indexing).
 
Convert plugins may provide conversions from any number of formats to any number of other formats (or not even 'formats' per-se e.g. unpacking/packing archives). A single plugin may represent a particular software package (e.g. ImageMagick) or a common goal (e.g. textifying documents for indexing).
  
Using the root Convert plugin it is possible to query all loaded conversion plugins for available conversions from a given [[API:EPrints/DataObj/Document|<tt>EPrints::DataObj::Document</tt>]].
+
Using the root Convert plugin it is possible to query all loaded conversion plugins for available conversions from a given [[API:EPrints/DataObj/Document|EPrints::DataObj::Document]].
  
 
To allow for simpler local configuration Convert plugins should use SystemSettings to store the location of external programs.
 
To allow for simpler local configuration Convert plugins should use SystemSettings to store the location of external programs.
Line 49: Line 49:
  
 
</source>
 
</source>
:Create a new plugin object using OPTIONS (should only be called by [[API:EPrints/Session|&lt;tt&gt;EPrints::Session&lt;/tt&gt;]]).
+
:Create a new plugin object using OPTIONS (should only be called by [[API:EPrints/Session|EPrints::Session]]).
 
:
 
:
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->

Revision as of 12:25, 15 March 2012

EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects


API: Core API

Latest Source Code (3.4, 3.3) | Revision Log | Before editing this page please read Pod2Wiki


NAME

EPrints::Plugin::Convert - Convert EPrints::DataObj::Document into different formats


DESCRIPTION

This plugin and its dependents allow EPrints to convert documents from one format into another format. Convert plugins are also used by the full-text indexer to extract plain-text from documents.

Convert plugins may provide conversions from any number of formats to any number of other formats (or not even 'formats' per-se e.g. unpacking/packing archives). A single plugin may represent a particular software package (e.g. ImageMagick) or a common goal (e.g. textifying documents for indexing).

Using the root Convert plugin it is possible to query all loaded conversion plugins for available conversions from a given EPrints::DataObj::Document.

To allow for simpler local configuration Convert plugins should use SystemSettings to store the location of external programs.


SYNOPSIS

my $root = $session->plugin( 'Convert' );

my %available = $root->can_convert( $document );

# Convert a document to plain-text
my $txt_tool = $available{'text/plain'};
my $plugin = $txt_tool->{ plugin };
$plugin->convert( $eprint, $document, 'text/plain' );


METHODS

new

new OPTIONS
Create a new plugin object using OPTIONS (should only be called by EPrints::Session).


render_name

$xhtml = $plugin->render_name
Return the name of this plugin as a chunk of XHTML.


is_visible

$plugin->is_visible( $level )
Returns whether this plugin is visible at level (currently 'all' or ).


can_convert

%types = $p->can_convert( $doc, [$type], [%params] )
Returns a hash of types that this plugin can convert the document $doc to. The key is the type. The value is a hash ref containing:
  • plugin
The object that can do the conversion.
  • encoding
The encoding this conversion generates (e.g. 'utf-8').
  • phraseid
A unique phrase id for this conversion.
  • preference
A value between 0 and 1 representing the 'quality' or confidence in this conversion.


export

@filelist = $p->export( $dir, $doc, $type )
Convert $doc to $type and export it to $dir. Returns a list of file names that resulted from the conversion. The main file (if there is one) is the first file name returned. Returns empty list on failure.


convert

$doc = $p->convert( $eprint, $doc, $type [, $epdata ] )
Convert $doc to format $type (as returned by can_convert). Stores the resulting $doc in $eprint, and returns the new document or undef on failure.
Optionally initialise the new document with $epdata. Specifying 'files' in $epdata will cause the converted file content to be discarded.


COPYRIGHT

Copyright 2000-2011 University of Southampton.

This file is part of EPrints http://www.eprints.org/.

EPrints is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

EPrints is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with EPrints. If not, see http://www.gnu.org/licenses/.