RTF Generator Class


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

Additional materials


[^ up]

Introduction


The main purpose of the class is generating RTF files, which are compatible with the most popular office packet - Microsoft Office. There are a lot of situations, when there is a need of some application which could form certain information in a format, which could be easily downloaded from internet server and then opened by any internet user in Microsoft Word - RTF Generator can help here.

This script is written in PHP and uses no additional components (plugins or else). It works on Unix or Win32 platforms and require only PHP 4.x.x (or later) installed. As there is no plugins required for the script to work, it could be easily installed on server, or even be used in a local network to create some reports, or anything else.

The script uses special markup language which is HTML-based but not HTML itself. The language is very flexible and allow to create perfect-looking documents as there are a lot of options available to control document look.

With this script it is possible to create very complicated tables having full control over their look at the same time. It is possible to merge cells, change background color, control width and height of the cells.

The script supports images (.JPG and .PNG) which could be inserted into your RTF document. Besides it supports multiple pages layout with page numbering, headers and footers.


[^ up]

Usage Example

The script installation is pretty simple. As it uses only PHP, it doesn't have any other requirements. To install the script you should only place the main script file (rtf_class.php) and configuration file (rtf_config.inc) in a server folder and that's all - it is ready to use.

To generate RTF file you'll need just a few lines of PHP code. You should create RTF Class object, then pass marked text to it and receive ready RTF code. After that you could either pass this code to the user as a file stream or save it to disk for future use.

Here is the simplest example of using the script, in this example the file will be passed to user as a file stream:

This is very simple example of creation of an .xls file:



<?


   
// including main script file:
   
include "rtf_class.php";
   
// this will be the name of our RTF file:
   
$file_rtf "Test.rtf";
   
// HTTP headers saying that it is a file stream:
   
Header("Content-type: application/octet-stream");
   
// passing the name of the streaming file:
   
Header("Content-Disposition: attachment; filename=$file_rtf");
   
// here is the text of our RTF file:
   
$html_text "Hello <b>World!<b>";
   
// creating class object and passing to it the path to configuration file:
   
$rtf = new RTF("rtf_config.inc");
   
// passing the text to the object:
   
$rtf->parce_HTML($html_text);
   
// getting RTF code:
   
$fin $rtf->get_rtf();
   
// streaming the file to the user:
   
echo $fin;
?>

Another example of the script shows how to save RTF file to disc:



<?


   
// including main script file:
   
include "rtf_class.php";
   
// this will be the name of our RTF file:
   
$file_rtf "SimpleTest.rtf";
   
// here is the text of our RTF file:
   
$html_text "Hello <b>World!</b>";
   
// creating class object and passing to it the path to configuration file:
   
$rtf = new RTF("rtf_config.inc");
   
// passing the text to the object:
   
$rtf->parce_HTML($html_text);
   
// getting RTF code:
   
$fin $rtf->get_rtf();
   
// saving the file to disk:
   
$fp fopen($file_rtf"w");
   
fwrite($fp$fin);
    echo 
"Generated file <b>".$file_rtf."</b> was saved to disc.";
   @
fclose($fp);

?>


[^ up]

Rules

When creating a template for RTF Generator you should stick to the following rules:
  1. Do not use crossed tags
    wrong: <font face=roman> some text <p> some text </font> some text
    correct: <font face=roman> some text </font><p><font face=roman> some text </font> some text
  2. Do not try to use "impossible" tables. If table tags are placed incorrectly - the result is unpredictable.
  3. Do not use "nested" tables - they are not supported


[^ up]

Tags Reference

To prepare a good-looking RTF document you will need to use different tags which allow apply different formatting properties to your document.


[^ up]

General tags

General tags are used to design your text in general. With the help of these tags you can create bold, italic, underlined text. Besides it is possible to create subscript and superscript, and insert line-breaks. These tags are identical to HTML tags.

Bold text

purpose: to create bold text
usage: <b>this text will be bold</b>

Italic text

purpose: to create italic text
usage: <i>this text will be italic</i>

Underlined text

purpose: to underline text
usage: <u>this text will be underlined</u>

Superscript

purpose: to create superscript text
usage: <sup>this text will be lifted up</sup>

Subscript

purpose: to create subscript text
usage: <sub>this text will be lowered</sub>

New line

