=head1 NAME
OpenOffice::OODoc::Intro - Introduction to the Open OpenDocument Connector
=head1 DESCRIPTION
This introductory notice is intended to allow the user to understand the
general principles and to learn some basic features of the OODoc module
without browsing the whole reference manual.
The reference manual is a set of OpenOffice::OODoc::xxx separate documents,
where xxx is the codename of a particular functional area. The present
introduction, as well as the OpenOffice::OODoc main chapter, should be read
in order to get the big picture before any attempt to dig in the detailed
documentation.
Just before reading this intro, it's a good idea to have a look at the
short (and commented) examples provided in the distribution.
Another general introduction to this Perl OpenDocument Connector has been
published in The Perl Review (issue #3.1, dec. 2006)
L<http://www.theperlreview.com>
There is an alternative intro for french-reading users. It's available in
ODT (L<http://jean.marie.gouarne.online.fr/doc/oodoc_guide.odt>) or PDF
(L<http://jean.marie.gouarne.online.fr/doc/oodoc_guide.pdf>). In addition,
a general presentation in French can be downloaded at
L<http://jean.marie.gouarne.online.fr/doc/perl_odf_connector.pdf>
=head1 Overview
The main goal of the Open OpenDocument Connector (OODoc) is to allow
quick application development in 2 areas:
- replacement of old-style, proprietary, client-based macros for intensive
and non-interactive document processing;
- direct read/write operations by enterprise software on office documents,
and/or document-driven applications.
OODoc provides an abstraction of the document objects and isolates the
programmer from low level XML navigation, UTF8 encoding and file
compression details. For example:
use OpenOffice::OODoc;
my $document = odfDocument(file => 'filename.odt');
$document->appendParagraph
(
text => 'Some new text',
style => 'Text body'
);
$document->appendTable("My Table", 6, 4);
$document->cellValue("My Table", 2, 1, "New value");
$document->save;
The script above appends a new paragraph, with given text and style, and
a table with 6 lines and 4 columns, to an existing document, then inserts
a value at a given position in the table. It takes much less time than the
opening of the document with your favourite text processor, and can be
executed without any desktop software connection. A program using this
library can run without any OpenOffice.org installation (and, practically,
OODoc has been tested on platforms where OpenOffice.org is not available
yet).
More generally, OpenOffice::OODoc provides a lot of methods (probably most
of them are not useful for you) allowing create/search/update/delete
operations with document elements such as:
- ordinary text containers (paragraphs, headings, item lists);
- tables and cells;
- user fields;
- sections;
- images;
- styles;
- bookmarks;
- bibliography entries;
- page layout;
- metadata (i.e. title, subject, and other general properties).
Every document processing begins by the initialization of an object
abstraction of the document. The most usual constructor for this object is
the odfDocument() function. When an object is initialized using this function,
it brings a lot of methods allowing allowing the application to retrieve,
read, update, delete or create almost every content and style element.
Another constructor, odfMeta() is available in order to allow metadata
processing (see below). These odfXxx() methods (and others) are shortcuts
for
OpenOffice::OODoc::Xxx->new(options)
where "Xxx" is generally "Document", for full access to the content, but
may be another specialized object such as "Manifest" or "Meta".
The long "OpenOffice::OODoc::...->new()" syntax can (and should) be avoided,
and replaced by the odfDocument(), odfMeta() or odfManitest() functions.
A document object initialization requires one or more options. The most
usual option is the file name, as in the first example. By default, this
parameter is regarded as a previously existing file. It's possible to
instantiate a document object with a new, empty document, with an
additional "create" option giving the content class of the document to
be generated. So, in our first example, the constructor could be:
my $document = odfDocument
(
file => 'filename.odt',
create => 'text'
);
This instruction creates a new file containing a text (i.e. an
OpenDocument Text) document (and replaces any previously existing file
with the same name). However, the new file will be actually created by the
$document->save instruction, not by the object initialization. If "create"
is set, the documents are generated according to ODF templates. By default,
OODoc uses a set of templates which are included in the CPAN package, but
it's possible to use custom templates instead.
When the 'create' option is in use, the newly created document may be
formatted either in the OASIS OpenDocument format (ODF) or in the primary
OpenOffice.org 1.0 format. If an additional 'opendocument' is provided and
set to 'true', then the new document will be ODF-compliant. If the same
option is present and set to 'false', the old OOo 1.0 format will be selected
instead. Without the 'opendocument' option, the format will depend on the
installation default (in the CPAN distribution, the default is set to
OpenDocument but it can be changed by the user at the install time). In the
other hand, the provided filename is not used by OODoc in order to
select the file format, so you are free to create an ODF file with
an OOo-like ".sxw" extension, and so on. The only one filename suffix that
is meaningful for OODoc is ".xml" (by default, a file whose name is like
"*.xml" is processed as flat XML and not as a regular, compressed ODF file).
For existing files, the format (ODF or OOo) is automatically detected
according to the real content of the file (whatever the filename).
The present version of OpenOffice::OODoc is based on the OpenDocument
specification, which has been published (May 2005) as an OASIS standard under
the following title:
"Open Document Format for Office Applications (OpenDocument) v1.0"
However, it works with ODF 1.1 documents as well.
=head1 Architecture
The OODoc toolbox is organized in 3 logical layers. It's not necessary for
you to remember the (annoying) details given in the next few paragraphs,
but these details are described only to explain the general organisation of
the modules. If you have only a few dozens of seconds for reading
this document, please jump directly at the part III (practical examples)
and come back later if you want to know more.
=head2 OpenDocument packaging
The first layer consists of the OpenOffice::OODoc::File class (defined in
the File.pm module). This class is responsible of read/write operations
with the ODF physical files. It does every I/O and
compression/uncompression processing. It's mainly an easy-to-use,
OpenDocument-oriented wrapper for the standard Archive::Zip Perl
module (but it could be extended to encapsulate any other physical
storage method for the ODF documents).
=head2 XML access
The second layer is made of the OpenOffice::OODoc::XPath class (XPath.pm), which
is an ODF/XML-aware class. This class is generally not directly used by
the applications; it's mainly a common ancestor for more specialised (and more
user-friendly) other classes. OpenOffice::OODoc::XPath is an object-oriented
representation of an XML part of an OpenDocument file
(ex: content.xml, meta.xml, styles.xml, etc.), using the XML::Twig
Perl API to access individual XML elements. It provides an XPath-based
syntax for advanced users who want to directly get or set any element or
attribute in any part of a document. If you want to deal in
the same time with several XML components of the same document, you
can/must create several OpenOffice::OODoc::XPath against the document (ex: one
OpenOffice::OODoc::XPath will be associated with 'meta.xml' to represent the
metadata, another one will be associated with 'content.xml' to give
access to the content. OpenOffice::OODoc::XPath accepts and provides only XML
strings from/to the application; but it's able to connect with an
OpenOffice::OODoc::File object for file I/O operation, so you can use it without
explicit file management coding.
For an example, if you want to get access to the content of any ODF file
(say 'foo.odt'), you have to write something like:
use OpenOffice::OODoc;
my $doc = odfXPath
(
file => 'foo.odt',
part => 'content'
);
then $doc becomes an abstraction of the 'content.xml' (i.e. the content
and automatic styles) of the 'foo.odt' file, that can be used to get/set
any content through simple methods like:
print $doc->getText('//text:p', 2);
The last instruction outputs the content of the 3rd paragraph as flat,
editable text (because '//text:p' is the XPath expression which selects all
the paragraphs in the current context, and the paragraphs are numbered from
zero). But don't worry about this XPath syntax, that is shown here in order
to explain the basic logic of the API.
You don't need to remember the path of such usual objects as paragraphs,
headings, lists, images, ..., and other well known document components, because
the 3rd layer (see below) provides easy-to-use, predefined accessors for these
objects.
You could also put your own text in the same paragraph with:
$doc->setText('//text:p', 2, 'My text');
The line above deletes any preceding content in the paragraph and replaces
it by 'My text'. But, for the moment, the paragraph is only changed in
memory; to commit the change and make it persistent in the OO file, you
have just to do a
$doc->save;
OpenOffice::OODoc::XPath allows some quick element manipulation and exchange,
and can operate on several documents in the same session. For example:
my $doc1 = odfXPath(file => 'file1.odt', part => 'content');
my $doc2 = odfXPath(file => 'file2.odt', part => 'content');
my $paragraph = $doc1->getElement('//text:p', 15);
$doc2->insertElement
('//text:h', 0, $paragraph, position => 'after');
This sequence takes an arbitrary paragraph (the 16th one) of a document
and inserts it just after an arbitrary heading (the first one) in another
document. Here, we used an 'insertElement' method to directly transfer
an existing text element, but the same method (with different arguments)
can create a new element according to application data, or from a well-
formed XML string describing any document element in regular OpenOffice
syntax. Example:
# a program
my $doc = odfXPath(file => 'file1.odt', part => 'content');
open MYFILE, "> transfer.xml";
print MYFILE $doc1->exportXMLElement('//text:p', 15);
close MYFILE;
# another program
my $doc2 = odfXPath(file => 'file2.odt', part => 'content');
open MYFILE, "< transfer.xml";
$doc2->insertElement
('//text:h', 0, <MYFILE>, position => 'after');
close MYFILE;
These last two short programs produce the same effect as the preceding one,
but the target file can be processed later than the source one and in a
different location, because there is no direct link in the two documents.
The first program exports an XML description of the selected element, then
the second program uses this description to create and insert a new element
that is an exact replicate of the exported one. In the meantime, the XML
intermediate file can be checked, processed and transmitted with any
language and protocol.
But it's just a beginning, because, in the real world, you have to do
much more sophisticated processing, and you have not a lot of time to
learn the XML path of any kind of document element (paragraph, heading,
item list, style, ...).
=head2 Document-oriented API
So there is a third, more user-friendly layer, that should be the only one
visible for most of the applications. The programmer should know the
features provided by the first layer (i.e. the XPath object) but should not
explicitly instantiate XPath objects, knowing that all these features are
inherited by more user-friendly objects.
The third layer is designed as a set of application-oriented
classes, inherited from OpenOffice::OODoc::XPath. In this layer, the basic
principle is "allow the user to forget XML". Each document element is
considered from the user's point of view, and the XML path to get it is
hidden. This approach works only if a specialized OpenOffice::OODoc::XPath
class is defined for each kind of content. So, we ultimately need the
following classes:
OpenOffice::OODoc::Text for the textual content of any document;
OpenOffice::OODoc::Image to deal with the graphic objects;
OpenOffice::OODoc::Styles for page/style definitions;
OpenOffice::OODoc::Meta for the metadata (meta.xml);
Fortunately, the 3 first ones should not be expressly used in real applications,
knowing that the toolbox provides a compound OpenOffice::OODoc::Document class
which inherits all their features. As a consequence, ordinary users have just
to deal with OpenOffice::OODoc::Document to process any content (graphic or
textual) or layout. An OpenOffice::OODoc::Document object is instantiated
through the odfDocument() function, that is a shortcut for
OpenOffice::OODoc::Document->new().
Simply put, a typical application will need OpenOffice::OODoc::Document in
order to process the content and the layout, and OpenOffice::OODoc::Meta for a
read/write access to the global properties.
However, the reference manual in organized according to the kind of features,
in order to avoid a huge manual page for the Document class. As a consequence,
the documentation of this compound class includes 4 chapters (::Text, ::Styles,
::Image and ::Document, the last one describing a few transverse methods. In
addition, the user should remember that all the low-level attributes and methods
described in the ::Xpath manual chapter are inherited by both ::Document and
::Meta.
The OpenOffice::OODoc::Text class brings some table processing methods
(table creation, direct access to individual cells). These methods, (under
some conditions) can be used with spreadsheets (ODF spreadsheet documents) as
well as with tables included in text documents.
To illustrate the differences between the layers, with the ::Text features of
a ::Document object, the two following instructions are equivalent:
print $doc->getText('//text:p', 2); # common ::XPath method
print $doc->getParagraphText(2); # ::Text (::Document) method
provided that $doc has been previously created through an odfDocument() call.
The difference looks tiny, but in fact OODoc::Text contains much more
sophisticated text-aware methods that avoid a lot of coding and probably
a lot of errors. For example, the following code puts the content of an
ordinary perl list (@mydata) in an OpenOffice document as an ordinary
item list:
my $list = $doc->appendItemList();
$doc->setText($list, @mydata);
The first instruction creates an empty list at the end of the document body.
The second one populates the new list with the content of an application-
provided table. The setText method automatically modify its behaviour
according to the functional type of its first argument (with is not the same
for a paragraph as for an itemlist or a table cell).
The same layer provides some global processing methods such as:
my $result = $doc->selectTextContent($filter, \&myFunction);
that produces a double effect:
1) it scans the whole document body and extracts the content of every text
element matching a given filter expression (that is an exact string or a
conventional Perl regular expression);
2) it triggers automatically an application-provided function each time a
matching content is found; the called function can execute any on-the-fly
search/replace/delete operation on the current content and get data from
any external database or communication channel; the return value
of the function automatically replaces the matching string.
So such a method can be used in sophisticated conditional fusion-
transformation scripts.
But you can use the same method to get a flat ASCII export of the whole
document, without other processing, if you provide neither filter nor
action:
print $doc->getTextContent;
Of course, OODoc can process presentation and not only content.
Example:
$filter = 'Dear valued customer';
foreach $element ($doc->selectElementsByContent($filter))
{
$doc->setStyle($element, 'Welcome')
if $element->isParagraph;
}
After this last code sequence, every paragraph containing the string 'Dear
valued customer' has the 'Welcome' style (assuming 'Welcome' is a paragraph
style, already defined or to be defined in the document).
A style (like any other document element) can be completely created by
program, or imported (directly or through an XML string) from another
document. The second way is generally the better because you need a lot
of parameters to build a completely new style by program, but the creation
of a simple style is not a headache with the OODoc::Styles module,
provided that you have an ODF attributes glossary at hand.
The following example show the way to build the "Welcome" style.
This piece of code declares "Welcome" as a paragraph style, whith
"Standard" as parent style, and with some private properties
(Times 16 bold font and navy blue foreground).
$doc->createStyle
(
"Welcome",
family => 'paragraph',
parent => 'Standard',
properties =>
{
'area' => 'text',
'style:font-name' => 'Times',
'fo:font-size' => '16pt',
'fo:font-weight' => 'bold',
'fo:color' => '#000080'
}
);
The color attributes are encoded in RGB hexadecimal format. It's possible
to use more mnemonic values or symbols, through conversion functions
provided by the Styles module, and optional user-provided colour maps.
For example, "#000080" could be replaced by odfColor('navy blue'), provided
that an appropriate color table is available at the run time; see
odfLoadColorMap() in the OpenOffice::OODoc::Styles manual chapter.
According to the application logic, each newly created style can be
registered either as a "named" style (i.e. visible and reusable through
a typical office software suite) or as an "automatic" style.
For an ordinary application that needs the best processing facility
for any kind of content and presentation element, the OODoc::Document
module is the best choice. This module defines a special class that
inherits from Text, Image and Styles classes. It allows the programmer,
for example, to simply insert a new paragraph, create an image object,
anchor the image to the paragraph, then create the styles needed to
control the presentation of both the paragraph and the image, all that
in the same sequence and in any order.
Caution: In order to get a convenient translation between the user's local
character set and the common ODF encoding (utf8), the application
must indicate the appropriate encoding. The default one is iso-8859-1 in the
CPAN distribution; it can be set using the odfLocalEncoding() function.
Example:
use OpenOffice::OODoc;
odfLocalEncoding 'iso-8859-15';
The default encoding can be selected by the user during the installation,
and changed later by editing a configuration file. In addition, a program
working with several documents in the same time can select a distinct
character set for each one.
=head1 Some practical uses
To begin playing with the modules, you should before all see the
self-documented sample scripts provided in the package. These scripts
do nothing really useful, but they show the way to use the modules.
You should directly load the full library with the single
"use OpenOffice::OODoc" in the beginning of your scripts.
Then you should only use (in the beginning) the Document and/or Meta
classes only. We encourage you, in the first time, to avoid any explicit
OODoc::XPath basic method invocation, and to deal only
with available "intelligent" modules (Text, Image, Styles, via Document,
and Meta), in order to get immediate results with a minimal effort.
And, if you use this stuff for evangelization purpose, you can show the
code to prove that the OpenDocument format allows a lot of things
with a few lines.
You can avoid the heavy object oriented notation such as:
my $meta = OpenOffice::OODoc::Meta->new(file => "xxx.ods");
and use the shortcuts like:
my $meta = odfMeta(file => "xxx.ods");
The first thing you have to do with a document is to create an object
focused on the member you want to work with, and "feed" it with regular
ODF XML. The most straightforward way to do that is to create the object
in association with an ODF file.
=head2 Dealing with metadata
We need metadata access, so we use OODoc::Meta
use OpenOffice::OODoc;
my $doc = odfMeta(file => 'myfile.odt');
my $title = $doc->title;
if ($title) { print "The title is $title"; }
else { print "There is no title"; }
Here, because the constructor of OODoc::Meta is called with a 'file'
parameter, OODoc::Meta knows it needs a file access and it dynamically
requires the OODoc::File module, instantiates a corresponding object using
the file name, connects to it, and asks it for the 'meta.xml' member of
the file. All that annoying processing is hidden for the programmer. We
have just to query for the useful object, the title.
In the same way, we could get (or even change) the document creation
or last modification date registered by the editing software:
my $d1 = $doc->creation_date;
my $d2 = $doc->date;
The dates, in the ODF documents properties, are stored in ISO-8601 format
(yyyy-mm-ddThh:mm:ss); this format is readable but not necessarily convenient
for any application. But the API provides easy to use tools allowing
conversion to or from the regular numeric time() format of the system,
allowing any kind of formatting or calculation.
We could get more complex metadata structures, such as the user defined
fields:
my %ud = $doc->user_defined;
foreach my $name (keys %ud)
{ print $name . '->' . $ud{$name} . "\n"; }
This code captures the user defined fields (names and values) in a hash
table, which then is displayed in a "name->value" form. You could see
the way to update the user defined fields in the 'set_fields' script,
provided with the distribution. The most usual metadata accessors have a
symmetrical behaviour. To update the title, for example, you have to call
the 'title' method with a string argument:
$doc->title("New title");
You can proceed in the same way with subject, description, keywords.
The 'keywords' is an example of polymorphic behaviour (which is quite
common for many OODoc methods):
my $keywords = $doc->keywords;
my @keywords = $doc->keywords;
In the first form, the keywords are returned concatenated and comma-
separated in a single editable text line. In the second one,
we get the keywords as a list. But if 'keywords' is called to add new
keywords, these ones must be provided as a list:
$doc->keywords("kw1", "kw2", "kw3");
$doc->keywords(@my_keywords);
The program is automatically prevented from introducing redundancy in
the keyword list (the 'keywords' method deletes duplicates). While
'keywords' can only add new keywords, you have to call removeKeyword to
delete an existing keyword. If you want to destroy the entire list of
keywords in a single call, you have just to write:
$doc->removeKeywords;
Well, we have done some updates in the metadata, but these updates
apply only in memory. To make it persistent in the file, we have just
to issue a:
$doc->save;
I said OODoc::Meta (which is an OODoc::XPath) did not know anything about
the OpenDocument compressed files. But in my example,the object has been
created with a 'file' argument and associated with an implicit
OODoc::File object. So, the 'save' method of OODoc::XPath is only a
stub method which sends a 'save' command to the connected OODoc::File
object. With an object created with an 'xml' parameter (providing
the metadata through an XML string, without reference to a file), a
'save' call generates a 'No archive object' error. However, if the object
had been created from an XML flat file (instead of a regular
ODF compressed file), the output would be a flat XML file as well.
Note: A document is always saved in the same file format as it's source.
The save() can't act as a format converter. So, you can't save an OOo 1.0
file in OASIS OpenDocument format and vice versa, and you can't directly
(without intermediate processing) save in ODF compressed format a document
loaded from XML data. However, thanks to the getXMLContent() method, you can
write the flat XML to the standard output or a given file handle.
If you prefer to keep the original file unchanged, you can issue a
$doc->save('my_other_file.odt');
that produces the same thing as 'File/SaveAs' in your favorite office
software: if called with an argument, 'save' creates a new file
containing all the changed and unchanged members of the original
one.
Of course, whatever the way you will use (or not use) the save() method,
you will never process valuable documents without a backup copy...
=head2 Example 2 - Manipulating text
Here we must read and update some text content elements. By "text content",
we mean not only "flat text". While the most interesting module is named
OpenOffice::OODoc::Text, it's not fully dedicated to text documents.
It can deal with the text content of presentations, as well as the
sheets and cells of a spreadsheet.
Our program begins with something like that:
use OpenOffice::OODoc;
my $doc = odfDocument(file => 'myfile.odt');
The second line produces an OpenOffice::OODoc::Document object, which
inherits from O::O::Text, O::O::Image and O::O::Styles. However, in the
present example, we'll use its O::O::Text features only.
To give a very high level abstract, we can say that OODoc::Text provides
2 kinds of read access methods:
- the 'get' methods that return data referred by unconditional
addressing, like getParagraph(4);
- the 'select' methods that return data selected against a given filter,
related to a text content or an attribute value, like
selectParagraphsByStyle('Text body').
Some 'get' or 'select' methods return lists while other return individual
elements or values.
Returned data may be elements or texts. Text data can be exported or
displayed, but the application needs elements to do any read/write
operation on the content. For example:
my $text = $doc->getTextContent;
extracts the whole content of the document as a flat, editable text in the
local character set, for immediate use (or display on a dumb terminal).
Of course, there are more the one way to do the same thing, so you can
get the same result with a 'select' method as with a 'get' one if you use
a "non-filtering filter". So:
my $text = $doc->selectTextContent('.*');
will also return the whole text content. But this last method, with some
additional arguments and an appropriate filter, is much more powerful,
because it can do 'on-the-fly' processing in each text element matching
the filter (for example, insert values extracted from an enterprise
database or resulting from complex calculations).
The output of getTextContent can be tagged according to the type of each
text element, so the application can easily use this method to export the
text in an alternative (simple) markup language.
To do some intelligent processing in the text, we need to deal with
individual text objects such as paragraphs, headings, list items or table
cells. For example, to export the content of the 5th paragraph (paragraph
numbering beginning with 0), we could directly get th text with:
my $text = $doc->getParagraphText(4);
But in order to update the same paragraph, or change its style, I need
the paragraph element, not only its text content:
my $para = $doc->getParagraph(4);
# text processing takes place here
$doc->setText($para, $other_text);
$doc->setStyle($para, $my_style);
Some methods can dynamically adapt to the text element type they have
to process. For example, the getText method (exporting the text content
of a given text element), can return the content of many kinds of element
(paragraphs, headings, table cells, item lists or individuals list items).
In addition, any text content extracted with an high-level OODoc method is
transcoded in the local character set (UTF-8 issues are (we hope) hidden for
the application). Optionnally, the text output can be instrumented with
begin and end application-provided tags according to the element type (so
it's possible to export the text in an alternative, simple XML dialect, or
in LaTeX, or in an application-specific markup language).
In order to facilitate some kinds of massive document processing
operations, OODoc::Text provides a few high level methods that do
iterative processing upon whole sets of text elements. One example is
selectElementsByContent: this method looks for any text container matching
a given pattern (string or regular expression) and, each time an element is
selected, it executes an application-provided callback function. An example
of use is provided in the 'search' demo script, which selects any text
element in a document matching a given expression, and appends the selected
content as a sequence of paragraphs in another document.
The more usual methods have explicit names, and can be used without their
exhaustive documentation, provided that the programmer has a good
understanding of the general philosophy. Heading and paragraph manipulations
are quite simple. The situation is more complex with other text content such
as item lists, tables and graphics.
To get an individual list item, you must point to it from a previously
obtained list element:
my $item_list = $doc->getList(2);
my $item = $doc->getListItem($item_list, 4);
Here, $item contains the 5th item of the 3rd list of the document. The
content of the item could then be exported by a generic method such as
getText(), or processed using another method. Note that, if the application
doesn't need the $item_list object for any other use, it can directly get
the list item with the same method with a list number (instead of s list
object) as its first argument:
my $item = $doc->getListItem(2, 4);
=head2 Playing with tables and spreadsheets
Because the need of data capture within table structures is more evident,
there is a direct accessor to get any individual table cell:
my $value = $doc->getCellValue($table, $line, $col);
For example:
my $value = $doc->getCellValue(0, 12, 0);
This code example returns the value of the 1st cell of the 13th row of
the 1st table in the document. Note the 'cell value' is simply the text
content if the cell type is string; but if the cell type is any numeric
type, getCellValuereturns the content of the value attribute and ignores
the text. The first argument (the table) can be either the table number
(zero-based, according to its sequential position in the document) or the
logical table name (as it's get or set by the end-user with OOo Writer
or Calc).
A cell can be selected in a table using either it's numeric (row, column)
coordinates or a "spreadsheet-like" alphanumeric notation. So, the example
above could be written as
my $value = $doc->getCellValue(0, "A11");
Caution, in the classical spreadsheet notation, the column comes first
while it comes last in the numeric coordinates. In addition, knowing that
the numeric coordinates are zero-based, "A1" corresponds to (0,0). Finally,
remember that the alphanumeric coordinates must be provided in a single
string while numeric coordinates require two arguments.
This alphanumeric notation is probably more user-friendly for OOo Calc
documents, but it's allowed by OODoc whatever the document class: you can
use it with tables in text documents as well.
Caution: The direct cell addressing works only when the table XML storage
is "normalized", i.e. when every table object (row, column or cell) is
mapped to an exclusive XML element. The application program can easily
ensure this "normalization" thanks to the normalizeSheet() method, described
in the OpenOffice::OODoc::Text manual page. However, up to now, the tables
included in text document through OpenOffice.org Writer are normalized, so
they are immediately available for direct addressing. In the other hand,
with OpenOffice.org Calc spreadsheets, several contiguous objects are mapped
to a single XML element as long as they have the same content, the same type
and the same presentation. It's not an issue; it's a feature allowed by the
OpenDocument specification in order to save storage space, knowing that
typical large spreadsheets contain a lot of empty, or repetitive, cells. As
a consequence, several cells may be located at the same coordinates. The
normalizeSheet() method allows the application to define a safe area, sized
according to its needs, where the direct object addressing works whatever
the XML storage method in use.
The table-related methods can be used with spreadsheets (i.e. OOo Calc
documents) as well as with tables included in text documents. However,
before addressing cells in a spreadsheet document, a program must "declare"
the size of the used area in each target sheet (this requirement is due to
performance considerations, for Calc documents only).
You can also change the content of a cell:
$doc->updateCell($table, $line, $col, $value);
$doc->updateCell($table, $line, $col, $value, $string);
$doc->updateCell($cell, $value);
$doc->updateCell($cell, $value, $string);
The first form puts the $value in the target cell, assuming it's a string
cell or, if it's a numeric one, your choice is to put the same content
as the value and the displayable string. The second form (assuming the
target cell is numeric) provides independent content for value and string
(the programmer must know what (s)he does, for example in case of currency or
date cell). The 3rd and 4th forms do respectively the same things, but
use a previously obtained cell element in place of 3D coordinates (in
order to avoid unnecessary low-level XPath recalculation).
For a flat text (non-numeric) cell whose the reference is already available,
setText() produces the same result as updateCell():
my $cell = $doc->getCell($table, $row, $col);
$doc->setText($cell, "The text in the cell");
Both getCellValue() and updateCell() can be replaced by the cellValue()
shortcut, that is a read/write accessor to indivudual cells. So:
my $value = $doc->cellValue("Sheet4", "B12");
$doc->cellValue("Sheet1", "P5", $value);
copies a value from one cell to another one in another table.
In this intro, the cells are assumed to be text-only. Of course, the code
is more complex with numeric cells, because the program have to get or set
some additional information, according to its data type.
OODoc::Text allows the program to create a new table, using the appendTable
or insertTable method. The following example appends a new table with 8 lines
and 5 columns to the document.
my $table = $doc->appendTable("MyTable", 8, 5);
But this new table is (by default) a pure text table. It's possible to build
very sophisticated table structures, with an appropriate data type and a
special presentation for each cell. But, to complete this task, the
application must provide a lot of parameters. So, it's recommended to
avoid purely programmatic table construction, and to reuse existing table
structures and styles in template documents previously created with an
ODF compatible software.
=head2 Sections, subdocuments and hyperlinks
For sophisticated document structures, paragraphs and other text containers
may be included in sections. The API allows the applications to easily
create or retrieve sections, whith the getSection(), appendSection(),
and insertSection() methods. A given section may be either populated
with a local content or provided with an external link (file path or
URL) in order to include a subdocument. In addition, using lockSection()
and unlockSection(), the programs can control the end-user write protection
of any section.
The following example (working with OOo 2.0) appends to a master document a
new, write-protected section including a new document which can be reached
through an internet link:
my $url = "http://jean.marie.gouarne.online.fr/doc/oodoc_guide.odt";
$doc->appendSection
(
"Getting Started",
link => $url,
protected => "true"
);
And, if an unfortunate end-user is barred from updating a section by a lost
password, the programmer can help with a single line such as:
$doc->unlockSection($section_name);
Of course, a section can host any local content instead of an external link.
my $section = $doc->appendSection("Section 1");
$doc->appendParagraph
(
attachment => $section,
text => "The first paragraph in the section",
style => "Standard"
);
Here, a section is created and receives a paragraph as its first content.
An existing set of content elements could migrate under a section. The next
example, more sophisticated, selects the list of all the elements that
hierarchically depend on the first level 1 title of the document and moves
these elements to a given section:
my @content = $doc->getChapterContent(0, level => 1);
$doc->moveElementsToSection("Section 1");
The sections are not the only places for using hyperlinks. The applications
can associate hyperlinks to any portion of text. The following example puts
a remote (http) link on every "OpenDocument" character string in a given
paragraph:
$doc->setHyperlink
($para, "OpenDocument", "http://www.oasis-open.org");
The target of an hyperlink may be a bookmark or a heading in the current
document or in another ODF document. For example, if the target is a bookmark
included in the same document, the link is the name of the bookmark with a
leading "#":
$doc->setHyperlink($para, "a string", "#MyMark");
When the target is a heading (i.e. a hierarchical title), the link is made of
the text of the heading, prefixed with "#" and suffixed by "|outline".
If an hyperlink is aimed at any target belonging to another document (in the
local filesystem or elsewhere), you have just to concatenate the file path
and the internal path. The example below puts an hyperlink to a particular
heading located in a remote document:
$doc->setHyperlink
(
$para, "read the conclusion",
"http://somewhere.com/somewhat.odt#Conclusion|outline"
);
=head2 Manipulating variables, bibliographic entries, bookmarks
The OODoc toolbox provides easy read/write accessors to some useful objects
that can be included in OOo text documents.
If a text document contains a user-defined field, the corresponding value can
be read and updated. For example, if the user needs to increase a numeric
by a given value, the corresponding code could be:
$old_value = $doc->userFieldValue("FieldName");
$doc->userFieldValue("FieldName", $old_value + $added_value);
Any OpenDocument-compliant variable text field may be inserted in a document
through the textField() method. The next example appends a paragraph whose
text content is "This document contains <page-count> pages", knowing that
the real page count will be dynamically displayed by the office software:
my $p = $doc->appendParagraph
(text => "This document contains ");
$doc->appendElement($p, $doc->textField('page-count'));
$doc->extendText($p, " pages");
It's possible to get or set any property of a bibliography entry. An entry
can be selected by its identifier (as it appears for the end-user). The first
example below prints the title and the author of the first found occurrence
of a "[GEN99]" entry, while the second one creates (or updates) its "ISBN"
and "pages" properties:
# 1
my %properties = $doc->bibliographyEntryContent("GEN99");
print "Title = $properties{'title'}\n";
print "Author = $properties{'author'}\n";
# 2
$doc->bibliographyEntryContent
(
"GEN99",
isbn => 'xxxxyyyyzzzz',
pages => 254
);
In addition, a getBibliographyEntries() method allows the user to retrieve
the full list of the entries included in a document.
We can put a bookmark in a paragraph containing a given string.
Example:
my $paragraph = $doc->selectElementByContent("my search string");
$doc->setBookmark($paragraph, "MyMark");
The instruction above puts the mark at the beginning of the paragraph;
however, if an optional offset argument is provided, setBookmark() could
put the mark at any position within the text.
A bookmark (created either through OpenOffice::OODoc or through this Perl
API) can be used to retrieve a text element:
my $paragraph = $doc->selectElementByBookmark("MyMark");
=head2 Dealing with text AND metadata
Sometimes we must access both the text content and the metadata. So, we need
two OODoc::XPath objects : one OODoc::Document and one OODoc::Meta. And to
avoid collisions and inefficient I/O operations, we need to connect the 2
objects with the same OODoc::File "server".
use OpenOffice::OODoc;
my $archive = odfContainer('myfile.odt');
my $content = odfDocument(container => $archive);
my $meta = odfMeta(container => $archive);
# process content and metadata
$archive->save;
In this case, the OODoc::Document and OODoc::Meta objects are created with
a 'container' parameter, so they are required to connect to an existing
OODoc::File object. After processing, a 'save' call directly addressed
to the OODoc::File is sufficient to do the physical file update, because
this object "knows" the list of the OODoc::XPath objects connected to it,
and "asks" to each of them the XML content it's responsible of (the other
XML members of the file remain unchanged).
In the example above, if the user writes 'file' instead of 'container', the
API automatically detects the real type of the $archive value (i.e. an
OODoc::File object) and adapts its behaviour accordingly. So, one can use
the 'file' option either if the parameter is really a file path/name or if
it's a reference to a previously instantiated ODF package.
However, the explicit use of OODoc::File is not mandatory. The example above
could be written in a different way:
use OpenOffice::OODoc;
my $content = ooDocument(file => 'myfile.odt');
my $meta = ooMeta(file => $content);
# process content and metadata
$content->save;
This last sequence sounds strange because the 'file' option of ooMeta()
is an OODoc::Document (i.e. an OODoc::XPath object) and not a file. But
OpenOffice::OODoc encourages your laziness: if the value type of the
'file' option is OODoc::XPath (and neither a file path nor an OODoc::File
object), it knows you want share a file interface already used. So you get
the same result as in the previous example, but the common OODoc::File object
is not visible. The final save() could be issued from anyone of the document
objects.
There is an example of simultaneous access to content and metadata in the
script 'set_title' (where some text content is used to generate a piece
of metadata).
=head2 Manipulating graphics
The module OODoc::Image brings some functionalities that can be used
against any OO document. The following code (combining the capabilities
of OODoc::Text and OODoc::Image) selects the first paragraph containing
the string "OpenOffice" and attach an imported image to it.
my $p = $doc->selectElementByContent("OpenOffice");
die "Paragraph not found" unless $p;
$doc->createImageElement
(
"Paris landscape",
description => "Montmartre in winter",
attachment => $p,
import => "C:\MyDocuments\montmartre.jpg",
size => "5cm, 3.5cm",
style => "graphics2"
);
In a spreadsheet document, the same image could be attached to a cell
instead of a paragraph; to do so, the "attachment" option should be set
to a cell element, previously obtained using getCell(). With the same syntax,
in a presentation document, the "attachment" should be a draw page, previously
selected using getDrawPage(). A "page" option allows the user to anchor an
image to a page, instead of attaching it to a text container.
In this example, the image is physically imported. But I could replace the
"import" parameter by a "link" one, in order to use the image as an external
link (cf. the "link" option when you insert an image in OpenOffice.org). This
link could use a local filesystem path as well as a remote access path such
as "http://...".
My new image needs a style (called "graphics2" in my example) to be presented.
This style could be an existing one, but my program could create it if
needed, using an OODoc::Styles method (see below).
Any characteristic of an existing image can be read or updated using simple
methods. For example, it's easy to change the size and the position of my
image:
$doc->imageSize("Paris landscape", "10cm, 7cm");
$doc->imagePosition("Paris landscape", "3cm, 0cm");
The size and position strings indicate the used length unit. OODoc doesn't
the provided unit, so the application should ensure that only ODF-compliant
units are used. Possible units are, for example, "cm" (centimeter), "mm"
(meter), "in" (inch), "pt" (point).
The logical name of the image (here "Paris landscape") is the best way to
retrieve an image object, so it's a mandatory argument with the
createImageElement method. With OpenOffice.org Writer, each image is created
with an unique name (that is "Image1", "Image2", etc. if the user doesn't
provide a more significant one). But with OpenOffice.org Impress, the images
are unnamed by default. We recommend you to give a significant name to each
object that you want to process later by program, knowing that if an object
can be easily caught by program, it's potentially reusable.
An image can be selected by his description (i.e. the text the end-user
can edit in the image properties dialog in OpenOffice.org). So, the following
sequence provides the list of images whose the description contains the string
"Montmartre":
my @images = $doc->selectImageElementsByDescription("Montmartre");
If you have to store and process a graphical content out of the end user's
editing software, you can export it as an ordinary file:
$doc->exportImage("Paris landscape", "/home/pictures/montmartre.jpg");
And you can use a symmetric importImage method to change the content of an
image element.
=head2 Managing styles
The OODoc::Styles allows the programmer to get any style definition, to change
it and, if really needed, to create new styles. In the first part of this
document, you can see an example of paragraph style creation. Unfortunately,
createStyle could drive you to heavy coding efforts, because a very
sophisticated style definition needs a lot of parameters and requires the
knowledge of a lot of ODF attribute names. So we recommend you to
systematically reuse existing styles (stored in ODF template documents used as
"style repositories" or in XML databases). The createStyle method supports
a "prototype" parameter that allows you to clone an existing style, contained
in the same document or in another one.
The next code sequence selects the "Text body" style of a document, and uses
it as a template to create a "My Text body" style in another document,
changing the font size only:
my $template = $doc1->getStyleElement("Text body");
$doc2->createStyle
(
"My Text Body",
family => "paragraph",
prototype => $template,
properties =>
{
"area" => "text",
"fo:font-size" => "12pt",
"fo:color" => odfColor("dark blue")
}
);
Here a "dark blue" color has been given to the text; but "dark blue" is
an arbitrary string, that must be present in a user-provided, previously
loaded color map; without this color map, the users must, at their choice,
either directly provide an hexadecimal, six-digit color code, with a leading
"#" (such as "#00008b", that is the translation of "dark blue" in my
installation), or get it through the odfColor() function with 3 decimal RGB
values as arguments.
Because a style is required for each image in a document, the OODoc::Document
brings a more user-friendly createImageStyle method. This method allows you
to create an image style without any mandatory parameter (excepted the name).
So, the "graphics2" style I invoked in a previous createImage example could
be simply created by:
$doc->createImageStyle("graphics2");
Without other indication, the module automatically creates a style with
"reasonable" values, so the image is really visible in the document. Of
course, the application could provide explicit values for some parameters
if needed. The following call, for example, provides specific values for
contrast, luminance and gamma correction:
$doc->createImageStyle
(
"graphics2",
properties =>
{
'draw:contrast' => '2%',
'draw:luminance' => '-3%',
'draw:gamma' => '1.1'
}
);
Styles are not made only to control the presentation of individual elements.
There are special styles for page layout. While these styles are described
with very specific data structures, the OODoc::Styles module contains
some methods dedicated to page styling.
=head2 Dealing with styles AND content
While the OpenOffice::OODoc::Document methods can process both the content
(text, complex structures and graphics) and the styles, it's not always
possible any style and any content through the same object in the same session.
Each individual instance of ::Document wraps an indivudual part of an ODF
package. The default part is "content.xml", but all the named style definitions
are stored in the "styles.xml" part (in a few words, a named style is a style
which was designed in order to be used by more than one content element; for
example, any style which could be selected through the style dialog box of a
typical user-oriented office software is a "named" style).
In order to avoid a lot of useless XML parsing, only one part at a time is
loaded. As a consequence, if the application needs to process content and
named styles during the same session, it must create 2 instances of
::Document objects, associated with the same ODF container. Each instance must
be associated with the appropriate target. For example:
use OpenOffice::OODoc;
my $archive = odfContainer('myfile.odt');
my $content = odfDocument
(
container => $archive,
part => 'content'
);
my $styles = odfDocument
(
container => $archive,
part => 'styles'
);
After this sequence, the $styles object gives access to any named style while
all the document body can be processed through the $content object. Note that
in this last example, we could avoid the "part" option for the "content"
member of the package (because "content" is the default).
Knowing that its always possible to process content, named styles and
metadata in the same session, we could instantiate a ::Meta object through
odfMeta() as well. So up to 3 connecting objects can be used as interfaces
for the same ODF file.
Of course, a single $archive->save() can make all the changes made through all
the connected objects persistent.
=head1 COMMENTS AND BUG REPORTS
Comments, questions and answers are welcome through the CPAN forum
L<http://www.cpanforum.com/dist/OpenOffice-OODoc>
Bug reports should be sent using
L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=OpenOffice-OODoc>
=head1 AUTHOR/COPYRIGHT
Developer/Maintainer: Jean-Marie Gouarne L<http://jean.marie.gouarne.online.fr>
Contact: jmgdoc@cpan.org
Copyright 2004-2008 by Genicorp, S.A. L<http://www.genicorp.com>
Initial English version of the reference manual by Graeme A. Hunter
(graeme.hunter@zen.co.uk).
License: GNU Lesser General Public License v2.1
=cut