Help-Site Computer Manuals
  Algorithms & Data Structures   Programming Languages   Revision Control
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

Top level component for content and layout processing

OpenOffice::OODoc::Document - Top level component for content and layout processing


OpenOffice::OODoc::Document - Top level component for content and layout processing


        # get an OOo file handler

        my $oofile = ooFile("myfile.odt");

        # connect a content-focused document interface

        my $content = ooDocument


                        file => $oofile,

                        member => 'content'


        # connect a style-focused document interface

        my $styles = ooDocument


                        file => $oofile,

                        member => 'styles'


        # process any content and style element



                        text => "An additional paragraph",

                        style => "BlueStyle"





                        parent => 'Text body',

                        family => 'paragraph',

                        properties =>


                                area            => 'text',

                                'fo:color'      => rgb2oo('blue')



        # commit the changes using the file handler



This module defines the top level Document class, which is a connector allowing any kind of content and presentation processing. It inherits from OODoc::XPath, OODoc::Text, OODoc::Styles and OODoc::Image.

The most usual instruction to get access to any member of a document, with the exception if the metadata (meta.xml) should be something like:

        my $doc = ooDocument([options]);

This constructor, if successful, returns an object that can be used (according to its ``member'' option) to process styles, images and text.

This module is designed simply to create objects which include all the functionality of OODoc::Text, OODoc::Image, OODoc::Styles and OODoc::XPath (which should not be called directly by applications).

For example

        my $styles = ooDocument(file => "source.odt", member => "styles");

is generally better than

        my styles = ooStyles(file => "source.odt");

While OODoc::Document inherits all the methods and properties of these classes, its detailed documentation in essentially provided in the following manual pages:

        OpenOffice::OODoc::Text         -> text content

        OpenOffice::OODoc::Styles       -> style & layout

        OpenOffice::OODoc::Image        -> graphic objects

        OpenOffice::OODoc::XPath        -> common features & low-level API

For example, the appendParagraph() and createStyle() methods used in the synopsis above are respectively described in OpenOffice::OODoc::Text and OpenOffice::OODoc::Styles.

The present manual page only describes those methods (there are very few) which combine layout and content processing.


Constructor : OpenOffice::OODoc::Document->new(<parameters>)

        Short Form: ooDocument(<parameters>)


        See OpenOffice::OODoc::XPath->new (or ooXPath)


        Returns an OpenDocument connector, available for subsequent

        access to any element of a well-formed document.


        Knowing that the Document class is a derivative of the Text, Styles,

        Image, and XPath classes, ooDocument() implicitly executes the

        corresponding constructors. So all the options of these constuctors

        are available.


        If no "member" parameter is given, the member selected by default is

        "content" (see OODoc::XPath). The most generally used members are

        "content" and "styles".

createImageStyle(name [, options])

        Creates a graphics style which is immediately usable. With no

        options, this method applies to the new style a "reasonable" set of

        characteristics which match fairly closely the default image

        presentation style in before any manual changes made

        by the user. An application can set its own options in the same way

        as createStyle in OODoc::Styles.

        The aim of this method is to minimise the amount of work involved in

        setting up the style, especially when the default values are close

        enough, and bearing in mind that an image must always be associated

        with a style to be displayed in a document.

        The code below shows a simple method of inserting an image into a

        document, in this case linked to a given paragraph (see

        createImageElement in OODoc::Image):

            my $anchor  = $doc->getParagraph(4);

            my $style   = $doc->createImageStyle("Photo");

            my $image   = $doc->createImageElement


                "Eiffel Tower",

                style           => "Photo",

                attachment      => $anchor,

                size            => "4cm, 12cm",

                import          => "eiffel_tower.jpg"


createTextStyle(name [, options])

        Creates a text style which is immediately usable and whose default

        characteristics are the "Standard" style in the document, even if no

        options are given.

        If the "Standard" style does not exist, a "reasonable" style is

        still created (this can happen in a document created from code and

        not by an interactive office software).

        An application can still pass all the options it wants in the same

        way as createStyle in OODoc::Styles.


        Removes the page break from the given paragraph (before or after).

        This method actually removes the page break attribute from the

        corresponding paragraph style. It does not remove paragraph styles

        which may have been created to carry page breaks, so its effects are

        not technically the reverse of setPageBreak(). Generally speaking,

        however, this should not be a problem. See setPageBreak() about the

        logic of handling page breaks.

setPageBreak(paragraph [, options])

        Places a page break at the position of the given paragraph. By

        default, the page break is placed before the paragraph and no

        changes are made to the page style.

        You can place the page break after the paragraph using the option

            position => 'after'

        To use this method properly every time, you must remember that a

        page break is not a text element, but a style applied before or

        after the paragraph concerned. Putting a page break in front of or

        behind a paragraph actually means adding a "page break before" or

        "page break after" attribute to the paragraph's style. As always, a

        page break cannot appear in the text in keeping with the principle

        of separation of content and presentation. This however adds a

        slight complication, in that all paragraphs which use the same style

        will have the page break. Otherwise, if the paragraph has a named

        style (i.e. defined in styles.xml) and we are working in the body of

        the document (i.e. in content.xml), then this method will not work

        as it cannot access both XML members at the same time. There is

        however a solution (the one used by which consists

        simply of creating a special style for the paragraph which takes the

        old paragraph style as a parent and has only a page break attribute

        (the old paragraph style is not modified). To do this, all you need

        is the option:

            style => style_name

        This option forces the creation of an automatic style with the given

        name (make sure none other exists with the same name) and which will

        only be used to carry the page break. Later on, you can of course

        apply other characteristics to the style using the updateStyle

        method in OODoc::Styles, but this is not recommended. It is better

        not to use page break styles for other purposes. The nature of the

        existing paragraph style dictates whether or not you create a page

        break style. If the paragraph style is a named style (i.e. defined

        in styles.xml and visible to the user), you must create a page break

        style, but if it already has an automatic style you must not. The

        quite rare but most complicated scenario is where the paragraph has

        an automatic style shared by several paragraphs. In this case you

        must then make copies of the styles using the methods in


        A page break can allow you to change a page's style. You can do this

        with the option:

            page => page style

        in which you give the following page's style (i.e. the logical name

        of a master page. See OODoc::Styles). Remember that if the "page"

        option is given, the page break is forced before the paragraph (the

        "position" option does not work in this case).

style(object [, style])

        Returns the style name of a text or graphics object. If the first

        argument is a "master page" (see OODoc::Styles), it even returns the

        associated "page layout".

        Replaces the object's style if a style name is given as the second



Developer/Maintainer: Jean-Marie Gouarne


Copyright 2004-2006 by Genicorp, S.A.

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


        - Licence Publique Generale Genicorp v1.0

        - GNU Lesser General Public License v2.1