OpenOffice.org Perl Library (ooolib-perl)

Version 0.1.8

Documentation

Table of Contents

  1. Table of Contents
  2. Information
  3. Setup and Installation
  4. Application Programming Interface (API)
  5. Library Internals

Information

Information about the ooolib-perl project. I am interested in seeing how the ooolib is being used. If you are using ooolib in a program or on your website, please email me and let me know.

Contact Information

You can contact me, Joseph Colton, at either of these addresses. For e-mail:
josephcolton@gmail.com

For mailing or visiting:
55-579 Naniloa Loop
Laie, Hawaii 96762

ooolib-perl License

ooolib-perl - This Perl Library is built to create OpenOffice.org documents.
Copyright (C) 2003-2006 Joseph Colton

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.

This library 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
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

Setup and Installation

The setup and installation for ooolib-perl is really quite easy. Because the library is written in Perl, there is no compiling. You only need to have the requirements and use the require statement in your program.

Requirements

In order to use ooolib-perl you will need to have a machine running GNU/Linux and have either the Archive::Zip module or the zip command installed. To view the resulting documents you will need to have OpenOffice.org 1.1 Beta or later.

Contents

Below are the files and directories included with the source for ooolib:

ChangeLog	This file contains information about changes to ooolib-perl
		in each version.
doc/		This is the documentation directory.
examples/	This directory contains example programs.
ooolib.pm	This is the ooolib-perl module.
README		The readme file.
TODO		This file contains information about tasks that are not yet
		completed.
mime.types	This file contains mime type information you can use with Apache, etc.

Example Programs

There are currently very few example programs. The number and use of the example programs are subject to change as the feature set of ooolib grows.

Application Programming Interface (API)

The Application Programming Interface or API is just the collection of functions you use to create programs that use ooolib.

Basic Outline

Perl scripts using ooolib need a few basic things. You need to use the module and you need to create the document by specifying what type of document you are creating. Finally you need to create the document with the generate command. This is about the shortest a script can be: #!/usr/bin/perl use ooolib; $doc = new ooolib("sxw"); $doc->oooSet("builddir", "."); $doc->oooSet("author", "The Author"); $filename = $doc->oooGenerate("basic.sxw");

For you can save and use this code if you like: base_code

oooSet - Setting Properties

Sets variables used in creating and processing documents.
Synopsis:
&oooSet(NAME, <DATA>);
Description:
oooSet can only be called after oooInit. This function sets options such as the author, subject, bold, italics, etc. The first argument, NAME, refers to what is to be set. Each NAME argument has different options that are needed. Here are the current names with the that they require:
  • "title" - Takes a single string value that is used as the title of the document.
  • "author" - Takes a single string value that is used as the name of the author for the document.
  • "subject" - Takes a single string value that is used as the subject of the document.
  • "comments" - Takes a single string value that is used as the comments for the document.
  • "builddir" - Takes a single string that is supposed to contain the path for the creation of the document.
  • "keyword" - Takes a single string containing a single word that is to be added to the keywords for the document. This may be used multiple times to add multiple keywords to the document.
  • "meta[1-4]-name" - Takes a single string containing the title of a user defined variable.
  • "meta[1-4]-value" - Takes a single string containing the value of a user defined variable.
  • "cell-loc" - Takes x and y coordinates in a spreadsheet. The next oooData call will print to the resulting cell.
  • "column-width" - Takes x as the column number and a width in centimeters. (Sorry for those of you who use inches. I guess I have spent too much time in foreign countries. 1 inch = 2.54 cm.)
  • "cell-left" - Moves the writing cell one to the left.
  • "cell-right" - Moves the writing cell one to the right.
  • "cell-up" - Moves the writing cell up one.
  • "cell-down" - Moves the writing cell down one.
  • "cell-auto" - Takes x and y values. After each oooData call the writing cell is incremented by these x and y values.
  • "justify" - Takes a single argument of "right", "left", "center", or "block". The next text will then be justified accordingly.
  • "bold" - Takes a single argument of either "on" or "off".
  • "italic" - Takes a single argument of either "on" or "off".
  • "underline" - Takes a single argument of either "on" or "off".
  • "text-color" - Takes a single argument of six hex digits in the form RRGGBB where RR is the red, GG is the green, and BB is the blue for the color of the text. You may also select the following options "red", "green", "blue", "black", "white", and "default".
  • "text-bgcolor" - Takes the same argument at "text-color" except it is instead applied to the background or highlighting of the text.
  • "text-size" - Takes a single argument that must be a number for the size of the font. The following text will be written in this size. The exception is the headings.
  • "text-font" - Takes a single argument for the font. The following are valid fonts:
    • "Arial"
    • "Bitstream Vera Sans"
    • "Bitstream Vera Serif"
    • "Bookman"
    • "Courier"
    • "Courier 10 Pitch"
    • "Helvetica"
    • "Lucidabright"
    • "Lucidasans"
    • "Lucida Sans Unicode"
    • "Lucidatypewriter"
    • "Luxi Mono"
    • "Luxi Sans"
    • "Luxi Serif"
    • "Symbol"
    • "Tahoma"
    • "Times"
    • "Times New Roman"
    • "Utopia"
    • "Zapf Chancery"
    • "Zapf Dingbats"
Return Value:
On successful completion oooSet returns the string "ok". If there is a problem, oooSet will return the string "error" and an error message will be available by calling oooError.

oooData - Documents Data

Takes data and formats it for use in the document.
Synopsis:
&oooData(STYLE, TEXT);
Description:
oooData can only be called after oooInit has been called. It takes a string STYLE and a string of TEXT then uses this information to create the data in the content.xml file. The TEXT is run through the character filter oooCleanText, then the STYLE is looked up.
In some cases, the style needs to have features such as bold, italics, right, center, or block justification added. This is also handled by this function call.
This is a list of the different styles currently available:
Return Value:
Return the string "ok" on successful completion and the string "error" if there is a problem.

