NAME

ODF::lpOD::Table - Table management

DESCRIPTION

The present manual page introduces the way lpOD allows the user to handle ODF tables and their components, namely the columns, rows and cells.

The lpOD API doesn't make differences between document types in this area. So, tables are dealed with in the same way for a spreadsheet document (whose content is just a set of tables) as for any other document.

A table is an instance of the lpOD odf_table class.

An odf_table object is a structured container that holds two sets of objects, a set of rows and a set of columns, and that is optionally associated with a table style.

The basic information unit in a table is the cell. Every cell is contained in a row. Table columns don't contain cells; an ODF column holds information related to the layout of a particular column at the display time, not content data.

A cell can directly contain one or more paragraphs. However, a cell may be used as a container for high level containers, including lists, tables, sections and frames.

Every table is identified by a name (which must be unique for the document) and may own some optional properties.

Note: the implemented and documented features, in the present development version, are only a subset of the full lpOD specification about tables.

Table creation and retrieval

Like any other odf_element table may be created either from scratch according to various parameters or by cloning an existing table using the generic clone method of odf_element. The second way is the most recommended one because, while it looks very easy to create a table with a default appearance, a typical convenient layout may require a lot of style definitions and is much more difficult to specify by program than through a point-and-click interface.

A table is created using odf_create_table with a mandatory name as its first argument and the following optional parameters:

width, length: the initial size of the new table (rows and columns), knowing that it's zero-sized by default (beware: because cells are contained in rows, no cell is created as long as width is less than 1);

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

cell style: the style to use by default for every cell in the table;

protected: a boolean that, if TRUE, means that the table 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 table should be visible; default is TRUE;

print: boolean, tells that the table should be printable; however, the table is not printable if display is FALSE, whatever the value of print; default is TRUE;

print ranges: the cell ranges to be printed, if some areas are not to be printed; the value of this parameter is a space-separated list of cell ranges expressed in spreadsheet-style format (ex: "E6:K12").

Once created, a table may be incorporated somewhere using insert_element of append_element, like any other odf_element.

Caution: a table should not be inserted in any context. For example, a table should not be inserted within a paragraph. A bad placement may corrupt the document structure. Right contexts are, for example, the document body (in a spreadsheet or text document), a section (in a text document) or a table cell (knowing that the ODF standard allows nested tables).

The style of a table may be retrieved at any time using the generic get_style and set_style accessors.

A table may be retrieved in a document according to its unique name using the context-based get_table_by_name with the name as argument. It may be selected by its sequential position in the list of the tables belonging to the context, using get_table_by_position, with a zero-based numeric argument (possibly counted back from the end if the argument is negative). In addition, it's possible to retrieve a table according to its content, through get_table_by_content; this method returns the first table (in the order of the document) whose text content matches the given argument, which is regarded as a regular expression.

Table content retrieval

A table object provides methods that allow to retrieve any column, row or cell using its logical position. A position may be expressed using either zero-based numeric coordinates, or alphanumeric, spreadsheet-like coordinates. For example the top left cell should be addressed either by (0,0) or by "A1". On the other hand, numeric coordinates only allow the user to address an object relatively to the end of the table; for example, (-1,-1) designates the last cell of the last row whatever the table size.

Table object selection methods return a null value, without error, when the given address is out of range.

The number of rows and columns may be got using the odf_table get_size method.

An individual cell is selected using get_cell with either a pair of numeric arguments corresponding to the row then the column, or an alphanumeric argument whose first character is a letter. The second argument, if provided, is ignored as soon as the first one begins with a letter.

The two following instructions are equivalent and return the second cell of the second row in a table (assuming that $t is a previously selected table):

        $cell = $t->get_cell('B2');
        $cell = $t->get_cell(1, 1);

get_row allows the user to select a table row as an ODF element. This method requires a zero-based numeric value. If the required row exists, it's returned; the method returns undef otherwise. get_row provides a odf_row object, that provides its own get_cell method. When called from a odf_row, get_cell requires a numeric argument only, that is the zero- based position on the needed cell.

get_column works according to the same logic and returns a table column object, that is a odf_column instance. (Remember that a column doesn't contain cells.)

Row and column customization

The objects returned by get_row and get_column can be customized using the standard set_attribute or set_attributes method. Possible attributes are:

• default cell style name: the default style which apply to each cell in the column or row unless this cell has no defined style attribute;

• visibility: specifies the visibility of the row or column; legal values are 'visible', 'collapse' and 'filter'.

The style may be get or set using get_style or set_style.

Table expansion

A table may be expanded vertically and horizontally, using its add_row and add_column methods.

add_row allows the user to insert one or more rows at a given position in the table. The new rows are copies of an existing one. Without argument, a single row is just appended as the end. A number named parameter specifies the number of rows to insert.

An optional before named parameter may be provided; if defined, the value of this parameter must be a row number (in numeric, zero-based form) in the range of the table; the new rows are created as clones of the row existing at the given position then inserted at this position, i.e. before the original reference row. A after parameter may be provided instead of before; it produces a similar result, but the new rows are inserted after the reference row. Note that the two following instructions produce the same result (assuming $t is a previously selected or created table):

        $t->add_row(number => 1, after => -1);
        $t->add_row();

Of course, it's possible to use insert_element in order to insert a row, a column or a cell externally created (or copied from an other table from another document), provided that the user carefully checks the consistency of the resulting contruct. As an example, the following sequence appends a copy of the first row of $t1 after the 5th row of $t2:

   $to_be_inserted = $t1->get_row(0)->clone;
   $t2->insert_element($to_be_inserted, after => $t2->get_row(5));

While a table may be expanded vertically using add_row, each row may be expanded using the odf_row add_cell method whose parameters and behaviour are the same as the table-based add_row method.

The add_column method, which is in the lpOD scope, will be implemented soon.

Individual cell property handling

A cell owns both a content and some properties which may be processed separately.

The cell content is a list of one or more ODF elements. While this content is generally made of a single paragraph, it may contain several paragraphs and various other objects. The user can attach any content element to a cell using the standard insert_element method. However, for the simplest (and the most usual) cases, it's possible to use set_text. The cell-based set_text method diffs from the generic odf_element set_text: it removes the previous content elements, if any, then creates a single paragraph with the given text as the new content. In addition, this method accepts an optional style named parameter, allowing the user to set a paragraph style for the new content. To insert more content (i.e. additional paragraphs and/or other ODF elements), the needed objects have to be created externally and attached to the cell using insert_element or append_element. Alternatively, it's possible to remove the existing content (if any) and attach a full set of content elements in a single instruction using set_content; this last cell method takes a list of arbitrary ODF elements and appends them (in the given order) as the new content.

The get_content cell method returns all the content elements as a list. For the simplest cases, the cell-based get_text method directly returns the text content as a flat string, without any structural information and whatever the number and the type of the content elements.

The cell properties may be read or changes using get_xxx and set_xxx methods, where xxx stands for one of the following:

• style: the name of the cell style;

• type: the cell value type, which may be one of the ODF supported data types, used when the cell have to contain a computable value (may be omitted with text cells, knowing that the default type is 'string');

• value: the numeric computable value of the cell, used when the type is defined;

• currency: the international standard currency unit identifier (ex: EUR, USD), used when the type is 'currency';

• formula: a calculation formula whose result is a computable value (the grammar and syntax of the formula is application-specific and not ckecked by the lpOD API (it's stored as flat text and not interpreted);

• protect: boolean (default FALSE), tells the applications that the cell can't be edited.

If set_currency is used with a non-null value, then the type of the cell is automatically set to 'currency'. If set_type forces a type that is not 'currency', then the cell currency is unset.

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