TXT Generator Class


http://paggard.com/projects/txt.generator/

[^ up]

Introduction


TXT Generator is a PHP script, the younger member of the "Generators" family. The script is aimed to creation of the plain text files (TXT). Certainly, there is no use to "just create TXT file using PHP" it is simple - so, TXT Generator is powered by additional features in order to make it possible to create complicated layouts using just plain text. Sometimes there is a need to stick to plain text - and here TXT Generator can help you.

The script is using user-friendly input format, which is actually XML template. This template can be generated dynamically (like dynamic php web-pages) and then passed to the TXT Generator (or stored for future use) - and TXT Generator will convert this XML template into TXT file.

TXT Generator has many features which will help you to make your generated TXT files look not as a bunch of lines of text: paragraphs with alignment, custom width, borders and page orientation; ordered and unordered lists; and even tables, with variable width, in-cell text alignment, table orientation on page.


[^ up]

Usage Example

It is very simple to use the class, so, the main part you should concentrate your efforts - is to create good XML template to pass to the class. Creation of the template is pretty much alike to the process of creation dynamic HTML pages using PHP - but in this case you do not echoing the results to the user's browser, but pass the ready template to TXT Generator class. The documentation how to create an XML template is given below in this document. When the template is created you can either save it on disk for future use or pass directly to the XLS Generator to get the plain text, which can be saved on disc or sent by mail, or passed to the user's browser.

This is very simple example of class usage:


<?
// UNCLUDING THE THE MAIN CLASS FILE
require_once "txt.generator/cl_txt_generator.inc";

// CREATING XML TEMPLATE
$xml_template "<?xml version=\"1.0\"?>
<document>
    <head>
        <author>Paggard [paggard@paggard.com]</author>
        <title>TXT Generator sample</title>
    </head>
<body>
    <align hor=\"center\">Hello World Sample</align>

    <br />
    <table border=\"1\"  width=\"35%\" align=\"center\" text_align=\"center\">
        <tr>
            <td>Hello</td>
            <td>World!</td>
        </tr>
    </table>
</body>
</document>
"
;

// MAIN CLASS CALL
$xml = new txt($xml_template);

// SAVING THE RESULT TEXT TO DISK
$fp fopen("simple_usage.txt""w");
fwrite($fp$xml->get_result_file());
@
fclose($fp);
?>


[^ up]

Rules

Only mind that XML has certain rules:
  1. All templates must have <?xml version="1.0"?> at the very beginning.
  2. All the document data should be enclosed into <Document> </Document> element
  3. All element tags must be closed like this: <Document> </Document>
    or like this <Align />
  4. Attributes must always be quoted:
    <Table border="0"> </Table>
    <align hor="center" />
  5. All elements must be properly nested:
    wrong: <tr><td> </tr></td>
    right: <tr><td> </td></tr>
  6. Document can contain comments: <!-- some comment -->


[^ up]

Head Section

<?xml version="1.0"?>
<Document>
    <Head>
        <author>Author Text</author>
        <title>Document Title</title>
        <subject>Document Subject</subject>
        <description>Document Description</description>
    </Head>
...
</Document>

Document template may or may not have the header section. Header section is always enclosed in <Head> . . . </Head> tags and may have the following child elements:

All the above elements may or may not be present within the <Head> section of the document. If even one of the elements will be defined, the result text will have the header section containing the defined elements (Author, Title etc.). It will look like this:

--------------------------------------------------------------------------------
 Author:                                 Author Text          
 Title:                                  Document Title                   
 Subject:                                Document Subject            
 Description:                            Document Description            
--------------------------------------------------------------------------------


[^ up]

Body Section

<?xml version="1.0"?>
<Document>
    ...
    <Body>

Main Text of the Document


    </Body>
</Document>

Body of the document contains the main document layout. It should be always enclosed into <Body> ... </Body> tags. These elements may contain the following tags to describe text formatting:


[^ up]

<Align hor="center"> . . . </Align>

Horizontal alignment of the text and objects; can be one of the following - "left", "right", "center" and "justify".


[^ up]

<br /> or <line />

Adds line break


[^ up]

<hr />

Adds horizontal rule


[^ up]

<p> . . . </p>

Defines paragraph. This element can have the following parameters:


[^ up]

Lists

<list type="ordered">
   <li> . . . </li>
   <li> . . . </li>
</list>

Tag structure to define ordered or unordered lists. Type attribute may have the following values : "ordered" or "unordered"

[^ up]

Example:

   1. Item 1
   2. Item 2
      +  Item 1
      +  Item 2
   3. Item 3
   4. Item 4
   


[^ up]

Tables

<table width="50%" border="1" align="right" text_align="center">
<tr>
    <td>Right aligned Table</td>
</tr>
<tr>
    <td>Cell One</td>
    <td>Cell Two</td>
</tr>
</table>

Tag structure to define tables. Table consists of rows and columns, there are no colspan and rowspan tags - instead of them you can specify exact number of cells in the ach row that you need. The row will be equally divided between all the cells.

<Table> element may have the following attributes:


[^ up]

Example of the simple XML template

<?xml version="1.0"?>
<document>
    <head>
        <author>Paggard [paggard@paggard.com]</author>
        <title>TXT Generator sample</title>
        <subject>To show the class in action</subject>
    </head>

<body>

<align hor="center">
TXT Generator Class
</align>
<line />

<p align="right">One Ring to rule them all. One Ring to find them.<br />
One Ring to bring them all and in the darkness bind them.<br />
In the Land of Mordor where the Shadows lie.<br />
</p>

<table border="1"  width="35%" align="center" text_align="center">
<tr>
    <td>PHP</td>
    <td>-></td>
    <td>TXT</td>
</tr>
</table>

<p align="justify">TXT Generator is a PHP script, the younger member of the "Generators" family. 
The script is aimed to creation of the plain text files (TXT). Certainly, there is no 
use to "just create TXT file using PHP" - this is simple - so, TXT Generator is powered 
by additional features in order to make it possible to create complicated layouts using 
just plain text. Sometimes there is a need to stick to plain text - and here TXT Generator can help you.
</p>

<table border="1"  width="100%" align="center">
<tr>
    <td>This script is commercial and can not be distributed freely. </td>
</tr>
<tr>
    <td>the price for the script is:</td>
    <td>34 USD  </td>
</tr>
</table>

<br />

Lists
<list type="ordered">
   <li>Item 1</li>
   <li>Item 2</li>
        <list type="unordered">
           <li>Item 1</li>
           <li>Item 2</li>
           <li>Item 3</li>
           <li>Item 4</li>
        </list> 
   <li>Item 3</li>
   <li>Item 4</li>
</list> 
<br />

Tables
<table width="80%" border="1" align="right" text_align="center">
<tr>
    <td>Right aligned Table</td>
</tr>
<tr>
    <td>Cell One</td>
    <td>Cell Two</td>
</tr>
</table>

</body>
</document>


[^ up]

Author & Copyright

Vadim Kiparenko paggard@paggard.com
If you will have any question of suggestions - feel free to contact me directly - I'll try to respond as soon as possible.

© 2004. All Rights Reserved. This class is a commercial software, if you are interested in purchasing it - contact me.