oooSpecial - Special Data

This function creates special types of data for documents.
Synopsis:
&oooSpecial(STYLE, <ARGS>);
Description:
oooSpecial takes a single argument for a style and then optional additional arguments required to carry out the style. Below are the current styles:
Return Value:
Return values vary, but if you get "ok" then everything worked. If you get "error" then there is a problem. All other return values also indicate things worked out correctly. For other return values see the description of the different styles.

oooGenerate - Document Creation

Creates the end document file.
Synopsis:
&oooGenerate;
&oooGenerate(FILENAME);
Description:
The oooGenerate function is either left empty or is passed a single string argument, FILENAME, that is used to determine the filename for the document being created.
In the event that a FILENAME is picked, oooGenerate will make sure the filename ends with the correct file extension. If it is not present, oooGenerate will append the correction extension and create the file.
If no FILENAME is supplied, oooGenerate will create a a name consisting of the date and the pid number of the processes running ooolib, and the correction file extension.
Return Value:
Once oooGenerate has successfully completed, it will return a string containing the complete path of the newly created document. If there is an error, oooGenerate will return the string "error" and an error message will be available by calling oooError.

oooError - Error reporting

Gives error messages to help in debugging code.
Synopsis:
&oooError;
Description:
oooError returns a string containing the last error message. If two errors are reported to oooError, it will only return the last error.
Return Value:
A string containing the last error message.

Library Internals

If you are interested in working on the inside of the library you will probably want to know a little bit about how it is setup.

Internal Variables

oooCleanText

This function prepares a text string to be included in the XML for OpenOffice.org documents.
Synopsis:
&oooCleanText(TEXT);
Description:
oooCleanText takes a string, TEXT, and replaces special characters that conflict with the text of the XML for the OpenOffice.org documents. This is the order of the substitutions:
"&" becomes "&amp;"
"'" becomes "&apos;"
"<" becomes "&lt;"
">" becomes "&gt;"
Return Value:
Once the text has been modified, the resulting text is returned.

oooWriteMeta

Writes the meta.xml file that is included in the document.
Synopsis:
&oooWriteMeta(BUILDDIR, TYPE);
Description:
The function oooWriteMeta takes two string BUILDDIR and TYPE as input and uses the information previously entered using commands like oooSet to build the meta.xml file.
Return Value:
Return "ok" on success and "error" if an error occurs.

oooWriteContests

Writes the content.xml file.
Synopsis:
&oooWriteContents(BUILDDIR, TYPE);
Description:
The function oooWriteContents takes two strings BUILDDIR and TYPE as input and uses the information previously entered using commands like oooSet and oooData to build the content.xml file.
Return Value:
Returns "ok" on success and "error" if an error occurs.

oooWriteStyles

Writes the styles.xml file.
Synopsis:
&oooWriteStyles(BUILDDIR, TYPE);
Description:
The function oooWriteStyles takes two strings BUILDDIR and TYPE as input and uses the type of document to build a styles.xml file.
Return Value:
Returns "ok" on success and "error" if an error occurs.

oooWriteMimetype

Writes the mimetype file.
Synopsis:
&oooWriteMimetype(BUILDDIR, TYPE);
Description:
The function oooWriteMimetype takes two strings BUILDDIR and TYPE as input and uses the type of document to build a mimetype file.
Return Value:
Returns "ok" on success and "error" if an error occurs.

oooWriteSettings

Writes the settings.xml file.
Synopsis:
&oooWriteSettings(BUILDDIR, TYPE);
Description:
The function oooWriteSettings takes two strings BUILDDIR and TYPE as input and uses the type of document to build a settings.xml file.
Return Value:
Returns "ok" on success and "error" if an error occurs.

oooWriteManifest

Writes the manifest file.
Synopsis:
&oooWriteManifest(BUILDDIR, TYPE);
Description:
The function oooWriteManifest takes two strings BUILDDIR and TYPE as input and builds the manifest.xml file.
Return Value:
Returns "ok" on success and "error" if an error occurs.

oooTimeStamp

Returns a time stamp.
Synopsis:
&oooTimeStamp;
Description:
The oooTimeStamp function calculates the date and returns a string indicating the date.
Return Value:
A string in the form YYYY-MM-DDTHH:MM:SS.

oooDateTime

Returns the date and time: yyyy, mm, dd, hh, mm, ss
Synopsis:
&oooDateTime;
Description:
Gets the date and time information, then returns the results.
Return Value:
Returns an array (year, month, day, hour, minute, second)

oooCellUpdate

Updates max values and current values for x and y
Synopsis:
&oooCellUpdate;
Description:
The function oooCellUpdate is called after data is entered in a cell. It updates the cell location if the cell-auto x and y have been set. Next it calls oooCellCheck to make sure the resulting x and y values are still valid.
Return Value:
None

oooCellCheck

Tests to make sure the x and y values are legal
Synopsis:
&oooCellCheck;
Description:
Checks and makes sure the x ($cellhash{x}) and y ($cellhash{y}) values are between the maximum ($MAXX, $MAXY) and minimum ($MINX, $MINY) allowed values. If they are too high or too low they are set to the max or min value.
Return Value:
None

oooStyleName

Returns the name of the style to use
Synopsis:
&oooStyleName(STYLE);
Description:
The oooStyleName function keeps track of which combinations of bold, italics, underline, right, left, center, and block justification have auto style aliases. If there is one it is returned, if not it is created and returned.
Return Value:
Returns a string that contains the style that should be used for the text.