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


       OpenOffice::OODoc - The Perl Open OpenDocument Connector


               use OpenOffice::OODoc;

                               # get global access to the content of an ODF file
               my $document = odfDocument(file => "MyFile.odt");
                               # select a text element containing a given string
               my $place = $document->selectElementByContent("my search string");
                               # insert a new text element before the selected one
               my $newparagraph = $document->insertParagraph
                               position        => 'before',
                               text            => 'A new paragraph to be inserted',
                               style           => 'Text body'
                               # define a new graphic style, to display images
                               # with 20% extra luminance and color inversion
                               properties      =>
                                       'draw:luminance'        => '20%',
                                       'draw:color-inversion'  => 'true'
                               # import an image from an external file, attach it
                               # to the newly inserted paragraph, to be displayed
                               # using the newly created style
                               style           => "NewImageStyle",
                               attachment      => $newparagraph,
                               import          => "D:\Images\Landscape.jpg"
                               # save the modified document


       This toolbox is an extensible Perl interface allowing direct read/write operations on
       files which comply with the OASIS Open Document Format for Office Applications (ODF), i.e.
       the ISO/IEC 26300:2006 standard.

       It provides a high-level, document-oriented language, and isolates the programmer from the
       details of the file format. It can process different document classes (texts,
       spreadsheets, presentations, and drawings).  It can retrieve or update styles and images,
       document metadata, as well as text content.

       OpenOffice::OODoc is designed for data retrieval and update in existing documents, as well
       as full document generation.


       The present chapter, then the OpenOffice::OODoc::Intro one, should be read before any
       attempt to dig in the detailed documentation.

       The reference manual is provided in several separate chapters as described below.

       The OpenOffice::OODoc documentation, as the API itself, is distributed amongst several
       manual pages on a thematic and technical basis. The present section is a general foreword.

       Each manual page corresponds to a Perl module, with the exception of
       OpenOffice::OODoc::Intro. It's strongly recommended to have a look at the Intro before any
       other manual chapter, in order to get a quick and practical knowledge of the big picture.
       Another possible introductory reading has been published in The Perl Review (issue #3.1,
       dec. 2006) <>, while an alternative presentation article,
       intended for French-reading users, can be downloaded at

       The API is object-oriented and, with the exception of the main module (OpenOffice::OODoc
       itself), each module defines a class. The features of each module are documented in a
       manual page with the same name. But, while some classes inherit from other ones, they
       bring a lot of features that are not documented in the corresponding manual page. The best
       example is OpenOffice::OODoc::Document: it contains a few method definitions by itself,
       but it's the most powerful class, because it inherits from four other classes, so its
       features are documented in five manual pages. Fortunately, the classes are defined on a
       functional basis. So, for example, to know the text-related capabilities of a Document
       object, the user should select the Text manual page before the Document one.

       The detailed documentation of the API is distributed according to the following list:

       The present manual page contains (in the GENERAL FUNCTIONS section below) the description
       of a small number of miscellaneous functions, dedicated to control some general
       parameters, to create the main objects of the applications, or to provide the user with
       some basic utilities. It introduces the main object constructors, namely odfContainer(),
       odfDocument() and odfMeta().

       This manual page contains detailed information about the physical access to the ODF
       containers, i.e. the multipart, compressed files that contain the documents.

       In some simple applications, this page can be ignored without risk.

       It describes all the common features, that are provided by the corresponding class, and
       available in every other class with the exception of OODoc::File.  This page is so called
       because it essentially relies on XPath expressions to select the various document
       elements. However, beyond the XPath-based retrieval features, it allows the user to
       update, create, or delete any element.

       This manual page describes the common XML toolbox of OpenOffice::OODoc. It allows almost
       everything, and it may be appropriate for XML- and XPath-aware users who have some
       knowledge of the Open Document Format. On the other hand, it covers only the low level
       part of the API.

       The high level part of OpenOffice::OODoc is covered by the ::Text, ::Image, ::Styles,
       ::Document and ::Meta manual chapters. However, the user should remember that ::XPath
       describes some common features which are not redundantly documented in the high level
       chapters , so this manual page can be useful even if the user don't need to work with
       explicit XPath expressions.

       Note: by "high level", I don't suggest that OpenOffice::OODoc provides any stratospheric
       functionality. The "high level" API is a set of frequently needed features that are
       implemented in order to be used without knowledge of the ODF storage structure and without
       XML familiarity. The following example, that retrieves a section in a text document
       according to its name, illustrates the difference: while both return the same result, the
       second instruction, which is mnemonic and largely self-documented, belongs to a higher
       level than the first one:

               $section = $doc->getElement('//text:section[@text:name="Foo"]');
               $section = $doc->getSection("Foo");

       This manual page describes all the high level text processing methods and allows the
       user's program to deal with all the text containers (headers, paragraphs, item lists,
       tables, and footnotes). OpenOffice::OODoc::Text is dedicated to the text content and
       structure of any kind of document, and *NOT* to the so-called "text documents". As a
       consequence, this chapter describes all the methods which process ODF text containers in
       spreadsheets and presentations as well as in text documents.

       The set of covered text objects includes all the markup elements that may be inserted
       within paragraphs, such as variable text fields, notes, bibliography entries, bookmarks,
       index entries, text runs with special styles, hyperlinks, etc.

       Whatever the document class, the ::Text part of OpenOffice::OODoc may apply to some style
       definitions, too. For example, a page style may specify a header and/or a footer that may
       contain paragraphs and other text elements.

       This manual page describes all the graphics manipulation API, i.e. all the available
       syntax dedicated to insert or remove images in the documents, and to control the
       presentation of these images.

       Note that OpenOffice::OODoc does *NOT* include any graphical processing API; it just deals
       with the Open Document way to include and display images. It allows, for example, to
       control the color correction and the display size of an image in the context of a
       particular document, but not to change the image itself.

       This manual page describes the methods to be used to control the styles of a document,
       knowing that each page layout, each text element, and each image is displayed or printed
       according to a style. This part of the documentation can be ignored if the user's programs
       are strictly content- focused and don't care with the presentation.

       Note that some style definitions, such as master pages, can include text containers or
       images, which can be processed through methods provides by OpenOffice::OODoc::Text or

       This manual page describe some miscellaneous methods that deal simultaneously with text,
       presentation and/or images. So, in order to discover the capabilities of a "Document"
       object (created with ooDocument), the user should use the Text, Image, Styles AND Document
       manual pages. The OpenOffice::OODoc::Document class inherits all the features provided by
       the other classes with the exceptions of OpenOffice::OODoc::File and

       This manual page describes all the available methods to be used in order to control the
       global properties (or "metadata") of a document. Most of these properties are those an
       end-user can get or set through the "File/Properties" command with the
       desktop software.

       This manual page describes the manifest management API, knowing that the manifest, in an
       ODF file, contains the list of the file components (or "members") and the media type (or
       MIME) of each one. The text content, the style definitions, the embedded images, etc. are
       each one stored as a separate "member".



               Synonym: odfDocument()


               Shortcut for OpenOffice::OODoc::File->new().

               This function returns a File object, that is the object representation
               of the physical package containing the text, the images and the style
               definitions of an ODF document.

               See the OpenOffice::OODoc::File manual page for detailed syntax.
               See the OpenOffice::OODoc::Intro manual page to know why, in some
               situations, the using applications need or don't need to deal with
               explicit File objects.

               Synonyms: odfFile(), odfPackage().


               Returns the translation of a raw ODF (UTF-8) string in the local character
               set. While the right translation is automatically done by the regular text
               read/write methods of OpenOffice::OODoc, this function is useful only if
               the user's application needs to bypass the API.


               Shortcut for OpenOffice::OODoc::Document->new().

               This function is the most general document constructor. It creates
               and returns a new Document object. It can be instantiated on the basis of
               an existing ODF file, or using XML, OpenDocument-compliant data previously
               loaded in memory. With an appropriate "create" parameter, it can be used
               in order to create a new document from scratch as well. The Document class
               provides methods allowing a lot of read/update operations in the text
               content, the graphics, and the presentation. So ooDocument() is the
               recommended first call to get access to a document for further processing.

               See the OpenOffice::OODoc::Document manual page for detailed syntax.


               Returns the translation of an application-provided string,
               made of local characters, in an ODF-compliant (UTF-8) string.
               The given string must comply with the active local encoding (see
               odfLocalEncoding()). While the right translation is automatically done
               by the regular text read/write methods of OpenOffice::OODoc, this
               function is useful only if the user's application needs to bypass the


               Synonyms: odfContainer(), odfPackage().


               Shortcut for OpenOffice::OODoc::Image->new().

               Generally not used explicitly by the applications.

               This function returns a document object whose features are related to
               image element processing, which is a subset of the Document object.

               See the OpenOffice::OODoc::Image manual page for detailed syntax.


               Accessor to get/set the user's local character set
               (see $OpenOffice::OODoc::XPath::LOCAL_CHARSET in the
               OpenOffice::OODoc::XPath man page).


                       $old_charset = odfLocalEncoding();

               If the given argument is an unsupported encoding, an error
               message is produced and the old encoding is preserved. So
               this accessor is safer than a direct update of the
               $OpenOffice::OODoc::XPath::LOCAL_CHARSET variable.

               The default local character set is fixed according to the
               "OODoc/config.xml" file of your local OpenOffice::OODoc installation
               (see readConfig() below), or to "iso-8859-1" if this file is missing
               or doesn't say anything about the local character set. By calling
               ooLocalEncoding() with an argument, the user's programs can override
               this default.

               Note: the user can override this setting for a particular document,
               using the 'local_encoding' property of the document object (see the
               OpenOffice::OODoc::XPath manual page).

               See the Encode::Supported (Perl) documentation for the list
               of supported encodings.


               Converts the numeric time given in argument to an ISO-8601 date
               (aaaa-mm-jjThh:mm:ss), knowing that this format is required for
               the stored content of any ODF-compliant date element or attribute.

               The argument type is the same as for the standard Perl localtime()
               function, i.e. a number of seconds since the "epoch". It can be, for
               example, a value previously returned by a time() call.

               Without argument, returns the current local time in ISO-8601 format.

               Beware: The resolution of this function is limited to the second,
               unlike the ISO-8601 standard which supports an optional subsecond


               Short cut for OpenOffice::OODoc::Manifest->new().

               This function returns a Manifest object, giving access to the
               meta-information of the physical archive containing the document.


               Shortcut for OpenOffice::OODoc::Meta->new().

               This function returns a Meta object. Such an object represents the
               global properties, or "metadata", of a document. It brings a set of
               accessors allowing the user to get or set some properties such as
               the title, the keyword, the description, the creator, etc.

               See the OpenOffice::OODoc::Meta manual page for details.


               Synonyms: odfContainer(), odfFile().


               Creates or resets some variables of the API according to the
               content of an XML configuration file. Without argument, this
               function looks for 'OODoc/config.xml' under the installation
               directory of OpenOffice::OODoc. In any case, the provided file
               must have the same XML structure as the config.xml file included
               in the distribution, so:

               <?xml version="1.0" encoding="UTF-8"?>

               In the example above, "my_oo_date" should be replaced by a regular
               ISO-8601 date (YYYY-MM-DDThh:mm:ss).

               Elements out of the <OpenOffice-OODoc> element are ignored.
               Any element included in <OpenOffice-OODoc> sets or update a variable
               with the same name and the given value in the space of the
               OpenOffice::OODoc package. So, for example an element like

                       <strange_thing>a strange value</strange_thing>

               will make a new $OpenOffice::OODoc::strange_thing variable,
               initialized with the string "a strange value", available for any
               program using OpenOffice::OODoc.

               Attributes and sub-elements are ignored.

               Strings with characters larger than 7 bits must be encoded in UTF-8.

               Any '-' character appearing in the name of an element is replaced
               by '::' in the name of the corresponding variable, so, for example,
               the <XPath-LOCAL_CHARSET> element controls the initial value of

               All the variables defined in this file, are the file itself, are

               The <INSTALLATION_DATE> element is not used by the API; it's provided
               for information only. It allows the user to get (in OpenOffice format)
               the date of the last installation of OpenOffice::OODoc, through the
               variable $OpenOffice::OODoc::INSTALLATION_DATE. In the default
               config.xml provided with the distribution, this element contains the
               package generation date.

               The <BUILD_DATE> element is the date of the CPAN package.

               This function is automatically executed as soon as OpenOffice::OODoc
               is used, if the OODoc/config.xml configuration file exists.


               Shortcut for OpenOffice::OODoc::Styles->new().

               Generally not used explicitly by the applications.

               This function returns a Styles object, that brings a subset of the
               Document object. In can be used in place of odfDocument() if the
               calling application needs some style/presentation manipulation
               methods only. Note the 's' at the end of 'Styles': this object doesn't
               represent a particular style; it represents a set of styles related
               to a document.

               See the OpenOffice:OODoc::Styles manual page for detailed syntax.


               Shortcut for OpenOffice::OODoc::File::templatePath().

               Accessor to get/set an alternative path for the ODF template files
               used to create new documents.

               The template path must designate a directory containing 4 regular
               ODF files, each one corresponding to an supported ODF document class,
               i.e. "template.odt", "template.ods", "template.odp", "template.odg".


               Shortcut for OpenOffice::OODoc::Text->new().

               Generally not used explicitly by the applications.

               This function returns a Text object, that brings a subset ot the
               Document object. It can be used in place of ooDocument() if the
               calling application is only text-focused (i.e. if it doesn't need
               to deal with graphics and styles). The processed document can contain
               (and probably contains) graphics and styles, but the methods to
               process them are simply not loaded.

               See the OpenOffice::OODoc::Text manual page for detailed syntax.


               Translates an ODF-formatted date (ISO-8601) into a regular Perl
               numeric time format, i.e. a number of seconds since the "epoch". So,
               the returned value can be processed with any Perl date formatting or
               calculation function.


                       my $date_created = odfTimelocal($meta->creation_date());
                       $lt = localtime($date_created);
                       $elapsed = time() - $date_created;
                       print "This document has been created $date_created\n";
                       print "$elapsed seconds ago";

               This sequence prints the creation date of a document in local time
               string format, then prints the number of seconds between the creation
               date and now. Note that the creation_date() method used here works
               with the meta-data document part only (see OpenOffice::OODoc::Meta for
               details about this method).

               Note: This function requires the Time::Local Perl module.


               Accessor to get/set the working directory to use for temporary
               files. Short-lived temporary files are generated each time the save()
               function (see OpenOffice::OOdoc::File) is called. If case of success,
               these files are automatically removed when the call returns, so the
               user can't view them. If something goes wrong during the I/O
               processing, the temporary files remain available for debugging. In any
               case, a working directory is necessary to create or update documents.
               However, OpenOffice::OODoc can be used without available working
               directory in a read-only application.

               The default working directory depends on the "OODoc/config.xml" file
               of your local OpenOffice::OODoc installation. If this file is missing
               or if it doesn't contain a <File-WORKING_DIRECTORY> element, the
               working directory is "." (i.e. the current working directory of the
               user's application).

               If an argument is given, it replaces the current working

               A warning is issued if the (existing or newly set) path is not
               a directory with write permission. After this warning, the user's
               application can run, but any attempted file update or creation

               This accessor sets only the default working directory for the
               application. A special, separate working directory can be set
               for each OOo document (see the manual page for OpenOffice::OODoc::File
               for details, if needed).

               CAUTION: a odfWorkingDirectory() call can't change the working
               directory of a previously created File object. So, consider the
               following code sequence:

                       my $doc0 = ooDocument(file => 'doc0.odt');
                       my $doc1 = ooDocument(file => 'doc1.odt');

               In this example, all the write operations related to the $doc0
               document will use the default working directory, while the ones
               related to $doc1 will use "C:\TMP".


               Shortcut for OpenOffice::OODoc::XPath->new().

               Generally not used explicitly by the applications.

               This function returns an XPath object, that brings all the low level
               XML navigation, retrieve, read and write methods of the API. The XPath
               class (in the OpenOffice::OODoc context) is an OpenOffice-aware
               wrapper for the general XML::Twig API. Unless you are a very advanced
               user and you have a particular hack in mind, you should never need to
               explicitly create an XPath object. But you must know that every method
               or property of this class is inherited by the Text, Image, Styles,
               Document and Meta objects. So the knowledge of the corresponding
               manual page could be useful.

               See the OpenOffice::OODoc::XPath manual page for detailed syntax.


               Synonyms: odfDocument(), odfConnector().


               See odfDecodeText().


               See odfEncodeText().


               Synonyms: odfContainer(), odfPackage(), odfFile().


               Synonym: odfImage().


               See odfLocalEncoding().


               See odfLocaltime()


               Synonym: odfManifest().


               Synonym: odfMeta().


               See odfReadConfig().


               Synonym: odfStyles().


               See odfTemplatePath().


               Synonym: odfText().


               See odfTimelocal()


               See odfWorkingDirectory().


               Synonym: odfXPath().


       Developer/Maintainer: Jean-Marie Gouarne <>


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

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

       License: GNU Lesser General Public License v2.1