Contact Information
You can contact me, Joseph Colton, at either of these addresses. For e-mail:joseph@colton.byuh.edu
For mailing or visiting:
55-579 Naniloa Loop
Laie, Hawaii 96762
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program 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.
For you can save and use this code if you like: base_code
ooolib License
ooolib - This Perl Library is built to create OpenOffice.org documents.
Copyright (C) 2003,2004 Joseph ColtonGNU General Public License
There is a local copy of the GNU General Public License here and you can also view the license at http://www.gnu.org/licenses/gpl.html.
Setup and Installation
The setup and installation for ooolib 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 you will need to have a machine running GNU/Linux and have 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 in
each version.
doc/ This is the documentation directory.
examples/ This directory contains example programs.
LICENSE This is the GNU General Public License. This project is
licensed under the GNU GPL.
ooolib.pl This is the ooolib Perl Library.
README The readme file.
RELEASE This is the release notes for the current version.
TODO This file contains information about tasks that are not yet
completed.
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. Here I will try to explain what each of the example programs currently does and what looking at it is good for.
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");
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:
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 "&"
"'" becomes "'"
"<" becomes "<"
">" becomes ">"
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.