NAME

ODF::lpOD::StructuredContainer - High-level structures other than tables

DESCRIPTION

This manual page is related to the sections, item lists, draw pages, frames, and drawing shapes.

These element types are implemented through the odf_section, odf_list, odf_draw_page, odf_frame, odf_rectangle, odf_ellipse, odf_line, and odf_connector classes.

Item lists

A list is a structured object that contains an optional list header followed by any number of list items. The list header, if defined, contains one or more paragraphs that are displayed before the list. A list item can contain paragraphs, headings, or lists. Its properties are style, that is an appropriate list style, and continue numbering, a boolean value that, if true, means that if the numbering style of the preceding list is the same as the current list, the number of the first list item in the current list is the number of the last item in the preceding list incremented by one (default=false).

A list is created using the odf_create_list() function or the create() class method of odf_list, then inserted using insert_element() as usual.

A list header is created "in place" with set_header(), called from a list element; this method returns an ODF element that can be used later as a context to append paragraphs in the header. Alternatively, it's possible to call the list-based set_header() with one or more existing paragraphs as arguments, so these paragraphs are immediately incorporated in the new list header. Note that every use of set_header() replaces any existing header by a new one.

Regular list items are created in place (like the optional list header) using add_item() which creates one or more new items and inserts them at a position which depends on optional parameters, according to the same kind of logic than the table-based add_row() method. Without any argument, a single item is appended at end of the list. An optional before named parameter may be provided; if defined, the value of this parameter must be an item number (in numeric, zero-based form) in the range of the list; the new items are inserted before the original item that existed at the given position. Alternatively, a after parameter may be provided instead of before; it produces a similar result, but the new items are inserted after the given position. If a additional number parameter is provided with a integer value, the corresponding number of identical items are inserted in place.

By default, a new item is created empty. However, as a shortcut for the most common cases, it's possible to directly create it with a text content. To do so, the text content must be provided through a text parameter; an optional style parameter, whose value is a regular paragraph style, may be provided too. The new item is then created with a single paragraph as content (that is the most typical situation).

Another optional start value parameter may be set in order to restart the numbering of the current list at the given value. Of course, this start value apply to the first inserted item if add_item() is used to create many items in a single call.

add_item() returns the newly created list of item elements. In addition, an existing item may be selected in the list context using get_item() with its numeric position. A list item is an ODF element, so any content element may be attached to it using insert_element() or append_element().

Note that, unlike headings, list items don't have an explicit level property. All the items in an ODF list have the same level. Knowing that a list may be inside an item belonging to another list, the hierarchy is represented by the structural list imbrication, not by item attributes.

A list may be retrieved using the context-based get_list() method, whose optional parameters are the same as get_element(). A get_list_by_id() method selects a list according to its (optional) identifier. In addition, get_lists() selects the item lists contained in the context according to the same rules as get_elements().

Sections

A section is a named region in a text document. It's a high level container that can include one or more content elements of any kind (including sections, that may be nested).

The purpose of a section is either to assign certain formatting properties to a document region, or to include an external content.

A section is created using odf_create_section with a mandatory name as the first argument and the following optional parameters:

• style: the name of a section style, already existing or to be defined;

• url: the URL of an external resource that will provide the content of the section; if this option is set, the protected option is set to TRUE by default; note that lpOD doesn't check for the availability of the resource, which should be available when the processed document is displayed through an ODF viewer, but which is not needed to run the program;

• source: same as url;

