NAME

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

DESCRIPTION

This manual page is related to the sections, item lists and draw pages. These element types are implemented through the odf_section, odf_list, and odf_draw_page classes, respectively.

Note: In the present development version, odf_section is the only one already implemented.

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;

• 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: boolean, tells that the section should be visible (default is TRUE).

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

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

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

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.

Frames

A frame is a rectangular container that may contain text boxes and 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 (for the end-user);

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

• 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"), knowing that the default value is 0 and the default length unit is "cm" (centimeter);

• 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 (see the "Class" subsection in ODF §9.6.1).

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 have a title and/or a description, that may be get or set using get_title(), set_title(), get_description(), or set_description().

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

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.

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

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

An existing frame may be selected using get_frame() with the identifier.

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 parameters are the same as with odf_create_image() introduced later); alternatively, if set_image() is called with an existing ODF image element as argument, this element is incoporated as is without creation; set_image() returns the new (or newly inserted) ODF image element.

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 an external 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 (see above).

COPYRIGHT & LICENSE

Copyright (c) 2010 Ars Aperta, Itaapy, Pierlis, Talend.

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

lpOD is free software; you can redistribute it and/or modify it under the terms of either:

a) the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. lpOD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with lpOD. If not, see http://www.gnu.org/licenses/.

b) the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

cpanm ODF::lpOD

perl -MCPAN -e shell
install ODF::lpOD