NAME

DESCRIPTION

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

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

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

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

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

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

Tables of contents

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.

AUTHOR/COPYRIGHT

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

POD ERRORS

Around line 128:

Non-ASCII character seen before =encoding in '(§4.4.1),'. Assuming UTF-8