• protected: a boolean that, if TRUE, means that the section should be write-protected when the document is edited through a user-oriented, interactive application (of course, such a protection doesn't prevent an lpOD-based tool from modifying the table)(default is FALSE);

• protection key: a (supposedly encrypted) string that represents a password; if this parameter is set and if protected is TRUE, a end-user interactive application should ask for a password that matches this string before removing the write-protection (beware, such a protection is not a security feature);

• display: tells that the section should be visible; legal values are TRUE, FALSE, and the string 'condition'; the default is TRUE; note that if this option is set to 'condition' an additional condition parameter should be provided according to the ODF specification (§4.4.1), but this parameter is neither checked nor documented in lpOD.

A new section may be inserted or appended somewhere using insert_element or append_element. (Of course, an existing section may be copied and pasted thanks to the common clone method.)

The following code appends a new write-protected section whose content will come from an external ODF text document at the end of the document body:

      $body = $doc->get_body;
      $body->append_element(
            odf_section->create(
                  "ExternalDocument",
                  url => "/home/documents/report.odt"
                  )
            );

A section may be retrieved using get_section() with the unique name of the needed section as argument, while get_sections() returns all the sections (if any) of the context.

A section may be retrieved from any element of its direct or indirect content, thanks to the get_parent_section() method. This method returns undef if the calling element is not included in a section. As an example, the example below selects the first paragraph whose text matches a given expression in the whole document content, then displays the section name if this paragraph belongs to a section:

   $p = $doc->get_body->get_paragraph(content => "xyz")
      or die "No matching paragraph\n";
   $section = $p->get_parent_section;
   say $section ? $section->get_name : "Not in a section";

An existing section may be used as the context for any element retrieval, update, creation or deletion. As examples, the following sequence appends a new paragraph to a supposedly existing section:

   $section = $context->get_section("My Section");
   $section->append_element(
      odf_create_paragraph(text => "Section end")
      );

Thanks to the group() method, it's possible to move a set of existing elements into a section. As an example, the example below grabs all the tables of a given document and moves them in a newly created section:

   my $context = $doc->get_body;
   my $section = $context->append_element(
      odf_create_section("Tables")
      );
   $section->group($context->get_tables);

Note that group() is a generic odf_element method that could be used to move anything into anything. However, this method is not recommended with elements other than sections, unless the user have a good knowledge of the ODF semantics. While a section can host a large variety of content elements, other objects have much more restrictive composition rules, and inappropriate groupings may result in severe inconsistencies.

Draw pages

Draw pages are structured containers belonging to presentation or drawing documents. They shouldn't appear in text or spreadsheet documents.

A draw page can contain forms, drawing shapes, frames, presentation animations, and/or presentation notes (§9.1.4 in the ODF specification).

A draw page is created using odf_create_draw_page() and integrated through insert_element() or append_element(). Note that a draw page should be inserted at the document body level, knowing that it's a top level content element.

A draw page must have an identifier (unique for the document) and may have the following parameters, to be set at creation time or later:

• name: an optional, but unique if provided, name (which may be made visible for the end-users); this parameter is strongly recommended knowing that some ODF applications don't preserve the draw page identifier, so the name remains the only stable identifier;

• style: the name of a drawing page style (existing or to be defined);

• master: the name of a master page whose structure is appropriate for draw pages (beware, a master page defined for a text document don't always fit for draw pages);

• layout: the name of a presentation page layout as defined in §14.15 of the ODF specification (if such a layout is used); beware, such objects are neither similar nor related to general page layouts as defined in §14.3 (a general page layout may be used through a master page only, and should never be directly connected to a draw page) (sorry, this confusing vocabulary is not a choice of the lpOD team)

The following example creates a draw page with these usual parameters and integrates it as the last page of a presentation document::

        $dp = odf_create_draw_page(
                'xyz1234',
                name    => 'Introduction',
                style   => 'DrawPageOneStyle',
                master  => 'DrawPageOneMaster',
                layout  => 'DrawPageOneLayout'
                );
        $context->append_element($dp);

All these parameters may retrieved or changed later using get_attributes() and set_attributes() with draw page objects.

An existing draw page may be retrieved in a given context (that should be the document body or root) through get_draw_page() with the identifier as argument. This methods attempt to retrieve a draw page whose identifier matches the argument, then, in case of failure, it looks for a draw page whose name matches. Alternatively, the user can explicitly select a draw page by name using get_draw_page_by_name() or according to its zero-based position in the document using get_draw_page_by_position(). The whole list of draw pages may be returned by get_draw_pages().

Populating a draw page doesn't require element-specific methods, knowing that:

• all the fixed parts, the layout and the background are defined by the associated style, master and layout;

• all the content objects are created separately and attached to the draw page using the regular insert_element() or append_element() method from the draw page object.

The get_title() method, when applied to a draw page, tries to get the title text box of the page, and returns the text content of the first paragraph found in it, if set. The first frame whose presentation class is title, if any, is assumed to be the title text box. Beware that there is no set_title() method for draw pages.

The following sequence, assuming the given file is a presentation document, displays the name and (if defined) the title of every draw page:

      $doc = odf_get_document($filename);
      $context = $doc->get_body;
      foreach my $p ($context->get_draw_pages) {
            my $n = $p->get_name // '<no name>';
            my $t = $p->get_title // '<no title>';
            say sprintf("%s %s", $n, $t);
            }

If the draw page doesn't contain any frame whose class is title, or if its title frame doesn't contain any paragraph, get_title() returns undef.

Frames

A frame is a rectangular container that may contain text boxes or images. It may contain other kinds of elements that are not presently covered by the lpOD level 1 specification.

A frame is created using odf_create_frame() with the following properties:

• name: the optional name of the object;

• id: an arbitrary string, that is the unique identifier of the frame;

• title: a free informative title;

• description: a free informative description;

• style: the name of a graphic style for the frame;

• position, the coordinates of the frame, as a list of 2 strings or as 2 comma-separated fields in a single string, containing the X and Y positions, each string specifying the number and the unit (ex. "1cm", "2pt");

• size: the size, provided either in absolute values like the position, as percentages, or using the special keywords scale or scale-min (see ODF §9.3 for details); both absolute and relative values may be provided as a string, separated by a comma, if needed, like "10cm, 12%"; or as a list of 2 strings;

• z index: an optional sequence number that allows the user to assign a particular order of rendering, knowing that frames are rendered by default according to their sequential position in the document tree;

• class: an optional presentation class, such as title, subtitle, outline, graphic, etc (see the "Class" subsection in ODF §9.6.1 for the whole list of legal values).

For an existing frame, the properties above may be read or changed using get_xxx() or set_xxx() methods where "xxx" designates the appropriate property.

A frame may be inserted in place through the standard insert_element() method, but the behavior depends on the context.

Once attached to something, a frame may be associated to a clickable hyperlink through the set_hyperlink() that requires a url parameter specifying the URL. Optionally, a significant name may be provided through a name parameter. Beware that this hyperlink is not related to the content of the frame; it only specifies a link that should be activated by an interactive viewer when the user will click in the frame. Caution: this method is prohibited as long as the frame element is free (i.e. non-attached), so it can't be used with a created but not inserted frame.

It's possible to retrieve the hyperlink associated to a frame (if any) through get_hyperlink(). The returned object is not the URL, it's a regular element whose URL may be read or changed using get_url() or set_url().

In a text document, a frame may be attached to the document body, as long as it's anchored to a page; as an consequence, a page parameter must be provided with the page number. The example below inserts a new frame that will appear in the first page, assuming that the document type is text:

        $doc->get_body->insert_element(
                odf_frame->create(
                        name            => "FR1",
                        text            => "Example",
                        size            => "8cm, 3cm",
                        position        => "2cm, 3.5cm",
                        page            => 1
                )
        );

Note that a page-anchored frame should be attached to a text document body through insert_element() without option, and not append_element(), knowing that typical ODF viewers can't properly render if it's not stored before any other visible content.

Simply put, with the exception above, a frame is anchored to the calling context element. The ODF elements that may insert a frame in the present lpOD API are *draw pages*, *paragraphs*, *tables*, and *cells*.

The sequence hereafter inserts a frame immediately after the 5th paragraph of a document; to do so, an empty paragraph is inserted at the right position then used to host the frame:

        $context = $doc->get_body;
        $p = $context->insert_element(
                odf_paragraph->create,
                after   => $context->get_paragraph(position => 4)
        );
        $p->insert_element(
                odf_frame->create(
                        name    => "FR2",
                        size    => "12cm, 8cm",
                        text    => "In the box"
                )
        );

In a presentation or drawing document, the calling element is typically a draw page.

When insert_element() is called from a paragraph, an optional offset parameter, specifying the position in the text where the frame will be inserted, may be provided (the default position is the beginning of the paragraph).

The way to attach a frame to a table cell is not the same in a text document as in a spreadsheet document. lpOD tries to hide the differences provided that the attachement is done when the cell itself is already attached to a document. On the other hand, if the target cell is not attached, lpOD doesn't know what will be the document type and silently selects the attachment method that works for text documents.

An existing frame may be selected using get_frame() from any context with the frame name as argument.

It's possible, of course, to populate a frame using insert_element() or append_element() from the frame itself. However, the API provides frame- specific methods in order to directly create and incorporate the most common objects in a frame context, namely *text boxes* and *images*. These methods are respectively:

• set_text_box(), which requires no argument, but which may be called with a list of existing ODF elements that could become a valid content for a text box (paragraphs, item lists, etc); this method returns an object that may be later used to insert additional content;

• set_image(), which creates an image element that will cover the whole area of the frame; the first argument is the external of internal path to the image file; alternatively, if set_image() is called with an existing ODF image element as argument, this element is incorporated as is without creation; set_image() returns the new (or newly inserted) ODF image element; a load boolean option is allowed and, if set to TRUE, specifies that the external file whose path is provided as the first argument must be loaded in the ODF package (works only if the calling frame is attached to a document); a size optional parameter allows the application to explicitly force a particular size.

  The following example loads a image file according to a given URL in the document package, associates it to the calling odf_frame object, and resizes the frame according to given width and height:

          $frame->set_image(
                  "http://my.images/logo.png",
                  load    => TRUE,
                  size    => "5cm, 8cm"
                  );

  If no size parameter is provided and if the calling frame has no previously defined size, then set_image() tries to automatically detect the size of the given resource. Note that such detection may be very costly, especially if the image resource is remote. The best option definitely consists of providing an explicit size each time this size may be known and/or fixed by the application.

  Caution: The load option can't work if the calling frame is not in a document, because the storage space of the image is the document container, not the frame.

Images

An image element may be created out of any document with odf_create_image(). This constructor requires only one named parameter, that is either url or content. The first one is a link to a graphic resource, while the second one is the binary content of an image in BASE64 encoding.

These properties may be retrieved or changed later using get_uri(), set_uri(), get_content(), set_content().

An image should be incorporated in a document through a frame. In most situations, the applications don't need to explicitly create and handle image objects, that may be more easily set through the image frame constructor (see below).

Frames including text boxes or images

Knowing that a frame is in most situations created as a text box or image container, the odf_create_text_frame() and odf_create_image_frame() constructors allow the user to directly create a frame with the appropriate content. Each one requires a mandatory argument in first position (before the usual frame parameters).

Note that odf_create_text_frame() and odf_create_image_frame() are just syntactic variants for the following instructions, respectively:

        odf_frame->create(text => $text [, options]);
        odf_frame->create(image => $resource [, options]);

For odf_create_text_frame() the first argument is either a text string or an ODF text element. In the first case the string is used as the content of the text box. In the second case the text element is used as is as the content of the text box.

For odf_create_image_frame() the first argument is the link to the internal or external image resource.

If the size parameter is not set, lpOD internally uses Image::Size in order to set it to the original image size of the given resource. Beware that such an automatic size detection may be very costly, so the user should provide explicit frame sizes in any intensive application.

Note that the ODF::lpOD::Document class provides a add_image_file() method that can import external image files in the ODF package. In array context, this method returns both the internal path of the image and, if possible, the original image size.

Caution: the automatic image sizing feature provided by lpOD uses the point (pt) as length unit, not an absolute length unit (such as the millimeter or the inch); so it may ensure a correct aspect ratio but the real display size may depend on the rendering environment.

The following sequence imports an image file, creates a frame that uses it, then attach the frame to a newly appended paragraph (so the image will appear at the very end of a text document):

        my ($path, $size) = $doc->add_image_file('/home/images/logo.png');
        my $frame = odf_create_image_frame($path, size => $size);
        my $paragraph = $doc->get_body->append_element(odf_create_paragraph);
        $paragraph->append_element($frame);

The same job could be done another way:

        my $frame = odf_frame->create;
        my $paragraph = $doc->get_body->append_element(odf_create_paragraph);
        $paragraph->append_element($frame);
        $frame->set_image('/home/images/logo.png', load => TRUE);

Note that it's strongly recommended, each time it's possible, to set an application-provided size, in order to avoid the costly automatic size detection.

Beware that a size of 0x0 is sometimes interpreted as "original size" by the office software. If so, the best option consists of providing a size parameter set to "0,0": it may avoid useless processing, because the frame is automatically sized by the rendering software, instead of being extracted by lpOD.

Drawing shapes

Common Drawing Shape Attributes

The currently covered shapes are line, rectangle, ellipse, and connector.

A shape is created using an odf_create_xxx() constructor, where xxx is of course replaced by a shape name from the list above, that returns an odf_shape object.

The common properties that may be set through shape constructor named parameters are:

• name: an optional name, that should be unique;

• id: an optional identifier, that must be unique;

• style: the name of the graphic style of the shape;

• text style: the style that is used to format the text that can be added to this shape, if any (if defined, must be a paragraph style);

• layer: the optional name of the layer in the layer set of the document, if the graphics are layered;

• transform: a list of transformations that can be applied to a shape, provided as a string where the transform definitions are separated by commas or spaces (ex.: rotate(45), scale(10, 12)); see ODF 1.1 §9.2.15 for the supported transformations;

• title and description: see below.

Note that, while the name property is not specified as unique in the standard, OpenOffice.org prevents the end-user from providing non-unique names to drawing shapes. On the other hand, OpenOffice.org currently neither uses nor preserves the id property in text documents, but needs it to implement the connectors in presentation documents. So, we presently recommend the use of name, with unique values, as soon as the applications need persistent shape identifiers.

A shape may be provided with a title and a description (which are non- displayed but persistent metadata), through the set_title() and set_description() methods. These informative data may be retrieved using get_title() and get_description().

A shape may be attached to a text element using insert_element() or append_element(). When insert_element() is called from a paragraph, an optional offset parameter, specifying the position in the text where the shape will be inserted, may be provided (the default position is the beginning of the paragraph).

For some shapes, the following properties must be provided:

• position, the coordinates of the frame, as a list of 2 strings containing the X and Y positions (each string specifies the number and the unit, ex. "1cm", "2pt");

• size: the size, provided using the same format and rules as the position.

However, the position and size properties don't apply to some particular shapes, such as lines and connectors (see below).

A shape becomes visible when it's inserted somewhere using the generic insert_element() method.

In a text document, a frame may be attached at the document level, as long as it's anchored to a page; as an consequence, a page parameter must be provided with the page number. Without this page property, lpOD anchors the shape to the first page by default.

Simply put, with the exception above, a shape is anchored to the calling context element.

Optionally, regular text paragraphs may be embedded in a shape. Unlike the name, the title and the description, this paragraph will be visible. There is no shape-specific method for that; the generic append_element() method, called from the odf_shape object, allows the user to insert a paragraph in a shape. The given paragraph may have its own style, whose properties override those of the shape text style.

Rectangles and Ellipses

Rectangles and ellipses are created with odf_create_rectangle() and odf_create_ellipse(), respectively, using the common properties described above, including size and position.

The following example, supposed to work with a text document, creates a rectangle anchored to the first page with given position, size, title, description. Then a text paragraph is written in it:

        $context = $document->get_part(CONTENT)->get_body;
        $rectangle = odf_create_rectangle(
                name => "Rectangle1", id => "R1", page => 1
                );
        $rectangle->set_title("The rectangle");
        $rectangle->set_description("The description of the rectangle");
        $context->insert_element($rectangle);
        $paragraph = odf_create_paragraph(
                text => 'The text in the shape', style => 'Standard'
                );
        $rectangle->append_element($paragraph);

Lines and Connectors

A line is created using odf_create_line(), with the standard shape parameters with the exception of size and position.

The size and the position are defined by line-specific start and end properties, each one representing the coordinates of an extremity, in the same format as the position property of some other shapes.

A connector is created using odf_create-connector(). It may be defined with the same parameters as a line, but can support a more sophisticated configuration, through the following specific properties:

• connected shapes: the name of the start and end shapes that are linked through the connector (as a pair of strings);

• glue points: the numbers of the glue points in the start and end shapes, respectively (glue points are designated points on the area of a drawing object to which a connector shape can connect, see ODF 1.1 §9.2.19);

• type: the connector type, knowing that allowed values are standard, lines, line, and curve.

Tables of contents

A table of contents (TOC) is represented by an odf_toc object, which is created using the odf_create_toc() constructor.

Note that a odf_toc object is a descriptor that specifies parameters for automatic generation by a typical, ODF-compliant text processor. The TOC is not automatically filled by lpOD.

TOC creation

A table of contents is created as a free element using the odf_create_toc() constructor, with a mandatory unique name as its first argument, and the following parameters:

• title: an optional title (to be displayed at the TOC head), whose default value is the given name;

• style: the name of a section style applying to the TOC;

• protected: a boolean flag that tells the editing applications if the section is write-protected (default=TRUE);

• outline level: specifies the last outline level to be used used when generating the TOC from headings; if this parameter is omitted, all the outline levels are used by default;

• use outline: a boolean flag that specifies if the TOC must be generated from headings (default=TRUE);

• use index marks: a boolean flag that specifies if the TOC must be generated from index marks (default=FALSE).

A table of contents object, after creation, may be put somewhere in a document using a generic method such as insert_element(). Note that such an object should be inserted in the CONTENT part of a text document only.

TOC retrieval

An existing table of contents may be retrieved by name using the part method get_toc(). Note that this method works with the CONTENT part only.

It's possible to retrieve the full list of the TOCs in the document content through get_tocs(), without argument.

TOC methods

The odf_toc elements provide the following methods:

• get_body() returns the table/index body, that is the context for any visible content; this content (once generated by a text processor) is typically made of a sequence of paragraphs;

• get_name() and set_name() to get or set the internal unique name;

• get_title() and set_title() to get or change the display TOC title; with set_title(), the first argument is the text of the title, and a style named parameter is allowed to specify a paragraph style for the title;

• get_outline_level() and set_outline_level() to get or change the current outline level property;

• get_use_outline() and set_use_outline() to get or set the use outline flag;

• get_use_index_marks() and set_use_index_marks() to get or set the use index marks flag.

• get_protected() and set_protected() to get or set the current protection status.

AUTHOR/COPYRIGHT

Developer/Maintainer: Jean-Marie Gouarne http://jean.marie.gouarne.online.fr Contact: jmgdoc@cpan.org

Copyright (c) 2010 Ars Aperta, Itaapy, Pierlis, Talend. Copyright (c) 2011 Jean-Marie Gouarne.

This work was sponsored by the Agence Nationale de la Recherche (http://www.agence-nationale-recherche.fr).

License: GPL v3, Apache v2.0 (see LICENSE).

cpanm ODF::lpOD

perl -MCPAN -e shell
install ODF::lpOD