purpose: to start new line
usage: <br>This is a new line.
* Do not mix this tag with paragraph tag, it is just a line break.

Horizontal rule

purpose: to create horisontal rule
usage: <hr>


[^ up]

Font tag

purpose: This tag is used to set font parameters of the text
usage: <font [size] [face] [color]>any text</font>

It is possible to control the size, face and color of the font. Size should be in points. Font color should be only in #XXXXXX format, no color names like "black", "red" or alike.

example:


<font size=14 face=roman color=#FF0000>

This text will be 14 point in size and have face Times New Roman and the text will be red 

</font>


[^ up]

Paragraph tag

purpose: This tag is used to set paragraph formatting
usage: <p [align] [before] [after] [lines] [lindent] [rindent] [findent] [lead] [tsize]>Paragraph text

This tag doesn't require end tag, so - you don't have to insert any </p> after the end of the paragraph. Paragraph ends just where the next paragraph starts.

Below are the tabulation controls, they are used to control position and the filling of the tabulations <tab>

tabulation example:


<p lead=dot,dot tsize=50,100>Name<tab>price1<tab>price2

<p lead=dot,dot tsize=50,100>Customer 1<tab>23<tab>56

<p lead=dot,dot tsize=50,100>Customer 2<tab>40<tab>60

To understand the system of tabulations it is better to perform some tests by yourself

paragraph example:


<p align=right before=10 after=0 lines=0 lindent=10 rindent=0 findent=-5>

This paragraph will be right-aligned, the space before the paragraph will be 10 millimeters, 

the space after the paragraph will be minimal, space between lines - minimal, 

the paragraph will be indented from left margin by 10 millimeters, from right margin - 

by 0 millimeters and the first line of the paragraph protrudes by 5 millimeters. 


[^ up]

Image tag

purpose: This tag is used to images into your RTF document
usage: <img src= width= height= [border] [wrap] [align] [anchor] [left] [top] [script]>

With the help of this tag you can insert images into your RFT documents. The script supports two image formats - .JPG and .PNG. The images can be inserted either from a local disk or from World Wide Web. The full control over image size, position and alignment. Besides special option is introduced to control text wrapping. In the configuration file there is a possibility to limit the maximum image size.

* mm - means millimeters, don't try to use pixels as in HTML the page have certain size in millimeters and all the measurements should be in millimeters.
** obligatory - means that this option must be present in this tag to guarantee correct image representation.
*** if you are using script-generated images - make sure that you are using 'http://' call, because the script first should be excecuted by server and generate an imge, and after that this image will be ready by Generator.

example:


1. <img src=logo.png width=60 height=14 wrap=around align=left border=1 anchor=page>

2. <img src=http://your_server.com/get_image.php?get_var=345 script=jpg width=60 height=14 wrap=around align=left border=1 anchor=page>




[^ up]

Table tags

purpose: This tag is used to images into your RTF document
usage: <table [border] [align] [valign] [width] [bgcolor] [bord_color] [color] [rowkeep] [tablekeep]>

<tr [border] [align] [valign] [bgcolor] [color]>
<td [border] [align] [valign] [bgcolor] [color]>table cell text</td>
</tr>
</table>

