OODoc::Intro(3pm) User Contributed Perl Documentation OODoc::Intro(3pm)
NAME
OpenOffice::OODoc::Intro - Introduction to the Open OpenDocument
Connector
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)
<http://www.theperlreview.com>
There is an alternative intro for french-reading users. It's available
in ODT (<http://jean.marie.gouarne.online.fr/doc/oodoc_guide.odt>) or
PDF (<http://jean.marie.gouarne.online.fr/doc/oodoc_guide.pdf>). In
addition, a general presentation in French can be downloaded at
<http://jean.marie.gouarne.online.fr/doc/perl_odf_connector.pdf>
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"
It works with ODF 1.1 and 1.2 documents as well, knowing that these
newer versions use the same basic data structure as 1.0, and
(hopefully) this library doesn't depend on any particular feature which
could be removed from the specification.
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.
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).
Every physical access to a document through the OpenOffice::OODoc API
requires the use of one or more "connectors", each one being associated
to an ODF "container". The appropriate constructor is the
odfContainer() function, which requires a file name/path as its first
(and mandatory) argument:
my $resource = odfContainer("myfile.odt");
The instruction above creates an instance of ODF container, associated
to a given filename. The returned object (assuming the specified file
exists and is readable) is an OpenOffice::OODoc::File instance, i.e. an
abstraction of the ODF physical file. However, it's possible to
associate a container with an ODF that doesn't exist yet, provided that
an additional 'create' named parameter, whose value is the class of the
new document, is set. The following example creates an instance of
spreadsheet ODF package:
my $container = odfContainer("accounts.ods", create => 'spreadsheet');
Note that no persistent resource is created at this time. Without the
'create' option, the odfContainer() function attempts to load the
structure of the specified ODF file (and fails if something is wrong).
With the 'create' option, the structure is loaded in memory according
to defaut ODF templates that belong to the OpenOffice::OODoc
installation. But any persistent change (including the creation of the
new ODF file, if any) requires the save() method. As an example, the
following code really created a new ODF presentation file (without
content):
my $container = odfContainer("show.odp", create => 'presentation');
$container->save;
Or, more concisely:
odfContainer("show.odp", create => 'presentation')->save;
So, the most minimalistic OpenOffice::OODoc application is a one-liner
that creates an empty document.
For an existing resource, an open IO::File is allowed instead of a file
name.
Once initialized, such a container is typically used as a basis to
instantiate one or more document-oriented connectors using
odfDocument(), introduced later. However, for the users who know
exactly what they do, an ODF container brings some low-level methods,
such as physical export and/or import of document parts. The next
example exports all the named persistent styles of "doc1.odt" then
imports them in "doc2.odt":
my $p1 = odfContainer("doc1.odt");
my $p2 = odfContainer("doc2.odt");
$p1->raw_export("styles.xml");
$p2->raw_import("styles.xml");
$p2->save;
Caution: there is no consistency check with raw_import(), so the
application may ensure that the imported part makes sense according to
the remainder of the target container (so, in this example, it may
ensure that all the styles needed in the document content are
conveniently defined in the imported part). Note that the raw_import()
method doesn't produce any persistent effect before the save() method
is issued from the importing container. All the changes are lost if the
program ends or the objects goes out of scope before save().
XML access
An OpenOffice::OODoc::File object which has been instantiated using
odfContainer(), it becomes available for processing through document-
oriented, XML-based connectors. A typical OpenOffice::OODoc user
doesn't need to be really "XML-aware", and most applications will
probably use the high-level, XML-free methods provided by the Document
and Meta objects, introduced later. However, the present section could
prove useful for the general knowledge of the API.
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 $container = odfContainer("foo.odt");
my $doc = odfDocument
(
container => $container,
part => 'content'
);
then $doc becomes an abstraction of the 'content' part of the document
(corresponding to the document body and some automatic styles). This
new object brings a lot of methods allowing the applications to
retrieve, read, modify, delete and creates elements in the documents.
An element is a consistent piece of content or style definition. Any
element may contain a text and/or one or more attributes. As an
example, the following example selects a paragraph, then gets its text
content and the name of its style:
my $element = $doc->getElement('//text:p', 2);
my $text = $doc->getText($element);
my $style = $doc->getAttribute($element, 'style name');
Note that the getElement() method works with XPath expressions.
According to the ODF specification, "text:p" specifies a paragraph. The
double slash ("//") means "everything from the root of the document".
The second argument of getElement() is the position of the needed
element in the list (knowing that "//text:p" designates all the
paragraphs); this position is zero-based, so in this example the third
paragraph is selected. The search space of getElement() is the whole
document by default, but it's possible to restrict it to a given
context, specified through a additional argument. A context is a
particular element, previously selected. As an example, the following
code selects the 3rd paragraph in the 4th section (if any):
my $section = $doc->getElement('//text:section', 3);
my $paragraph = $doc->getElement('//text:p', 2, $section);
(Of course, there is a getSection() method that allows you to forget
the XPath expression and to retrieve a section by name instead of
number.)
In a real application, the user doesn't need to known such an XPath
expression, because there is a more convenient getParagraph() method
that just requires the paragraph number. However, the generic, XPath-
based getElement() method remains available in order to retrieve any
element that is not covered by a specialized accessor.
The getText() method is self-documented in the example. The
getAttribute() method requires, after the element itself, the name of
the attribute whose value is needed. The real ODF name of the style
attribute of a paragraph is "text:style-name"; however, the application
may use the "style name" simplified form knowing that getAttribute() is
able to translate the attribute names according to a simple logic:
every space in the given name is replaced by a "-" and, if no prefix is
specified, the prefix of the element itself is used, so "style name" is
automatically interpreted as "text:style-name" in this particular
context.
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.
The text content and the attributes of a selected element may be
changed. The following sequence puts a new text content and affects a
new style to our previously selected paragraph:
$doc->setText($element, "A new text content");
$doc->setAttribute($element, 'style name' => "Text Body Style");
The same layer of the API allows one to append of insert new elements.
The next example demonstrates the use of appendElement(); it creates a
new paragraph with given text and style and appends it to the existing
content:
$doc->appendElement(
'text:p',
text => "Hello world",
attributes => {
'style name' => "Text Body Style"
}
);
For those who hate complex instructions, the 3 lines below do the same
job as the example above:
my $new_element = $doc->appendElement('text:p');
$doc->setText($new_element, "Hello world");
$doc->setAttribute($new_element, 'style name' => "Text Body Style");
Remember that the changes above are done in the volatile content of
document object; up to now; nothing is changed in the corresponding
file. In order to commit the changes and make them persistent, we need
to call the save() method of the container that has been used to
instantiate the document.
The API allows the user, in simple situations, to "forget" the ODF
container behind the document. The following "hello world" example,
that creates and saves a new document, works without explicit use of
the odfContainer() constructor:
my $doc = odfDocument(
file => "foo.odt",
create => 'text',
part => 'content'
);
$doc->appendElement(
'text:p',
text => "Hello World !",
attributes => {
'style name' => "Text Body Style"
}
);
$doc->save;
Note that odfDocument() is used here with a 'file' parameter, whose
value is a file name, instead of a 'container'. At the end, save() is
called from the document instance itself instead of a container.
However, a container is always instantiated, but it's just hidden; and
save() is only a stub method, the real job being done by the save()
method of the container. Such a shortcut is useful in this example
because the program processes one part only, i.e. the content; for
applications that uses more than one part (content, styles, meta-
data), two or more document connectors must be instantiated in
association with the same container connector, and, as a consequence,
the explicit use of odfContainer() is recommended.
OpenOffice::OODoc::XPath allows some quick element manipulation and
exchange, and can operate on several documents in the same session. For
example:
my $doc1 = odfDocument(file => 'file1.odt', part => 'content');
my $doc2 = odfDocument(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 immediately 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 Open Document syntax. Example:
# a program
my $doc = odfDocument(file => 'file1.odt', part => 'content');
open MYFILE, "> transfer.xml";
print MYFILE $doc1->exportXMLElement('//text:p', 15);
close MYFILE;
# another program
my $doc2 = odfDocument(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.
The OpenOffice::OODoc::XPath manual page describes a lot more common
features that may be used through the document-oriented API introduced
below.
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, table, draw frame, style, ...).
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 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(). For other parts, such as the
metadata or the file manifest, other constructors are available.
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, the two following
instructions are equivalent:
print $doc->getText('//text:p', 2);
print $doc->getParagraphText(2);
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 ODF document as an
regular 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.
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.
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...
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 the 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). Optionally, 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);
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.
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"
);
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);
In addition, the OODoc API allows the user to "declare" new user-
defined fields if needed (see setUserFieldDeclaration() in
OpenOffice::OODoc::XPath).
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");
While the sequence above appends a text field at the end of a
paragraph, the setTextField() method may insert a text field anywhere
within an existing paragraph according to various positioning
parameters. The example hereafter creates a date field immediately
after the last occurrence of the substring "the current date is "; the
'after' option provides the search string while the 'way' option
specifies that it must be searched backward:
$doc->setTextField(
$paragraph, 'date',
after => "the current date is ",
way => 'backward'
);
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.
An additional bibliography entry may be inserted within a paragraph
using setBibliographyMark(). As an example, the following instruction
inserts a new bibliography mark as a replacement of the first substring
"reference needed" that may occur after the 20th character in a given
paragraph:
$doc->setBibliographyMark (
$paragraph,
offset => 20,
replace => "reference needed",
attributes => {
identifier => "JDE",
title => "OASIS OpenDocument Essentials",
author => "J. David Eisenberg",
year => 2005,
isbn => "1-4116-6832-4"
}
);
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, setBookmark() could put the mark at any position within the
text, according to optional parameters. To illustrate the positioning
logic, the following instruction puts the bookmark immediately after
the first occurrence of "xyz" that appear after the first 20
characters:
$doc->setBookmark(
$paragraph, "MyMark",
offset => 20,
after => "xyz"
);
Note that there are many possible positioning parameter combinations
for bookmarks and any other markup elements intended to be inserted
within text containers; the various possibilities are inherited from
the setChildElement() method, that is described in the
OpenOffice::OODoc::XPath manual page.
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");
Note that the insert position of text fields, bibliography marks,
bookmarks, and other markup elements may be specified using the same
set of position parameters and according to the same logic, that are
inherited from the common setChildElement() method, described in
OpenOffice::OODoc::XPath.
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 $content and $meta are explicitly linked to a common
container. As a consequence, when the save() method of this container
is triggered, all the changes through them are made persistent.
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).
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.
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.
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 persistent all the
changes made through all the connected objects.
COMMENTS AND BUG REPORTS
Comments, questions and answers are welcome through the CPAN forum
<http://www.cpanforum.com/dist/OpenOffice-OODoc>
Bug reports should be sent using
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=OpenOffice-OODoc>
AUTHOR/COPYRIGHT
Developer/Maintainer: Jean-Marie Gouarne
<http://jean.marie.gouarne.online.fr>
Contact: jmgdoc@cpan.org
Copyright 2004-2010 by Genicorp, S.A. <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
perl v5.34.0 2022-06-16 OODoc::Intro(3pm)
Generated by dwww version 1.15 on Wed Jun 26 05:45:21 CEST 2024.