With the release of Prince 5.0 comes new documentation.

Some new topics are covered, including an explanation of how Prince handles the CSS generic fonts, the new support for PDF bookmarks and metadata and exciting new features like footnotes and cross-references.

For server users there are tutorials on how to call Prince from Java, PHP, ASP, ColdFusion and ActiveX / COM / Visual Basic.

There is also a page on troubleshooting that attempts to explain various error messages; if you see any particularly cryptic messages when using Prince please submit them and they will be added to this page!

We have also documented which features from CSS 2.1 are not supported by Prince; the page is quite short and hopefully we can make it disappear altogether in the future

Mike,

Do you know of any PHP server examples that users could go to in order to see how the calls are actually implemented? We bought the server version of Prince, but I'm having a difficult time envisioning a process overview of how the server calls would actually work.

Would the user upload the XHTML and XML files to the server and then apply CSS files already installed on the server? Or could they upload both XHTML and CSS files as well?

I don't know PHP that well myself, as I have others on staff who will be coding this. I just want to know what's possible from the user perspective, and none of that is included with documentation.

Thanks.

Lee

Hi Lee,


Either of these approaches are possible, so it really depends on what it is that you're trying to do.

Prince is typically used in web applications to produce PDF files on demand, such as producing an invoice as the result of a purchase or other transaction. In this case the user enters their details in a web form in their browser, which makes a POST request to your server. This runs a PHP page (or Perl script, or whatever) that processes the user request, creates XML or XHTML, pipes it to Prince -- which is also running on the server -- and returns the resulting PDF file back to the user's browser.

In this situation, the user never sees the XML/XHTML/CSS directly, as it only exists on the server and is used to create the PDF that is sent back to the user. There is no reason in this situation for the user to be supplying their own XML documents or CSS style sheets.

If you can describe what kind of web application you are creating I can suggest some possible ways to implement it using Prince.

Best regards,

Michael

Mike,

We'd like to use Prince in basically two situations -- one where the user would click on a PDF icon on an XHTML page and have it return a PDF generated using a print-based CSS file. We use Plone for a lot of our page serving, so we'd probably be using the Python calls for this, but we'd like PHP support as well.

In the second scenario, we'd like to use Prince as an educational tool for showing students how they can use XML/XHTML and CSS to produce print PDFs with advanced layout features supported by many desktop publishing programs. In this case, we'd like students to have the ability to upload their own XML/XHTML and CSS files to the server via a password-protected page, with Prince generating the returned PDF. We'd be using the PHP calls for this.

Sample files or suggestions on how we might create these scenarios would be greatly appreciated. I'm teaching a course in the spring here at our university that will devote four weeks to how XML is used in single-source publishing, and as others have observed, I've found CSS much easier to use than XSL or FO.

Thanks for your help.

Lee

Hi Lee,


This is fairly typical usage of Prince as I described earlier; the XHTML and CSS are already available on the server, so the Python script just needs to pass them to Prince and then stream the resulting PDF file back to the browser. Make sure that the Python scripts sets the HTTP Content-Type header to "application/pdf" so that the browser knows that it is getting a PDF back. You can also set the Content-Disposition header to suggest a filename to the browser and whether the browser should view the PDF inline or prompt the user to save it; just google "Content-disposition pdf" for more information about this.


This situation is a bit more fiddly, as the PHP page will need to let the students upload multiple files and then pass them to Prince. Once that's done the PDF can be returned to the browser the same way as before. You could simplify this if you are only using XHTML, by requiring the CSS to be specified within the <style> element of the XHTML file rather than in a separate CSS file. Then only one file needs to be uploaded and the PHP page can be a bit simpler.

Please let me know if you have any questions about calling Prince from the command-line or from Python, or aspects of the PHP API.

Best regards,

Michael