=head1 NAME
OpenOffice::OODoc::Meta - Access to document properties (metadata)
=head1 DESCRIPTION
The OpenOffice::OODoc::Meta class is a specialist derivative of
OpenOffice::OODoc::XPath for XML members which describe the metadata
of OpenOffice.org documents.
=head2 Methods
=head3 Constructor : OpenOffice::OODoc::Meta->new(<parameters>)
Short Form: ooMeta(<parameters>)
See OpenOffice::OODoc::XPath->new
The XML member loaded by default is 'meta.xml'.
Example:
$my meta = OpenOffice::OODoc::Meta->new
(file => 'document.sxw');
returns a new object which represents the metadata of the
OpenOffice.org "document.sxw".
=head3 addKeyword(text)
Adds the given text to the list of document keywords if not already
found.
Example:
$meta->addKeyword("GED");
$meta->addKeyword("office");
$meta->addKeyword("tech watch");
=head3 creation_date()
Without argument, returns the document's creation date in
OpenOffice.org (ISO-8601) format.
Example of returned value:
2002-11-12T08:22:50
The returned value can be converted in standard numeric time format
with the ooTimelocal() function.
With argument, inserts the given string (without checking) as the
creation date. The argument, if any, must comply with the OOo
(ISO-8601) date format. The ooLocaltime() function can be used in
order to convert a regular Perl time() value in OOo format.
The OpenOffice.org desktop software never changes this value, but
this method allows the user to read or write it.
See also date().
=head3 creator()
Without argument, returns the document creator's name. The creator
is generally the author of the last update. See also initial_creator().
With argument, modifies the document author's name.
=head3 date()
Without argument, returns the document's date of last modification,
in OpenOffice.org format.
With argument, inserts the given string (without checking) as the
last modification date. The argument, if any, must comply with the
OOo date format (ISO-8601). The ooLocaltime() function can be used
in order to convert a regular Perl time() value in OOo format.
The returned value can be converted in standard numeric time format
with the ooTimelocal() function.
=head3 description()
Without argument, returns the contents of the document properties
"Description" field.
With argument, inserts the given text in the "Description" field.
=head3 editing_cycles()
Without argument, returns the number of edit sessions (i.e. saves,
under OpenOffice.org or StarOffice). Or, technically, the number of
versions.
With argument, modifies this number without checking.
=head3 editing_duration()
Without argument, returns the total editing time for the document,
in OpenOffice.org date/time format.
For example, the returned string can be:
P2DT11H27M33S
which in this case means that the document has been edited for 2
days, 11 hours, 27 minutes and 33 seconds.
With argument, forces a new value into this property without
checking.
=head3 generator()
Without argument, returns a label representing the signature of the
software which generated the document. Example of signature:
"OpenOffice.org 1.1.1 (Linux)"
With argument, inserts any signature.
=head3 initial_creator()
Like creator(), but apply to the creator of the first version of the
document. The OOo desktop software never updates this value, but this
method allows the user to read or write it.
=head3 keywords()
Without argument, returns a list of the document's keywords. In a
list context, the result is a table where each element is a keyword.
In a scalar context, the keywords are returned in a single character
string, each of which is separated by a comma and a space.
With arguments, adds a list of keywords to the existing one. The
only checking carried out is to see if the keyword already exists,
if so it is not added.
=head3 language()
Without argument, returns the content of the language variable.
Example:
fr_FR
With argument, changes the content of this variable without
checking.
=head3 removeKeyword(keyword)
Removes the given keyword if it exists.
=head3 statistic()
Without argument, returns a hash which represents the entire
"statistics" section of the metadata. The content depends on the
type of document.
Text
'meta:table-count' => number of tables
'meta:image-count' => number of images
'meta:object-count' => number of OLE objects
'meta:page-count' => number of pages
'meta:paragraph-count' => number of paragraphs
'meta:word-count' => number of words
'meta:character-count' => number of characters
Spreadsheet
'meta:table-count' => number of sheets
'meta:cell-count' => number of non-empty cells
'meta:object-count' => number of objects (images, etc.)
Example:
my $meta = OpenOffice::OODoc::Meta->new("invoice.sxc");
my %stat = $meta->statistic;
print "This invoice contains " .
"$stat{'meta:cell-count'} cells and " .
"$stat{'meta:table-count'} pages\n";
With arguments, you can modify (or falsify ?!) all or some of the
statistical data and even create attributes which are not created by
the OpenOffice.org or StarOffice software. Arguments are passed in
pairs [key => value] and handled without checking.
Example:
$meta->statistic
('meta:table-count' => '4', 'status' => 'OK');
This example forces the number of tables to 4 (whatever the reality)
and adds an arbitrary attribute 'status' with value 'OK'.
Note : Such forced attributes do not upset the function of
OpenOffice.org which ignores them. They could therefore be useful in
programs which handle documents out of reach of the end user.
However, if such a document is then edited or updated by
OpenOffice.org or StarOffice (using currently released versions),
these "foreign" attributes will be lost and the software will
replace what it considers to be the "real" values to those
attributes it manages.
=head3 subject()
Without argument, returns the document's subject.
With argument, adds a new subject to the document.
=head3 title()
Without argument, returns the document's title.
With argument, adds a new title to the document.
=head3 user_defined()
Returns a list of the four fields which appear in the User tab of
the Properties dialog in OpenOffice.org. These fields are called, by
default, "Info 1" to "Info 4". The end user can change their names
and their content.
The list is returned in the form of a hash of 4 elements whose
keywords represent the field names and whose values represent their
content.
By supplying a similar hash of 4 elements as an argument, this
method deletes and replaces the existing content.
If the number of elements supplied in the hash is less than 4, the
last fields are left untouched. If, however, the hash contains more
than 4 elements, only the first 4 are taken into account.
=head2 Properties
As for OpenOffice::OODoc::XPath
=head2 Exported functions
=head3 ooLocaltime([$time_value])
Converts the numeric time given in argument to an OpenOffice-compliant
date (ISO-8601). The argument type is the same as for the standard
Perl localtime() function, i.e. a number of seconds since the "epoch".
It can be, for example, a value previously returned by a time() call.
Without argument, returns the current local time in OOo format.
The result of this function can be used as an argument for the date()
or creation_date() methods of OpenOffice::OODoc::Meta.
Example:
$doc->date(ooLocaltime());
This line puts the current time as the last modification date in the
document (assuming $doc is an OpenOffice::OODoc::Meta object).
=head3 ooTimelocal($oodate)
Converts a date in OOo format (ISO-8601) in a regular Perl numeric
time format, i.e. a number of seconds since the "epoch". So, the
returned value can be processed with any Perl date formatting or
calculation function.
Example:
my $date_created = ooTimelocal($doc->creation_date());
$lt = localtime($date_created);
$elapsed = time() - $date_created;
print "This document has been created $date_created\n";
print "$elapsed seconds ago";
This sequence prints the creation date of a document in local time
string format, then prints the number of seconds between the creation
date and now.
Note: This function requires the Time::Local Perl module.
=head1 AUTHOR/COPYRIGHT
Copyright 2004-2005 by Genicorp, S.A. (http://www.genicorp.com)
Initial developer: Jean-Marie Gouarne (http://jean.marie.gouarne.online.fr)
Initial English version of the reference manual
by Graeme A. Hunter (graeme.hunter@zen.co.uk)
License:
- Genicorp General Public Licence v1.0
- GNU Lesser General Public License v2.1
Contact: jmgdoc@cpan.org
=cut