Login / Status
developer.Resource
Home . Documentation . Document Library . Extension Manuals
Sponsors
hosted by punkt.deTYPO3 and Open Source Magazine

1.3. Administration

Install HTMLDOC

First you'll need to install htmldoc on your server. You can either used a preconfigured binary package or build it from the sources.

Installing HTMLDOC with a precompiled package for Linux or Windows

If your server is running linux or windows, you may be able to use one of my precompiled binary  packages. Just download it from http://www.jens-ellerbrock.de/T3X_htmldoc_linux-1_8_25-z.t3x and install it via the Extension manager. This is version 1.8.25. A 1.8.24 is also available on  http://www.jens-ellerbrock.de/T3X_htmldoc_linux-1_8_24-z.t3x.

I also provide a version for win32 on http://www.jens-ellerbrock.de/T3X_htmldoc_windows-1_8_25-z.t3x this is version 1.8.25.

Leave the htmldoc_path parameter empty if you use these extensions and they will autoconfigure the pdf_generator.

This packages are only offered as a courtesy, don't bug me if they don't work on your server.

Build HTMLDOC from source

Go to http://www.htmldoc.org and download the  HTMLDOC source. You may also use SVN to obtain the latest version (recommended).

Now compile and install.

Installing HTMLDOC on a server to which you have telnet/ssh access

Please refer to the compilation and installation instructions provided with HTMLDOC (./configure; make; make install for Linux/posix or simply compile with Visual Studio on windows)

Installing HTMLDOC on a server to which you only have ftp access

Well, you're out of luck, unless you do have access to a similar machine. Here's what I did to make it work for my provider who uses Linux:

  1. Find out what the absolute path of your web root is (see phpinfo() for example. in my case /www/htdocs/something)

  2. Configure using this path appended with “htmldoc” (configure --prefix=<web root>/htmldoc)

  3. Compile (make; make install)

  4. Now upload the <web root>/htmldoc directory to your server so that it is written to the same absolute directory where it came from. (You may delete documentation and man pages first)

  5. Don't forget to chmod the htmldoc binary (which will be in <web root>/htmldoc/bin/htmldoc) to executable.

Verify that HTMDOC is running fine

  1. Generate a dummy.html file:

    <html><head><title>Test Title</title><body>Test Body</body></html>

  2. if you have shell access call HTMLDOC: <path>/htmldoc --webpage -f dummy.pdf dummy.html and check that a dummy.pdf file is generated

  3. Check that the following dummy.php file creates a dummy.pdf file too. Make sure that the webserver_user has write access to the directory you try it in. (/typo3temp should work fine)

    <?php system('<path>/htmldoc --webpage -f dummy.pdf dummy.html');?>

  4. Don't forget to clean up and delete your files

Update .htaccess

You will need to update your .htaccess if you want the links to your PDF files be static (i.e. <alias.pdf>). This change is necessary to forward all requests to /<...>.PDF files  to typo3's index.php.

ErrorDocument 404 /error.html 
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule   ^typo3$  /typo3/index_re.php
RewriteRule   ^[^/]*\.html$  index.php
RewriteRule   ^[^/]*\.pdf$  index.php

Install the Extension

  1. Download the newest Extension using the Extension Manager/Extension Repository

  2. Install the Extension using the Extension Manager

  3. Configure the Extension.

  4. Update your .htaccess if you want to use “static” PDF filenames

Available Options

htmldoc path

Here you should set the absolute (or relative to typo3 root) path to HTMLDOC (including the binary). Additional parameters to the htmldoc command can be added via the htmldoc global parameters or on a by-template basis via the Constant Editor. If you use one of the precompiled binary packages just leave this path empty.

Note: You may change this parameter to 'export LC_TIME=”<your locale>”; <path to htmldoc>' if you want to set a specific locale for the HTMLDOC command. This may be desirable if you want to set the format of the $DATE string in HTMLDOC footers or headers.

htmldoc global Parameters

Here you can set parameters that will be appended to the htmldoc command. By default this is “--t pdf13” which will instruct htmldoc to generate a Adobe ver 1.3 PDF file. The necessary “--webpage” parameter is added internally.

