Joomla! 1.0.x and 1.5.x have a built-in feature that allows Web site visitors to generate PDF files from articles they are viewing. The feature works quite well with western languages, yet fails to create satisfactory PDF files for Asian languages, such as Chinese and Japanese. For Joomla! 1.0.x there exists patches to make it perform well with Asian languages. For instance, Joomla! Taiwan released localized Traditional Chinese Joomla! 1.0.x, which includes a properly working PDF generating subsystem.
Because Joomla! 1.5.x uses UTF-8 encoding and allows specifing the font used in generating PDF for different languages, it basically supports a wide variety of languages in its PDF feature. With correctly installed font metrics, script and font itself, Joomla! 1.5.x indeed can correctly create PDF files in Asian languages. However, there are still problems when it comes to support Asian languages.
The current Joomla! (1.5.7) uses TCPDF v2.5.000. This version of TCPDF always generates PDF files with whole font embedded unless the font is one of the core fonts. That creates two problems for Asian fonts, and both are caused by the font's usually large size.
The first problem is the size of the PDF generated. Since it includes the whole font, the size of the PDF is at least that of the font. The other problem is that the server needs to allocate a large chunk of memory because TCPDF loads the whole font into memory when making a PDF. A 15 MB Traditional Chinese font requires at least around 40 MB memory to process.
Here we will provide instructions to allow PDF creation without embedding the whole font for Traditional Chinese articles so that the resulting files' sizes are in the order of a few hundred kilo-bytes instead of several mega-bytes. With some minor modifications, similar instructions should be able to apply to other Asian languages.
Download TCPDF
As mentioned earlier, TCPDF v2.5.000 supplied in Joomla! 1.5.7 doesn't provide an option not to embed the complete font file. Fortunately the newer version of TCPDF does. So our plan is basically to replace the version in Joomla! with the latest version of TCPDF and make it to work with Joomla!.
Please head for the official TCPDF Web site and download the latest version. Uncompress the ZIP file into your local hard drive. A folder named tcpdf will be created and contain TCPDF source codes.
Create Font Script
Even though we don't want TCPDF to put the whole font file in the PDF, we still have to let it include some font metrics information. You will need to run a couple of tools included in the TCPDF release package to create a php script that contains some essential font information.
In order to allow Chinese PDF to be properly displayed in Adobe Acrobat without embedding the actual font file, the font to be used must be a part of Acrobat installation already. If you check the Resource\CIDFont folder under Acrobat's installation directory, you should find several font files for Asian languages. For Traditional Chinese, Adobe Acrobat provides a AdobeMingStd-Light.otf, which is the font we use. (We assume your local machine is a Windows computer because one of the commands you have to use is a DOS program.)
Now change into the folder fonts\utils under the tcpdf folder that contains TCPDF source codes. Copy the font file AdobeMingStd-Light.otf into this folder, and rename the file to adobemingstd-light.otf. Open a DOS command prompt window, and then execute the following command to generate the font's metrics file.
D:\tcpdf\fonts\utils> ttf2ufm -a -F adobemingstd-light.otf
The command will take a short while to finish. Once it is done, you should see three more files in the same directory with filename extensions .afm, .t1a and .ufm.
Next you need to run a PHP script makefont.php. (You need PHP installed on your Windows machine, or you can copy those three files created to your server and run the following command there.)
D:\tcpdf\fonts\utils> php -q makefont.php adobemingstd-light.otf adobemingstd-light.ufm false
This creates a compressed file with a .z extension and a PHP script named adobemingstd-light.php which will be used by TCPDF to generate PDF outputs. Before the PHP script can be used, there are some modifications must be done. Please open adobemingstd-light.php in your favorite text editor, and make following changes:
- change the font type to: $type='cidfont0';
- set the default font width by adding the line: $dw=1000;
- remove the $enc, $file and $ctg variables definitions
- add the following block of text at the end of the file :
// Chinese Traditional $enc='UniCNS-UTF16-H'; $cidinfo=array('Registry'=>'Adobe', 'Ordering'=>'CNS1','Supplement'=>0); include(dirname(__FILE__).'/uni2cid_ac15.php');
For modifications for other Asian languages, please refer to the document at official TCPDF site.
Copy Files into Joomla! Installation
With all the files ready, we can now copy them into proper locations on your server. Use FTP or SFTP to copy all the files and three directories cache, config and images inside your tcpdf folder to the directory libraries/tcpdf at your Joomla! installation. (You may want to rename the original libraries/tcpdf directory to another name, and then create a new libraries/tcpdf directory just to be safe.)
Next, copy the file adobemingstd-light.php you created into language/pdf_fonts at your Joomla! installation. Do the same for helvetica.php and uni2cid_ac15.php in your local tcpdf/fonts.
Edit Language Description XML File
The font used for PDF generation is specified in the language description XML file inside respective language folder. For Traditional Chinese, it's the language/zh-TW/zh-TW.xml. We need to add the following line between
adobemingstd-light
Modify Joomla! PDF Script
There seems to be a bug in Joomla! PDF script. It fails to correctly set the font for the article content. Please open the file libraries/joomla/document/pdf/pdf.php with your favorite editor on your server. Find the function render( $cache = false, $params = array()). Insert the following line right before the line $pdf->WriteHTML($this->getBuffer(), true);
$pdf->setFont($font, '', 10);
Optional Step
This step is optional if you can tolerate the ugly layout of article content in the resulting PDF file. The problem is that TCPDF uses white spaces to format the layout while Chinese characters are packed next to each other without spaces in between.
To fix this problem, you will have to modify the TCPDF core program. Use an editor to open the file libraries/tcpdf/tcpdf.php on your server. Find the public function Write($h, $txt, $link='', $fill=0, $align='', $ln=false, $stretch=0, $firstline=false) definition. Inside that function, look for the following line:
if (preg_match("/[\s]/u", $this->unichr($c))) {
and replace it with this line
if (preg_match("/[\s\p{Lo}]/u", $this->unichr($c))) {
Now try generating a Chinese PDF file from your Joomla! site's frontend, and see whether the layout has been improved. If not, your server doesn't have a PCRE library with the Unicode properties support compiled in. You can check it on the server using this command:
$ pcretest -C
You should see an output similar to the following
PCRE version 6.6 06-Feb-2006 Compiled with UTF-8 support Unicode properties support Newline character is LF Internal link size = 2 POSIX malloc threshold = 10 Default match limit = 10000000 Default recursion depth limit = 10000000 Match recursion uses stack
If it shows that Unicode properties support is not enabled, then the modification won't work. In that case you can download PCRE library source code and compile it with Unicode properties support enabled. Once the newly compiled PCRE library is installed, the layout in generated Chinese PDF should become more acceptable.
If You're Lazy.....
Well, if all these seems daunting, there is a short cut. I post an archive file including all the files, except the file mentioned at the optional step (because of the special PCRE library requirement), at Joomla! Taiwan. You can simply download it and put it on your server.