view release on metacpan or  search on metacpan

OODoc/Intro.pod  view on Meta::CPAN

=head1	NAME

OpenOffice::OODoc::Intro - Introduction to the Open OpenDocument Connector

=head1	DESCRIPTION

This introductory notice is intended to allow the user to understand the
general principles and to learn some basic features of the OODoc module
without browsing the whole reference manual.

The reference manual is a set of OpenOffice::OODoc::xxx separate documents,
where xxx is the codename of a particular functional area.  The present
introduction, as well as the OpenOffice::OODoc main chapter, should be read
in order to get the big picture before any attempt to dig in the detailed
documentation.

Just before reading this intro, it's a good idea to have a look at the
short (and commented) examples provided in the distribution.

Another general introduction to this Perl OpenDocument Connector has been
published in The Perl Review (issue #3.1, dec. 2006)
L<http://www.theperlreview.com>

There is an alternative intro for french-reading users. It's available in
ODT (L<http://jean.marie.gouarne.online.fr/doc/oodoc_guide.odt>) or PDF
(L<http://jean.marie.gouarne.online.fr/doc/oodoc_guide.pdf>). In addition,
a general presentation in French can be downloaded at
L<http://jean.marie.gouarne.online.fr/doc/perl_odf_connector.pdf>

=head1	Overview

The main goal of the Open OpenDocument Connector (OODoc) is to allow
quick application development in 2 areas:

- replacement of old-style, proprietary, client-based macros for intensive
and non-interactive document processing;

- direct read/write operations by enterprise software on office documents,
and/or document-driven applications.

OODoc provides an abstraction of the document objects and isolates the
programmer from low level XML navigation, UTF8 encoding and file
compression details. For example:

	use OpenOffice::OODoc;
	my $document = odfDocument(file => 'filename.odt');
	$document->appendParagraph
			(
			text	=> 'Some new text',
			style	=> 'Text body'
			);
	$document->appendTable("My Table", 6, 4);
	$document->cellValue("My Table", 2, 1, "New value");
	$document->save;

The script above appends a new paragraph, with given text and style, and
a table with 6 lines and 4 columns, to an existing document, then inserts
a value at a given position in the table. It takes much less time than the
opening of the document with your favourite text processor, and can be
executed without any desktop software connection. A program using this
library can run without any OpenOffice.org installation (and, practically,
OODoc has been tested on platforms where OpenOffice.org is not available
yet).

More generally, OpenOffice::OODoc provides a lot of methods (probably most
of them are not useful for you) allowing create/search/update/delete
operations with document elements such as:

- ordinary text containers (paragraphs, headings, item lists);
- tables and cells;
- user fields;
- sections;
- images;
- styles;
- bookmarks;
- bibliography entries;
- page layout;
- metadata (i.e. title, subject, and other general properties).
	
Every document processing begins by the initialization of an object
abstraction of the document. The most usual constructor for this object is
the odfDocument() function. When an object is initialized using this function,
it brings a lot of methods allowing allowing the application to retrieve,
read, update, delete or create almost every content and style element.
Another constructor, odfMeta() is available in order to allow metadata
processing (see below). These odfXxx() methods (and others) are shortcuts
for

	OpenOffice::OODoc::Xxx->new(options)

where "Xxx" is generally "Document", for full access to the content, but
may be another specialized object such as "Manifest" or "Meta".
The long "OpenOffice::OODoc::...->new()" syntax can (and should) be avoided,
and replaced by the odfDocument(), odfMeta() or odfManitest() functions.

A document object initialization requires one or more options. The most
usual option is the file name, as in the first example. By default, this
parameter is regarded as a previously existing file. It's possible to
instantiate a document object with a new, empty document, with an
additional "create" option giving the content class of the document to
be generated. So, in our first example, the constructor could be:

	my $document = odfDocument
			(
			file		=> 'filename.odt',
			create		=> 'text'
			);

This instruction creates a new file containing a text (i.e. an
OpenDocument Text) document (and replaces any previously existing file
with the same name). However, the new file will be actually created by the
$document->save instruction, not by the object initialization. If "create"
is set, the documents are generated according to ODF templates. By default,
OODoc uses a set of templates which are included in the CPAN package, but
it's possible to use custom templates instead.

When the 'create' option is in use, the newly created document may be
formatted either in the OASIS OpenDocument format (ODF) or in the primary
OpenOffice.org 1.0 format. If an additional 'opendocument' is provided and
set to 'true', then the new document will be ODF-compliant. If the same