PDF Documents

Mathematica provides a powerful medium for electronic technical documents. Mathematica notebook documents can combine text, mathematics, computations, charts, visualizations, and interactive elements suitable for many technical areas. The documents can be kept as notebook format and viewed with the Mathematica notebook front end; alternatively they can be converted into a variety of other formats such as PDF, PostScript, or XHTML.

webMathematica can use these features to automatically generate technical reports.

One format that is very easy to generate is Mathematica notebooks, and there are a number of webMathematica examples that work by returning Mathematica notebooks to the client. One example is Content.jsp. Using Mathematica notebooks has the advantage that the document can be worked on further after reaching the client. A disadvantage is that it requires the client to have access to an application that can read notebooks, such as Mathematica or CDF Player (http://www.wolfram.com/cdf-player/). Another alternative is to use PDF. This has the advantage that the vast majority of clients are set up to render PDF.

Mathematica can now automatically convert notebook documents into PDF format. This section will explore how to generate PDF documents from webMathematica.

Generating a Mathematica Notebook

A common way to do this involves using Mathematica commands for generating notebooks. A sample function is shown below (taken from the source used by Content.jsp).

MakeNotebook[] :=
    Developer`UseFrontEnd[
        Module[ {nb, nbobj},
            nb = NotebookCreate[] ;
            NotebookWrite[ nb, Cell[ "A Dynamically Created Notebook", "Title"]] ;
            NotebookWrite[ nb, 
                Cell[ "Converted to " <> $$button, "Subtitle"]] ;
            NotebookWrite[ nb, Cell[ "The date is " <> ToString[ Date[]], "Text"]] ;
            nbobj = NotebookGet[ nb] ;
            NotebookClose[ nb] ;
            nbobj]]

This sample shows how a notebook object is created with NotebookCreate, and then how the content is added with NotebookWrite. When the notebook is complete, a Mathematica expression holding the notebook is obtained with NotebookGet and this is returned. In a real life situation, the document could contain graphics, more text, and some computations. The Mathematica documentation has much more information on the commands for generating notebooks.

A major advantage of working with Mathematica notebooks like this is that they will take care of details such as font selection, graphics, and mathematics without the author having to be very involved.

Converting to PDF

The Mathematica function ExportString can be used to convert a Notebook expression into a string that contains the PDF. When it runs in webMathematica it needs to be wrapped with UseFrontEnd. An example of the conversion is shown below.

UseFrontEnd[ ExportString[ nb, "PDF"]]

You can read more about PDF generation in the format documentation.

Returning PDF

There are several ways to return non-HTML content from webMathematica. These are summarized in the section Returning General Content. One simple way is to embed a URL that will download the document in your result. This can be done with MSPURLStore as shown in the following.

<msp:evaluate>
    nb = MakeNotebook[];
    pdf = UseFrontEnd[ ExportString[ nb, "PDF"]];
    MSPURLStore[ pdf, "application/pdf", "notebook.pdf"]
</msp:evaluate>

An alternative is to return the result directly from the request, which can be done as follows. Note that the content type must be set in the page directive.

<%@ page contentType="application/pdf"%>
<%@ taglib uri="http://www.wolfram.com/msp" prefix="msp" %>

<msp:evaluate>
    nb = MakeNotebook[];
    UseFrontEnd[ ExportString[ nb, "PDF"]
</msp:evaluate>

Yet another approach is to use MSPReturn. This is useful if your call is embedded inside some other programs, or if the result is not always PDF (perhaps because of error handling).

<msp:evaluate>
    If[ convert === "True",
        nb = MakeNotebook[];
        pdf = UseFrontEnd[ ExportString[ nb, "PDF"]];
        MSPReturn[ pdf, "application/pdf"]]
</msp:evaluate>

Creating PDF Example

This section describes an example that generates a notebook and converts it to PDF. For it to work you need to install PDF tools described in the last section. If you installed webMathematica as described above, you should be able to connect to this JSP via http://localhost:8080/webMathematica/Examples/PDF/Generate.jsp. (You may have some other URL for accessing your server.) The source is in webMathematica/Examples/PDF/Generate.jsp. Here is the JSP source.

<form action="Generate.jsp" method="post">
<input type="image" src="../../Resources/Images/Buttons/generate.gif"/>
<input type="hidden" name="button"/>
</form>

<msp:evaluate>
  Needs["ExampleUtilities`Content`"]
</msp:evaluate>

<msp:evaluate>
  If[MSPValueQ[$$button],
    nb = MakeNotebook["PDF"];
    pdf = UseFrontEnd[ExportString[nb, "PDF"]];
    MSPReturn[pdf, "application/pdf", "Generate.pdf"]]
  ]
</msp:evaluate>

This code loads a basic package for creating notebooks. This is done in a separate evaluate tag, as described in the section Mathematica Packages and Applications. It calls the function MakeNotebook, which generates a very simple notebook and converts this into a string of PDF. The string is returned to the client using MSPReturn.