Provided by: libopenoffice-oodoc-perl_2.125-3_all bug


       OpenOffice::OODoc::Intro - Introduction to the Open OpenDocument Connector


       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) <>

       There is an alternative intro for french-reading users. It's available in ODT
       (<>) or PDF
       (<>). In addition, a general
       presentation in French can be downloaded at


       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');
                               text    => 'Some new text',
                               style   => 'Text body'
               $document->appendTable("My Table", 6, 4);
               $document->cellValue("My Table", 2, 1, "New value");

       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 installation (and, practically,
       OODoc has been tested on platforms where 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


       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 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.


       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
       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');

       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");

       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 (, 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

       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

               $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:

                       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

               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'
                       text            => "Hello World !",
                       attributes      => {
                               'style name'    => "Text Body Style"

       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);
                       ('//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";
                       ('//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

       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

       To illustrate the differences between the layers, the two following instructions are

               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

       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

       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).

                               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

       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

       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

       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");

       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:


       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:


       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


       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

       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

               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 Writer are normalized,
       so they are immediately available for direct addressing. In the other hand, with 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

       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

               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 = "";
                       "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:


       Of course, a section can host any local content instead of an external link.

               my $section = $doc->appendSection("Section 1");
                       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:

                       ($para, "OpenDocument", "");

       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

                       $para, "read the conclusion",

   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:

                       $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
                               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 (
                               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

                       $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

               use OpenOffice::OODoc;
               my $archive     = odfContainer('myfile.odt');
               my $content     = odfDocument(container => $archive);
               my $meta        = odfMeta(container => $archive);
               # process content and metadata

       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;
                       "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

       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 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 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 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 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

               my $template = $doc1->getStyleElement("Text body");
                               "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:


       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:

                               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"

       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, questions and answers are welcome through the CPAN forum

       Bug reports should be sent using


       Developer/Maintainer: Jean-Marie Gouarne <>


       Copyright 2004-2010 by Genicorp, S.A. <>

       Initial English version of the reference manual by Graeme A. Hunter

       License: GNU Lesser General Public License v2.1