sfTinyDocPlugin - 1.0.0

symfony sfTinyDoc plugin

You are currently browsing
the website for symfony 1

Visit the Symfony2 website


« Back to the Plugins Home

Signin


Forgot your password?
Create an account

Tools

Stats

advanced search
Information Readme Releases Changelog Contribute
Show source

sfTinyDocPlugin

Overview

The sfTinyDocPlugin allows to generate OpenOffice and Word 2007 documents with TinyButStrong template engine.

  • History :

    The previous class was named tbsOOo. I rewrite the class to have a clean code with new methods and add some new functionnality like :

    • work with the last version of TinyButStrong
    • better support of specials characters like \n, \r, \r\n, \t
    • can generate Word 2007 documents
    • can add images
    • can merge data with native format in OpenOffice spreadsheet
    • two methods to zip and unzip the office files (zip with command line and the pecl ZipArchive)
    • and a plugin for symfony framework
  • The office formats supported :

    • OpenOffice 1.0 or OpenDocument 1.0
    • OpenOffice 2.0 or OpenDocument 1.1
    • Word 2007
  • It's useful :

    • To create word processing and spreadsheet documents.
    • To create reports, bill, orders.
    • To create mailing.
    • To create multi pages documents.
    • To use the power of the TinyButStrong template engine syntax :
      • Merge fields
      • Merge blocks (repetitive fields)
      • and more...
  • It's not :

    • To create an Office document from scratch.
    • To convert a document from OpenOffice to Word or to PDF or else. See the project PyODConverter to do that.
  • Avantages :

    • No installation of OpenOffice on the server side.
    • Work on *nix, win and other systems.
    • Templates can be created and modified easyly by designer.
    • Templates layouts and styles are made with OpenOffice or Word2007 application.
    • Data in spreadsheet are converted to native OpenOffice format with the new parameter named 'type'.
      • Useful to use with spreadsheet formulas
      • Useful to use the spreadsheet format
    • For the symfony framework
      • Template have the same location as the symfony templates.
      • Template name have the same name as the symfony templates.
      • Get the config from app.yml.
      • The method createFrom() is automatic. By default : moduleName/templates/actionNameSuccess.odt
  • Limitations :

    • Can't merge collection of objects (iterator not supported in TinyButStrong, next version), you have to transform to an array before.

      • For Propel write your own method like asArray() in the Jobeet tutorial, see day 16.
      • For Doctrine use the magic method : $result->toArray (false | true) to transform the result to an array, see : doctrine api
    • Can't change a style of the Office document by code, the styles are fix when you editing your Office document.

    • Can't merge global vars [var.xxx], use method mergeXmlField() in place of use globals vars
    • Can't merge sub-block because TinyButStrong need global vars, see headergrp syntax
  • Experimental for OpenOffice :

    • Add images dynamicaly, to make a catalog by example - The image size have to be the same as in the layout.

Installation

  • Install sfTinyDocPlugin :

    symfony plugin-install http://plugins.symfony-project.com/sfTinyDocPlugin
    
  • Optionally add the following config to app.yml :

    all:
      sf_tiny_doc_plugin:
        zip_method:    shell             # the method to zip/unzip : shell | ziparchive
        zip_bin:       zip               # the binary to zip   for 'shell' method
        unzip_bin:     unzip             # the binary to unzip for 'shell' method
        process_dir:   %SF_WEB_DIR%/tmp  # the process directory
    
  • Clear your cache :

    symfony cc
    
  • Configure the method to zip/unzip office documents :

    • Method 1 : shell (by default)

      To install Zip on Red Hat Enterprise Linux or CentOS

        yum install zip
      
    • Method 2 : ziparchive

      To install Pecl ZipArchive on Red Hat Enterprise Linux or CentOS

        yum install httpd-devel
        pecl install zip
      
  • Create a directory where to process temporary files, by example on web root :

    mkdir web/tmp
    chmod 777 web/tmp
    