These tags give you the possibility to create very complicated and good-looking tables.

  • <table [border] [align] [valign] [width] [bgcolor] [bord_color] [color] [rowkeep] [tablekeep]>...</table> - the whole table settings
    • border= - table border (0 - no; 1 - yes - or string value like "t,b,r,l" - means: top,bottom,right,left border)
    • bord_color= - table border color in HEX - example - #ff00ff
    • align= - horizontal table alignment on the page
      • right - right aligned
      • left - left aligned
      • center - centered
      • justify - justified
    • valign= - vertical alignment for all the table cells
      • top - top aligned
      • middle - middle aligned
      • bottom - bottom aligned
    • width= - table width (either in mm or in percent from page width - example - 50%)
    • bgcolor= - table background in percent from black - example - 50 (50% of gray)
    • color= - table background color in HEX - example - #ff00ff
    • rowkeep= yes- prevent table rows from splitting between pages
    • tablekeep= yes- keeps all table rows on single page
  • <tr [height] [border] [align] [valign] [bgcolor] [color]> ... </tr> - table row settings
    • height= - vertical height of a given row
    • border= - row border (0 - no; 1 - yes - or string value like "t,b,r,l" - means: top,bottom,right,left border) - if omitted - is taken from table settings
    • align= - horizontal alignment for the row - if omitted - is taken from default settings
      • right - right aligned
      • left - left aligned
      • center - centered
      • justify - justified
    • valign= - vertical alignment for the text in row cells - if omitted - is taken from table settings
      • top - top aligned
      • middle - middle aligned
      • bottom - bottom aligned
    • bgcolor= - row background in percent from black - example - 50 (50% of gray - if omitted - is taken from table settings
    • color= - row background color in HEX - example - #ff00ff - if omitted the value is taken from table settings
  • <td [border] [align] [valign] [bgcolor] [color]>cell text</td >- cell settings
    • colspan= - number of colomns spanned by the cell
    • rowspan= -number of rows spanned by the cell
    • border= - cell border (0 - no; 1 - yes - or string value like "t,b,r,l" - means: top,bottom,right,left border) - if omitted - is taken from row settings
    • align= - horizontal alignment for the cell - if omitted - is taken from row settings
      • right - right aligned
      • left - left aligned
      • center - centered
      • justify - justified
    • valign= - vertical alignment for the cell - if omitted - is taken from row settings
      • top - top aligned
      • middle - middle aligned
      • bottom - bottom aligned
    • width= - cell width (either in mm or in percent from table width - example - 30%)
    • bgcolor= - cell background in percent from black - example - 50 (50% of gray - if omitted - is taken from row settings
    • color= - cell background color in HEX - example - #ff00ff - if omitted the value is taken from row settings

* be careful when using colspan and rowspan tags - if you're trying to build impossible table - the result will be unpredictable
** if some options are omitted they are taken from the default settings, which are set in the configuration file

example:


<table width=100 border=1>

   <tr>

      <td colspan=2 bgcolor=30 valign=top>First cell</td>

   </tr>

   <tr>

      <td align=left color=#ff0000>next cells</td><td align=right>another one</td>

   </tr>

</table>


[^ up]

Multi-page control

Using this set of tags you will be able to create multi-paged documents with the possibility to control page layout. You can insert headers and footers, number the pages through the whole document, insert page breaks.

Page break

purpose: to start new page
usage: <new page>

Just place this tag where you need to start a new page.

Headers and footers

purpose: to create headers and footers for all the document pages
usage: <header>Your header text</header>
<footer>Your footer text </footer>

For header and footer you can use all the tags to describe text formatting bold, italic (general tags). Ypu can even put tables and images into the page headers and footers - in this case these element will be repeated on every page. The alignment of header and footer is set in the main configuration file. You can use only one header and only one footer for all the pages.

Page numbers

Another feature of the script - page numbers. The settings are in the main configuration file. There is almost full control under the page numbers - start value, vertical and horizontal alignment. Also, page numbers can be controlled by document sections.

Document sections

The latest feature of the script is document sections. The point is that you can handle different sections within one RTF file. Every section can have its own page numbering, headers and footers. The section tag is much like page break tag - so they should not be put together, or you'll get an empty page within your document.

usage: <new section [pn_start] [pn_align] [nobreak] [landscape] [columns]>

To create headers and footers for the section, just place appropriate tags after the section tag. The vertical alignment of the page numbers through the whole document is set in the configuration file.


[^ up]

Hyperlinks

purpose: Hyperlinks can be used for providing navigation within and outside the document

Navigation within the document:
usage: <a local=go_to_this_id>any text</a>

. . .
<id go_to_this_id>

Navigation outside the document:
usage: <a file=path_to_file>any text</a> - mind that "file" should be one_word

By using this feature you can organize something like table of contents or anything else with the possibility of jumping from one to the other parts of the documents. Also you can create links to the other documents to be opened using one mouse click. In MS Word you will need to do CTRL+Click to follow the link.



Additional materials


[^ up]

Main Configuration File

Here is the example of the script configuration file with explanations.


<?


//    CONFIGURATION FILE FOR RTF GENERATOR CLASS
//    SOME OF THESE SETTINGS COULD BE OVERWRITTEN BY USING SPECIAL TAGS
//    IN CASE OF OMMITTING THE TAGS, TEXT IS FORMATTED USING THESE SETTINGS

/////
// ATTENTION!
// all measurements are given in millemeters, but you can use the following units:
//  'cm'   : //centimeters
//  'mm'   : //millimeters
//  'q'    : //alias of 'kyu'
//  'kyu'  : //Q/kyu
//  'in'   : //inches
//  'pt'   : //alias of 'pts' (points)
//  'pts'  : //points
//  'picas': //picas
//  'twips': //twips
/////

// ALSO - you can set special units everywhere, example:
//  $pg_height="12in"; // will mean 12 inches
//  <table width=2cm> // will set table width to 2 cm
// and alike.


$default_units "mm"// default measurement units

//---------------------------------------------------
// DEFAULT PAGE SETTINGS
//---------------------------------------------------
$pg_width=210// page width (mm)
$pg_height=297// page height (mm)
$mar_left=19// left margin width (mm)
$mar_right=19// right margin width (mm)
$mar_top=19// top margin height (mm)
$mar_bott=19// bottom margin height (mm)

$page_orientation "portrait"// portrait or landscape
//$page_orientation = "landscape"; // portrait or landscape

$header_align "left"// default header align - "left", "right", "center"
$footer_align "left"// default footer align - "left", "right", "center"
$head_y=1// space between the top edge of the page and the top header (mm)
$foot_y=10// space between the bottom edge of the page and the bottom footer (mm)

$page_numbers 1// page numbers, if  < 0 - no page numbers; if >= 0 page numbers start from the specified number
$page_numbers_valign "bottom"// vertical alignment of the page numbers ("top" or "bottom")
$page_numbers_align "center"// horisontal alignment of the page numbers ("left", "center", "right")

$page_numbers_autoinsert "0"// 0 = disable, 1 = enable autoinsertion.
                                // Use <cpagenum> to insert pagenumber when disabled.
                                // Valign and align only work in enabled mode


//---------------------------------------------------
// DEFAULT HYPER LINK SETTINGS
//---------------------------------------------------
$h_link_color "#009900"// default color for hyper links
$h_link_fontf "garamond"// default link font face [arial,roman,sym,courier,seriff,garamond]
$h_link_fonts "12"// default link font size in pt
$h_link_fontd "i"// default link decoration [ul - underline, i - italic, b - old]

//---------------------------------------------------
// DEFAULT FONT AND PARAGRAPH SETTINGS
//---------------------------------------------------

$font_face "arial"// default font face [arial,roman,sym,courier,seriff,garamond]
$font_size "10";  // font size in pt
$def_par_before "0"// space before paragraph (mm) (better set to 0, when using tables and set by tag)
$def_par_after "0"// space after paragraph (mm) (better set to 0, when using tables and set by tag)
$def_par_align "left"// default paragraph align.
                                     // "left", "right", "center", "justify"

$def_par_lines 0// space between lines (mm). if 0 - minimal is taken
$def_par_lindent "0"// paragraph left indent (mm) (better set by tag)
$def_par_rindent "0"// paragraph right indent (mm) (better set by tag)
$def_par_findent "0"// first line indent (mm) (better set by tag)

//---------------------------------------------------
// DEFAULT TABLE SETTINGS
//---------------------------------------------------
$tbl_def_border 1// table border (1 - yes; 0 - no) or string value:
                     //   "t,b,r,l" - means: top,bottom,right,left borders
                     //   you can vary these letters to get the result you need
$tbl_def_width "100%"// table width (in mm or in % from page width)
$tbl_def_cellpadding 0// default cellpadding (mm)
$tbl_def_align "left"// default table align on the page (center, right, left)
$tbl_def_valign "top";// default vertical text align for all the cells (top, middle, bottom)
$tbl_def_bgcolor "0"// table background (0 - no, or % from black)
$row_def_align "left"// default horizontal text align for all the cells (center, right, left)

//---------------------------------------------------
// DEFAULT IMAGE SETTINGS
//---------------------------------------------------
$image_size 500// maximum allowed image size in kb

$img_def_border 0// image border (1 - yes; 0 - no)
$img_def_src "";  // default image src (used when no, or a bad source specified)
$img_def_width 20// default image width (mm)
$img_def_height 20// default image height (mm)
$img_def_left 0// space between the anchor and image left edge (mm)
$img_def_top 0// space between the anchor and image top edge (mm)
$img_def_space 5// space between the image and the text (mm)
$img_def_align "left"// image align on the page (center, right, left)
$img_def_wrap "around"// type of text wrapping for image (no, updown, around)
$img_def_anchor "par"// linking anchor for image
                         // para = image is linked to the current paragraph
                         // page = image is linked to the current page (top left page corner)
                         // margin = image is linked to margin (top left page corner including margins)




////  FONT CHARACTER SET

//$default_charset = 238; // sets default character set
$default_charset 130// sets default character set
/*
ANSI                   = 0
Default                = 1
Symbol                 = 2
Invalid                = 3
Mac                    = 77
Shift Jis              = 128
Hangul                 = 129
Johab                  = 130
GB2312                 = 134
Big5                   = 136
Greek                  = 161
Turkish                = 162
Vietnamese             = 163
Hebrew                 = 177
Arabic                 = 178
Arabic Traditional     = 179
Arabic user            = 180
Hebrew user            = 181
Baltic                 = 186
Russian                = 204
Thai                   = 222
238Eastern European    = 238
PC 437                 = 254
OEM                    = 255
*/


?>


[^ up]

FAQ

I receive different questions about the aspects of using the script, some of them I've included into this FAQ. But before you decide to ask any question - study this manual carefully, may be the answer is already listed here.

If you have any idea of how to improve the script, have an idea of the script/program which could be of the great help for people or if you need some special script - I'll be ready to help.

  1. I want to insert ™(TradeMark) symbol, is it possible with your script?
  2. Is there a limit to the size of the tagged text? Eventually, I'll be printing huge documents of more than 150 pages. Will I be able to do it in a single pass, or will I have to break it into smaller pieces?
  3. The image in your demo does not currently work. I tried to insert one, I view the source and it looks like the image is there, but does not display.
  4. I am very interested in your product, does buying it also give me the upgrades?
  5. I need something that can convert the whole of an HTML into rtf, including images. Can your script do this?
  6. Is it possible to avail an evaluation copy of the script?

  1. I want to insert ™(TradeMark) symbol, is it possible with your script?
    Yes it is possible, you can use symbol code just like in HTML to insert any special symbol you like. For example to insert ™ symbol you should print: &#U153, to insert © symbol: &#U169 etc. To know the code of the symbols you could use Start->Programs->Accessories->Character Map.

  2. Is there a limit to the size of the tagged text? Eventually, I'll be printing huge documents of more than 150 pages. Will I be able to do it in a single pass, or will I have to break it into smaller pieces?
    If fact - there is no limits - except that PHP itself can supervise the maximum size of the variables - but it is more than 20 mb.
    But if you are going to generate such huge documents - be prepared that final RTF file will be big and certainly - it'll take some time for the script to render such document, especially if there are a lot of tables in it.

  3. The image in your demo does not currently work. I tried to insert one, I view the source and it looks like the image is there, but does not display.
    The RTF files produced by the script are compatible to Microsoft Word 95/97/2000 and Office XP. But you should remember, that images are shown only in page layout view. If your Word is set to Normal view - the images won't be shown (the headers and footers also). To show them you should select page layout view (View -> Page Layout).

  4. I am very interested in your product, does buying it also give me the upgrades?
    Certainly - in case you buy it - you'll get all the upgrades, but frankly speaking - I don't think there will be a lot of upgrades as the script is all-sufficient. But If you'll need some extra functions, and there will be possibility to include them into my script - I'll do my best to help you.

  5. I need something that can convert the whole of an HTML into rtf, including images. Can your script do this?
    No - my script doesn't convert HTML to RTF. To create RTF files special markup language is used, which is HTML-based, but not HTML itself.
    HTML format has so many variations, that it is next to impossible to guarantee the correct work of such a converter. Using my converter it is possible to insert images into an RTF file, and do other things - but you'll need to use some special tags.

  6. Is it possible to avail an evaluation copy of the script?
    No, it is next to impossible to create evaluation copy of the script. It is written in PHP and cannot be compiled into a single file and goes in open source.


[^ up]

Author & Copyright

License Agreement:

If you buy RTF Generator you can use it as you like it and anywhere you will need it. You can do what ever you want with it except selling the script itself. If you're going to include my script into some commercial project for selling, you should include the script price into the budget and every of your customer should together with your software buy the license for my script. It is also possible to buy a distribution license for the script. If you have other plans - we can discuss them.

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.