htmldoc append Parameters

Here you can set parameters that will be appended to the end of htmldoc commandline. By default this is “2> typo3temp/htmldoc.log” which will log the result of the htmldoc command to typo3temp/htmldoc.log. You may want to change that to “2> /dev/null” on Linux/Unix.

simulateStaticPdf

This parameter will define whether the link to the PDF files will be a static one (i.e. <alias>.pdf) or dynamic ones (index.php?id=12&type=123). If you enable this you will need to update your .htaccess.

Disable gzip compression

If this parameter is set and you have gzip-compression turned on for the Frontend ( [FE][compressionLevel] in the installation  tool) the generated PDF's will not be handled by the additional gzip-compression. It is highly recomended to leave this parameter at default (on) since PDF-files incorporate their own compression and you will only gain little additional compression. Additionally you may get problems with browsers that pass the stream to acrobat without decompressing it (e.g. Netscape 4.08).

typeID

This parameter defines the typeId that is used for the extension. Normally you will not need to change it.

Add a link in your Typoscript Template using makePdfLink

To add the a link to the PDF page you can wrap any content element in a link using stdwrap.postUserFunc. The following code gives some examples:

[...]
100 = IMAGE
100.file = fileadmin/pdf_link.gif
100.stdWrap.postUserFunc = tx_pdfgenerator->makePdfLink
[...]
[...]
110 = TEXT
110.value = printable version
110.postUserFunc = tx_pdfgenerator->makePdfLink
110.postUserFunc.target = _blank
[...]
[...]
temp.PDF = TEXT
temp.PDF.value = pdf
temp.PDF.postUserFunc = tx_pdfgenerator->makePdfLink
temp.PDF.postUserFunc.include_post_vars = 1
page.120 < temp.PRINT
[...]

If  you use the Template Auto-Parser extension and you want to put the link somewhere on your page, you may need to put it in a COA with another element. If you want to place it below the content for example you would change

  subparts.content < styles.content.get

to something like

  subparts.content = COA
  subparts.content {
    10 = CONTENT
    10 < styles.content.get
    20 < temp.PDF
  }

and define temp.PDF like above.

Please note that the link will be generated as a USER_INT object by default, i.e. that the link will be generated after the page has been pulled from the cache. If you want to go for maximum performance you can disable that with the parameter postUserFunc.no_user_int = 1 which will generate and cache the link. This is only recommended if you are sure that there are no USER_INT objects on the page that set POST or GET parameters. If you don't understand what i'm writing about leave it at default.

Add a link in your Typoscript Template using openPdfLink

Altenatively you can also use the function tx_pdfgenerator->openPdfLink which will generate the opening tag for the link. You will need to generate the closing </a> tag yourself´. Example:

page.36= USER_INT
page.36.userFunc = tx_pdfgenerator->openPdfLink
page.37=TEXT
page.37.value = Link to PDF
page.38=HTML
page.38.value = </a>

Add a link in your Typoscript Template using getPdfTarget

If you just need the target of the pdf link you can use the function getPdfTarget. Amongst other things this can be useful with  templavoila. Example:

lib.pdflink = USER_INT
lib.pdflink.userFunc = tx_pdfgenerator->getPdfTarget
lib.pdflink.userFunc.include_post_vars = 1

Customizing the PDF-Page via Typoscript

