desktop results from the CPAN

desktop
ODF-lpOD
view release on metacpan or search on metacpan
lib/ODF/lpOD/Tutorial.pod view on Meta::CPAN
        $doc->get_part(CONTENT)->needs_update(FALSE);
        $doc->save;

The C<save()> method is prevented from writing back any part whose update
flag is C<FALSE>. Of course this flag may be reset to C<TRUE> at any time
through a subsequent use of C<needs_update()>.

Note that it's a good practice to switch off the update flag of the C<CONTENT>
part as long as you just need it for read only, in order to avoid useless
processing.

While the default target of C<save()> is the source file itself, you may
specify an alternative output through a C<target> optional parameter:

        $doc->save(target => "newdoc.odt");

In such a case, the source file remains unchanged. A new one is created,
reflecting all the possible changes (with the exception of changes made in
parts whose update flag had been set to C<FALSE>, if any).

=head2  Creating a new document

When you want to create a new document, you must use the C<odf_new_document()>
constructor, with a mandatory argument that specifies the document type. The
possible document types are C<'text'>, C<'spreadsheet'>, C<'presentation'>,
or C<'drawing'>. As an example, the following instruction creates a new
spreadsheet document:

        my $doc = odf_new_document('spreadsheet');

This constructor returns a C<odf_document>, just like C<odf_get_document()>.
However, there is no associated source file, so when you want to C<save()> it
you must provide the C<target> parameter.

The same job could be done using another style:

        my $doc = odf_document->create('spreadsheet');

The example below could be a one-liner program that creates and saves a new
empty ODF presentation:

        odf_new_document('presentation')->save(target => "demo.odp");

=head2  Leaving a document

When your application no longer needs to do anything with a previously loaded
or created document, no particular action is required. However, in a process
that handles multiple successive documents, it's B<strongly recommended> to
execute an explicit call of an instance destructor, namely the C<forget()>
method, for each document that is no longer used:

        $doc->forget;

Unless this explicit instruction, you could be faced with significant memory
leaks.

=head1  Playing with document metadata

An office document owns a set of so-called I<"metadata">. Metadata is "data
about the document". For the end user, it may be got (and sometimes changed)
through the "File/Properties" sub menu of a typical desktop software. lpOD
allows the programmer to select, read or write any piece of metadata.

=head2  Pre-defined metadata

A document may contain some global metadata. The most commonly used ones are
the I<title>, the I<subject>, the I<description>, the I<creation date>, the
I<modification date>, the I<creator>, and others. All that is stored in the
C<META> document part. We can get access to any piece of metadata through the
C<META> context. Note that the C<META> document part is directly usable as the
context for metadata access, so we don't need to look for a particular I<body>
element in this part:

        my $meta = $doc->get_part(META);

or:

        my $meta = $doc->meta;

From this context, a set of get/set, self-documented accessors, is available.
The first instruction below displays the existing document title, and the
second one sets a new title that replaces the old one:

        say $meta->get_title;
        $meta->set_title("New Title");

The one-liner below displays the document title:

        say odf_document->get("mydoc.ods")->meta->get_title;

Some C<set_xxx()> metadata accessors provide default values when called without
argument. As examples, C<set_modification_date()>, that sets the date/time
of last modification, automatically puts the current system date, while
C<set_editing_cycles()> automatically increments the document revision count
by one, when called without explicit values:

        $meta->set_modification_date;
        $meta->set_editing_cycles;

The C<set_creator()> accessor specifies the author of the last modification.
It may be used in order to write any arbitrary string but, without argument,
if uses the system user name of the current process (provided that Perl can get
such an information from the operating system).

Note that lpOD provides such accessors as C<set_creation_date()> or
C<set_initial_creator()> that allows the programmer to change the date and
the author's name of the initial version, that is generally not allowed with
an interactive graphical editing software.

A piece of metadata whose data type is I<date> should be locale-neutral; it's
stored according to the ISO-8601 format. It's returned as is by the read
accessors. However, the write accessors allow the user to provide a numeric
date (that is automatically converted). In addition, lpOD provides a
C<numeric_date()> function that translates an ISO date into a numeric date.

lpOD deliberately allows you to provide any arbitrary value for any piece of
metadata. If you want to set a creation date that is later than the last
modification date, or decrement the editing cycle count, it's your choice.

=head2  Document keywords
( run in 2.172 seconds using v1.01-cache-2.11-cpan-39bf76dae61 )