root/plugins/sfOpenOfficePlugin/README

= sfOpenOffice Plugin =

== Authors ==

  * [joao.paulo.barbosa] [at] [gmail] (promag at irc)
  * [tiago.ribeiro] [at] [gmail] (fixe at irc)

== Notes ==

  * Plugin package is currently on development.
  * This wiki page may change without notice!
  * We are trying, with good results, to make the plugin easy to use, despite the server side administration required to use it.
  * The plugin will have several examples

== Introduction ==

This is the ultimate solution for server side report generation! Stop searching and continue to read. Imagine making beatiful reports with dynamic data and charts, easy paging, custom images and more. Just use the !OpenOffice.org suite and add easy PHP code to turn the document dynamic. The integration with Symfony resembles typical templates. Therefore learning to use this plugin is so straightforward as coding Symfony templates. You also have the power to choose the output format such as PDF, Microsoft Word or Excel and much more.

Check out the example on attachments. The !OpenOffice.org document report.odt resulted in report.pdf. The action executeReport only sets the variable $items.

== Motivation ==

Server side document generation is a common need on most of web applications and intranets. Many solutions lack WYSIWYG document sketching capabilities. Therefore they are programatically designed (for instance with sfFPDF). Despite being dynamic (in data) they are rigid in design/layout. Re-layout often requires hard code changes and this is cumbersome and not productive to a programmer.

== How it  works ==

At development time, instead of writing HTML/PHP templates you write !OpenOffice.org documents with PHP code. See tutorial to learn how to write PHP code in !OpenOffice.org documents. Then, in order to make the document a template, a new task needs to be executed. Much like propel-build-model, the new task ooffice-create-document will preprocess the !OpenOffice.org document to ease runtime document generation.

!OpenOffice.org zips the document content, style and definitions into one file (for instance ODT). One of those files is content.xml which will have the document body (with our styled PHP code). So the new task will unzip it and transform all files inside with a XSLT so that all styled PHP code becomes markup PHP code (which can be evaluated). The task also creates a empty view class associated with the document action. This way the action won't result in a sfPHPView but in a sfOpenOfficeDocumentView.

At runtime all the work is done in the sfOpenOfficeDocumentView. It grabs all the variables defined in the action (much like sfPHPView) and executes all the files mentioned above. Then it zips the executed files (which is an !OpenOffice.org document with dynamic data) and ask !OpenOffice.org to do its magic, for instance, rendering the document to PDF. The result can be sent to client, server printer (for office intranets or online store orders), email or just saved.

== Requirements ==

  * !OpenOffice.org 2.0.4 or superior
  * Shell zip/unzip commands (configurable on app.yml)
  * Xvfb to allow running !OpenOffice.org from PHP (I'm not a system administrator so I ask, if you have a better solution please email me)

== Setup ==

First of all take a look to plugins/sfOpenOfficePlugin/config/ooffice-*-env.* scripts. If those settings doesn't match your system then copy the corresponding file to the project config folder and change the necessary settings.

This plugin is shipped with a module to setup and test the !OpenOffice.org. This module gives you detailed instructions step by step. So , in order to use it you must enable it on settings.yml:

  {{{
    all:
      .settings:
        enabled_modules:      [default, sfOpenOfficeSetup]
  }}}


=== osX ===

If you have the stable version of symfony, and you want to try our test module, you need to do:
{{{
ln -s plugins/sfOpenOfficePlugin/modules/sfOpenOffice apps/aplication/modules/sfOpenOffice
}}}
Check this ticket to see why.

In your global app.yml, you should add the following parameters:
{{{
all:
  sfOpenOfficePlugin:
    ooffice_cmd: /Applications/OpenOffice.app/Contents/MacOS/program/soffice
    temp_dir:    '/tmp'
    unzip_cmd:   'unzip -d'
}}}

To create your first dynamic template, you should use our task:
{{{
symfony ooffice-create-document frontend sfOpenOffice test.odt
}}}

=== Linux ===

In order to setup correctly !OpenOffice.org, you need to activate the license. We suggest that you run OpenOffice in X with the user apache.

Change to the apache user (here apache):

{{{
sudo su apache
}}}

If you don't have possibility to run X, use a vncserver or Xvnc.
{{{
vncserver :9 -nohttpd -rfbport 5901
}}}

Connect to remote host with a vnc client
{{{
vnc host.com:5901
}}}

Then, just run !OpenOffice.org in display 9
{{{
$PATH_TO_OOFICE_BIN_DIR/soffice -display :9
}}}

A license agreement dialog should appear. Proceed with the installation.

=== Windows ===

== Test it ==

After installing the plugin, check the test module. For this, you have to enable the module in your settings.yml:
{{{
all:
  .settings:
    enabled_modules: [sfOpenOffice]
}}}

Then, just go to:
{{{
http://servername/app_dev.php/sfOpenOffice
}}}

== Tutorial ==

So you have an !OpenOffice.org document and you want to make it dynamic. First of all let's assume we are working in the application app and in the module mod. The document we created is report.odt. Now create the documents directory under the module directory:

{{{
mkdir apps/app/modules/mod/documents
}}}

and put the report.odt under this new directory. Then, on the project root directory, do:

{{{
symfony ooffice-create-document app mod report.odt
}}}

this will pre-process the document to allow customization of the document at a lower level. This will be discussed later. It also creates a new view class which will be in charge of runtime document generation.

Now we need to add a new action to the module actions:

{{{
vim apps/app/modules/mod/actions/actions.class.php 
}}}

and add the action with the same name as the report (without extension):

{{{
public function executeReport()
{
   // query the database or do anything else that can be done in an action
}
}}}

If the actions returns other value than sfView::SUCCESS then it won't generate the document. It will fall back to the regular template. For instance, if the return value is sfView::ERROR then it will result in the template reportError.php.

Now we are ready to go. If you try http://servername/app_dev.php/mod/report it should open the PDF document. PDF is the default format but you can change to any format supported by !OpenOffice.org in the view class (explained later).

== Issues ==

For each document generation the !OpenOffice.org is executed by the apache user in a virtual X. The overhead of this schema is the !OpenOffice.org startup, which takes few seconds. We tested other schema where the the virtual X is static and there is one instance of !OpenOffice.org running. The tests showed great performance improvement. So its a matter of time to get this schema easy to configure. Remember that this is not a Symfony issue but a administration issue. Fell free to drop here suggestions.

== Future ==

These are features we would like to see implemented in the near future:

  * Cache suport

== References ==

Comming soon