The PDF is rendered based on a very simple template. You can easily update the pdf_generator page object to contain additional information or content elements on every PDF page. One especially interesting use is to add special HTML comments to control the behavior of HTMLDOC. See the htmldoc documentation (on http://www.easysw.com/htmldoc/htmldoc.html#HTMLREF) for details. Some of these parameters (the header and footer comments) will be automatically generated with the parameters set via the Constant Editor (see previous chapter).

You don't have to put any of the following lines into your template, they are already there. They are noted here just for reference purposes.

pdf_generator = PAGEpdf_generator {  typeNum = {$extension.pdf_generator.typeNum}  config.pageGenScript = EXT:pdf_generator/gen_pdf.php  config.admPanel = 0  config.xhtml_cleaning = 0  config.USERNAME_substToken =  config.ftu = 0  config.disableCharsetHeader = 1  config.prefixLocalAnchors = 0  50 = CONTENT  50 < styles.content.get}

Generating a page-dependent logoimage

You can generate and supply a page dependent logoimage that can be used in headers and footers. You will need to generate a html-comment that contains the path to the image as

<!-- LOGOIMAGE=/path/filename -->

You can use a GIFBUILDER object to do so by using something like the following typoscript

temp.logoimage = GIFBUILDERtemp.logoimage {  XY = 10, 10  backColor = red}pdf_generator {  400 = IMG_RESOURCE  400.file < temp.logoimage  400.stdWrap.wrap = <!-- LOGOIMAGE="|" -->} 

If you use LOGOIMAGE_NOCACHE instead, the generated pdf will not be cached. This is desirable if you want to have dynamic or random logoimages.

Customizing the PDF-Page via the Constant Editor

You can set several options on a per-template basis with the Constant Editor. These options will either result in special parameters appended to the htmldoc command or special html-comments that also control the behaviour of htmldoc. See the htmldoc documentation (http://www.easysw.com/htmldoc/htmldoc.html#CMDREF) for details. The following parameters can be set:

Property:

Data type:

Description:

Default:

htmldoc browserwidth

string

If set controlls the width of the page in pixels. Set this to control scaling of tables and pictures. If empty it defaults to 680

htmldoc header_left

string

Sets the left header on all PDF pages. The following special strings are supported:

$$: Inserts a single dollar sign in the header.

$CHAPTER: Inserts the current chapter heading.

$CHAPTERPAGE, $CHAPTERPAGE(format) : Inserts the current page number within a chapter or file. When a format is specified, uses that numeric format (1 = decimal, i = lowercase roman numerals, I = uppercase roman numerals, a = lowercase ascii, A = uppercase ascii) for the page numbers.

$CHAPTERPAGES, $CHAPTERPAGES(format): Inserts the total page count within a chapter or file. When a format is specified, uses that numeric format (1 = decimal, i = lowercase roman numerals, I = uppercase roman numerals, a = lowercase ascii, A = uppercase ascii) for the page count.

$DATE: Inserts the current date.

$HEADING: Inserts the current heading.

$LOGOIMAGE: Inserts the logo image; all other text in the string will be ignored. The path to the logimage has to be set separately (htmldoc logoimage).

$PAGE, $PAGE(format): Inserts the current page number. When a format is specified, uses that numeric format (1 = decimal, i = lowercase roman numerals, I = uppercase roman numerals, a = lowercase ascii, A = uppercase ascii) for the page numbers.

$PAGES, $PAGES(format): Inserts the total page count. When a format is specified, uses that numeric format (1 = decimal, i = lowercase roman numerals, I = uppercase roman numerals, a = lowercase ascii, A = uppercase ascii) for the page count.

$TIME: Inserts the current time.

$TITLE: Inserts the document title.

The header is set by inserting a comment in the html document prior to passing it to htmldoc. See the note in Adminstration about setting the locale if you want to set the format for $DATE and $TIME.

htmldoc header_center

string

Sets the centered header. See above for format.

$TITLE

htmldoc header_right

string

Sets the right header. See above for format.

htmldoc footer_left

string

Sets the left footer. See above for format.

htmldoc footer_center

string

Sets the centered footer. See above for format.

htmldoc footer_right

string

Sets the right footer. See above for format.

$PAGE

htmldoc size

string

Sets the size of the generated PDF. The size can be A4, Letter or Universal. Custom sizes are specified by the page width and length separated by the letter "x" to select a custom page size. Append the letters "in" for inches, "mm" for millimeters, or "cm" for centimeters.

Depends on compilation options of htmldoc

htmldoc top

string

If set specifies the top margin. The default units are points (1 point = 1/72nd inch); the suffixes "in", "cm", and "mm" specify inches, centimeters, and millimeters, respectively.

htmldoc bottom

string

If set specifies the botttom margin. The default units are points (1 point = 1/72nd inch); the suffixes "in", "cm", and "mm" specify inches, centimeters, and millimeters, respectively.

htmldoc left

string

If set specifies the left margin. The default units are points (1 point = 1/72nd inch); the suffixes "in", "cm", and "mm" specify inches, centimeters, and millimeters, respectively.

htmldoc right

string

If set specifies the right margin. The default units are points (1 point = 1/72nd inch); the suffixes "in", "cm", and "mm" specify inches, centimeters, and millimeters, respectively.

htmldoc bodyfont

string

If set specifies the  font that is used for the PDF page unless another font is specified. (Remember, css is not yet supported).

htmldoc fontsize

string

If set specifies the  base fontsize that is used for the PDF page unless another size  is specified. (Remember, css is not yet supported).

htmldoc headfootfont

string

If set specifies the  font that is used for the footers and headers.

htmldoc headfootsize

string

If set specifies the  fontsize that is used for the footers and headers.

htmldoc logoimage

string

Sets the path to the logoimage for the page headers and footers. The supported formats are BMP, GIF, JPEG, and PNG. Don't forget to add $LOGOIMAGE to one of your headers or footers.

htmldoc no_links

boolean

If checked the PDF file will not contain clickable links.

Unchecked

htmldoc additional_params

string

Here you can set additional parameters for the htmldoc command that are not covered by the parameters above.

string_search[1-4]

string

Using this parameter together with string_replace you can remove/replace certain parts of your html-file prior to passing it to htmldoc. One example is to remove the “Back” link in the recipe extension. You can do this (when using english language) with

string_search1 = “<A href="javascript:history.go(-1);">Back</A>”

and  string_replace1 = “”

You can actually use string_search[5-n] as long as they are all set

string_replace[1-4]

string

See string_search[1-4]

regexp_search[1-4]

string

The same as string_search, but for regular expressions. The search and replace parameters must be valid regular expressions that will be passed to preg_replace.

You can actually use regexp_search[5-n] as long as they are all set

regexp_replace[1-4]

string

See regexp_search[1-4]

Reference for tx_pdfgenerator->makePdfLink, tx_pdfgenerator->openPdfLink and tx_pdfgenerator->getPdfTarget

Note that not all Propertys make sense for all functions. For example: the getPdfTarget function doesn't support the Target property.

Property:

Data type:

Description:

Default:

attachment

int

This controls the setting for the Content-Disposition header. Normally a

Content-Type: application/pdf

Content-Disposition: inline

header is generated. If this parameter is set to 1

Content-Type: application/pdf

Content-Disposition: attachment

and if it is set to 2

Content-Type: application/octet-stream

Content-Disposition: attachment

is sent instead.

Option 1 will force Internet Explorer to open the PDF file in a new Acrobat Reader window. Netscape will open it inline (same as normal). If it is set to 2 both IE and Netscape will query the user what to do with the file. (Tested on win2k with IE6 and Netscape 7)

The change is created by attaching a “attachment=<...>” parameter to the URL.

0

filename

string

Sets the a filename for the Content-Disposition header. Since most browsers seem to ignore this it is of limited use.

include_post_vars

boolean

If set to 1 the received POST variables will be appended as GET variables to the URL. This is useful if you want to generate dynamic data (like search result for example).

IMPORTANT NOTE: if you set this parameter it is possible that passwords and other sensible information will get encoded in the URL and thus be logged in proxy-logs for example.

false

no_blur

boolean

If this is set, no onFocus="blurLink(this); code is added to the link. You can also use noBlur instead.

no_user_int

boolean

If set the generated link will not be a non-cached USER_INT object. Use this for slightly better performance if you have no frontend plugins that act as USER_INTobjects and set GET or POST variables. If you don't understand what i'm writing leave it at default.

This parameter is only supported for the makePdfLink function.

false

simulateStaticPdf

boolean

Overrides the global setting of the extension.

Target

string

Sets the target for the link

ATagParams

string

Ads additional parameters to the <a..> tag.