My first OpenOffice text document in action (.odt)

  • Create a new module doc in your application

  • Create an action basic in doc/actions/actions.class.php

    public function executeBasic(sfWebRequest $request)
    {
      // create the document
      $doc = new sfTinyDoc();
      $doc->createFrom();
      $doc->loadXml('content.xml');
      $doc->mergeXmlField('field1', 'variable');
      $doc->mergeXmlField('field2', array('id' => 55, 'name' => 'bob'));
      $doc->mergeXmlField('field3', $doc);
      $doc->mergeXmlBlock('block1',
        array(
          array('firstname' => 'John'   , 'lastname' => 'Doe'),
          array('firstname' => 'Douglas', 'lastname' => 'Adams'),
          array('firstname' => 'Roger'  , 'lastname' => 'Waters'),
        )
      );
      $doc->saveXml();
      $doc->close();
    
      // send and remove the document
      $doc->sendResponse();
      $doc->remove();
    
      throw new sfStopException;
    }
    
  • Create an OpenOffice text document (.odt) and paste this.

    $doc->mergeXmlField() with a string
    
    [field1]
    
    $doc->mergeXmlField() with an array
    
    [field2.id] [field2.name]
    
    $doc->mergeXmlField() with an object
    
    [field3.getZipMethod]
    [field3.getZipBinary]
    [field3.getUnzipBinary]
    
    $doc->mergeXmlBlock() with an array
    
    [block1;block=begin][block1.$] [block1.firstname] [block1.lastname]
    [block1;block=end]
    Num rows : [block1.#]
    
  • Save the document as basicSuccess.odt in template directory doc/templates/

  • You can now test my first doc in a browser the result : doc/basic

    The result is something like this :

    $doc->mergeXmlField() with a string
    
    variable
    
    $doc->mergeXmlField() with an array
    
    55 bob
    
    $doc->mergeXmlField() with an object
    
    shell
    zip
    unzip
    
    
    $doc->mergeXmlBlock() with an array
    
    0 John Doe
    1 Douglas Adams
    2 Roger Waters
    
    Num rows : 3
    

and for OpenOffice calc document (.ods)

  • Change in your action

    $doc->createFrom();
    

    By

    $doc->createFrom(array('extension' => 'ods'));
    
  • Create an OpenOffice spreadsheed document (.ods) and paste the same as before.

    $doc->mergeXmlField() with a string
    
    [field1]
    
    $doc->mergeXmlField() with an array
    
    [field2.id] [field2.name]
    
    $doc->mergeXmlField() with an object
    
    [field3.getZipMethod]
    [field3.getZipBinary]
    [field3.getUnzipBinary]
    
    $doc->mergeXmlBlock() with an array
    
    [block1;block=begin][block1.$] [block1.firstname] [block1.lastname]
    [block1;block=end]
    Num rows : [block1.#]
    
  • Save the document as basicSuccess.ods in template directory doc/templates/

  • You can now test my OpenOffice calc document in a browser the result : doc/basicCalc

and for Word2007 document (.docx)

  • Change in your action

    $doc->createFrom();
    $doc->loadXml('content.xml');
    

    By

    $doc->createFrom(array('extension' => 'docx'));
    $doc->loadXml('word/document.xml');
    
  • Create an Word2007 document (.docx) and paste the same as before.

    $doc->mergeXmlField() with a string
    
    [field1]
    
    $doc->mergeXmlField() with an array
    
    [field2.id] [field2.name]
    
    $doc->mergeXmlField() with an object
    
    [field3.getZipMethod]
    [field3.getZipBinary]
    [field3.getUnzipBinary]
    
    $doc->mergeXmlBlock() with an array
    
    [block1;block=begin][block1.$] [block1.firstname] [block1.lastname]
    [block1;block=end]
    Num rows : [block1.#]
    
  • Save the document as basicSuccess.docx in template directory doc/templates/

  • You can now test the Word2007 document in a browser the result : doc/basicWord

    Tips

    $doc->createFrom();  // the defaut extension is 'odt'
    $doc->loadXml(); // the defaut XML filename is 'content.xml'
    

The basic structure of OpenDocument (OpenOffice) and Word 2007 files

  • The documents are a zip archive format with these main files :

                      OpenDocument      Word2007
    
    content           content.xml       word/document.xml
    meta              meta.xml          ? 
    settings          settings.xml      word/settings.xml
    styles            styles.xml        word/styles.xml     
    header            styles.xml        word/header1.xml     
    footer            styles.xml        word/footer1.xml     
    

    content.xml is the main file to merge in OpenOffice documents.

    word/document.xml is the main file to merge in Word 2007 documents.

    content.xml is the defaut file in loadXml() method.

    See more on :

  • The XML tags you have to know :

                HTML tags     OpenDocument XML tags     Word2007 XML tags
    
    table       <table>       <table:table>             <w:tbl>
    row         <tr>          <table:table-row>         <w:tr>
    cell        <td>          <table:table-cell>        <w:tc>
    paragraph   <p>           <text:p>                  <w:p>
    

The method to merge data

  • Before merging data, you have to load the XML file with the loadXml() method.
  • After merging data, you have to save the result of merging in the XML file with the saveXml() method.

    Each time you have to merge data with an another file you have to

    $doc->loadXml('content.xml');
    ...
    $doc->mergeXml(...);
    $doc->mergeXmlField(...);
    $doc->mergeXmlBlock(...);
    $doc->mergeXml(...);
    ...
    $doc->saveXml();
    
    
    $doc->loadXml('styles.xml');
    ...
    $doc->mergeXml(...);
    $doc->mergeXmlField(...);
    $doc->mergeXmlBlock(...);
    $doc->mergeXml(...);
    ...
    $doc->saveXml();
    
  • There two different methods to merge data, field and block

    • method : mergeXmlField($name, $data)

      MergeField it's for fields (one time)

    • method : mergeXmlBlock($name, $data)

      MergeBlock it's for repetive fields to merge all items from an array.

      Note : If you don't define the begin block and the end of the block, the fields are merged one time.

  • The two methods call the generic method : mergeXml($options, $data)

    With this method, you can pass some parameters in the $options array like :

    • name: The tag name in the template ('block' by default)
    • type: The tag type in the template ('field' | 'block' - 'block' by default)
    • data_type: The data type - only for type = 'block' ('array' by default)
    • charset: The data charset ('UTF-8' by default)
    • is_escape: If data are escaped (true by default)
    • callback: The callback to encode data ('=~encodeData' by default)

    Example :

      $doc->mergeXml(
        array(
          'name'      => 'b1',
          'type'      => 'block',
          'data_type' => 'array',
          'charset'   => 'UTF-8',
          'is_escape' => true,
        ),
        $data
      );
    

TinyButStrong templates syntax (TBS tags)

For all parameters of TinyButStrong, have a look to the TinyButStrong manual

The TBS field parameters

  • ifempty
  • if expr1=expr2;then val1;else val2
  • frm=format1|format2|format3|format4
  • magnet
  • mtype
  • ope=action

The TBS block parameters

  • block
  • $
  • #
  • nodata
  • bmagnet
  • headergrp
  • footergrp
  • splittergrp
  • parentgrp
  • serial
  • p1=val1 (for subquery, this param don't work inside a class, like for sfTinyDoc)
  • when expr1=expr2
  • default
  • several

New parameter

  • type : This parameter is only for OpenOffice spreadsheet. It fixes the value type of the cell, not the format. The format is set with OpenOffice.

    • type=currency or the shorten way type=c.

      The input data is a float.

    • type=date or type=d.

      The input data is a string 'Y-m-d' or 'Y-m-d H:i:s'.

    • type=float or type=f.

      The input data is a float.

    • type=int or type=i.

      The input data is a integer.

    • type=percentage or type=p.

      The input data is a float.

    • type=time or type=t.

      The input data is a string like 'H:i:s'.

    Note : Only one TBS field can be merge in a cell when the parameter type is set.

    Note2 : To fix the format the cell, use OpenOffice for that. Don't use frm parameter.

Examples

As in French we can said, "Un dessin vaut mieux qu'un long discours", here some examples for sfTinyDocPlugin

Bugs / Features

  • implement width and height for images in method tagXmlImage() in tinyDoc.class.php
  • optionals parameters in method sendResponse() like to fix, the download name, to convert the document ...
  • externalize zip methods in another classes

Todo

  • More documentation
  • More examples on specials TBS parameters
  • Link to download
  • Link to SVN
  • Link to trac