Native PDF Generation vs PDF Generator Module within Mendix
In the early days of Mendix, generating a PDF meant writing Java code. You could already use Apache FOP, but developing the PDF meant you needed high-code expertise. Since Mendix introduced the document generator, life has been a lot easier. With the release of the document generator last year, together with the Mendix 10 edition, generating a PDF became almost as easy as building a page.
In this iteration of my newsletter, I will deep-dive into the comparison between the old method and the new PDF generator module. For this, I set up a fairly simple domain model that allows for an invoice to be the basis of the document that will be generated. I gave myself 30 minutes for each variation to implement a template to create the PDF and will list my experience with both. TLDR: I like the new PDF generator a lot, but there are some issues to remember when using it.
The setup used for the generation of a PDF within Mendix
To generate a document with any valuable dynamic content, you, of course, need a domain model:
Besides that, you will see the GenerateTestData microflow used, which generates some “dynamic” data.
With the foundation in place, it is time to start building the actual generation logic for the PDF.
Old ways of generating a PDF within Mendix
Translating a relatively easy-to-use designer design into Apache FOP (the core technology of the native PDF generator) can be difficult. (Believe me, I tried the same thing with a high-code platform.) The What You See Is What You Get WYSIWYG editor style just doesn’t go as pixel-perfect as the page editor can. While Apache FOP supports styling that reads similarly to CSS, it has shortcomings. On top of that, the document generator designer hasn’t had much love for a long time. Using data in it still feels like you are building a Mendix page in Mendix 3, released well over a decade ago. Combine this with the fact that testing your design meant restarting your application repeatedly and needing to recompile everything (no quick start here). This makes implementing or updating a PDF design using the native PDF generator cumbersome. No wonder there are 5+ alternative modules created by the community over the last 14 years!
Generating a PDF using the old methods
First, you create a microflow that:
- Supplies some data;
- Prepares a file document object;
- Calls the Generate document microflow activity;
- Then, the document can be stored or offered via the Download file microflow activity.
After you set up the microflow, it is time to design your PDF template. For this, you need a document of the type Document template, and then the pain starts. This is especially true if this is your first rodeo with the document template designer and you started with a recent version of Mendix. The document template designer feels and acts like an artefact from the past.
The result
After 30 minutes of struggle with the old designer, I got a fairly nice result. Fortunately for me, it had been a while since I had used it, and similar to riding a bike, you never forget how it works. But it is still a painful process, unlike riding your bike. Keep in mind that the example used for this showcase is relatively simple. There is no complex conditional visibility or difficult graphics to render. And the result is not bad. However, a ton of clicking was involved, especially when setting the styling (even with the copy/paste style functionality). While my showcase app is small, I had to restart it about 50 times to get it to where it ended up, which meant it felt like waiting for paint to dry.
Verdict
The old method takes a straightforward approach. Sending data to it means using microflows as data sources or preparing it well beforehand. Without the ability to use non-persistent entities, you create all that data in the database or at least as a persistent entity that you then pass directly to the document template generator.
Pros
- Native to the platform, so there is no need for additional configuration
- Build over a decade ago, so all issues are relatively well-known in the community
Cons
- Severely outdated designer, not up to par with, for example, the page editor
- You must restart the application fully each time you want to test a change.
- Really limited means of getting your dynamic data into your document template
- It is known to crash your cloud environment if you make your designs too complex or add non-Latin character support.
- No dark mode support!
- It is difficult to get pixel-perfect for complex designs with graphics.
The future of PDF generation
The new PDF document generation comes as a module, meaning it is no longer native. However, it works out of the box in the cloud, where you need a separate component to generate your PDFs (it is not done on the same cloud node as your application is running). On your local development machine, you must have Chrome or Chromium installed. The special sauce of the new method is that it uses an HTML renderer to PDF to actually “print” your page as a PDF document. This allows you to get closer to a pixel-perfect design using a familiar designer, the page editor.
Generating a PDF using the new module within Mendix
First, you create a microflow that:
- Calls the Generate PDF from page activity;
- For this activity, you supply a page microflow that will present the page to generate the PDF;
- You may supply a context object;
- You define the output object;
- Supply a filename;
- Set the user to use for the context of the microflow to render the page execution;
- Then, tell the generator if you want to wait for the result or continue and get the result asynchronous.
- After that, the document can be stored or offered via the Download file microflow activity.
Which seems more complex but is relatively simple.
Of course, you also create a microflow to supply for the page open part.
- This microflow may or may not supply some test data (mine does). It could also take the context object and pass that to the page.
- And it needs to open up a page.
After you have set up the microflows, it is time to design your PDF / page. For this, you simply add a page, and for ease of use, you may use the supplied layout DocumentGeneration_Default. And because this is the regular page designer, you could use the structure or design modes. You could even combine it with XRay in design mode. Designing the page was a breath of fresh air.
The module even supplies useful design properties to render your page correctly in the generator:
The result
After another 30 minutes in which I did not have to wait for my app to restart, I got a slightly lesser result. However, every time I wanted to test the altered design I could do so almost instantly. The lesser result in part has to do with my choice to use the data grid 2 widget. But without custom CSS I did not get rid of a weird “selection” of the first cell issue. Besides that, I probably should have used tables instead of layout grids to align my content similarly as I did on the old PDF designer, but I wanted to create the design as much as I would have created it for an actual page.
The pro's and cons on the new method of generating a PDF within Mendix
The new PDF generator is easy to use, and while it isn’t a native component, it works extremely well out of the box. Using data on your page is something we do daily and just works well. You may even use non-persistent objects on your page if they have been supplied by the page opening microflow or within an appropriate timeframe while rendering the page via data source microflows. The PDF rendering engine does not wait forever to load your page. I could have spent more time refining the design and probably should have created some custom CSS to make it splash, but the result for 30 minutes of work is good enough.
Pros
- It is a lot simpler to design the template for the PDF
- A modern method to design the template using the native page editor
- Dark mode all the way!
- Automatically gets updates to the designer as more widgets/functions are added for the page editor.
- Doesn’t break your cloud environment anymore
- Pixel-perfect designs are now fully supported by your CSS skills
- Out of the box non-Latin character support
Cons
- It is not native to the platform, meaning you need to do a bit extra setup
- The WYSIWYG experience from the page to the browser is not precisely 1-on-1 translated to the PDF output
- Not all widgets play nice with the PDF rendering (even Mendix platform-supported widgets)
In with the new, out with the old
I like the new method. As I got a glimpse of it during the private BETA testing, I knew this would be a game changer. Using the final version makes the implementation of PDF generation significantly easier and brings it back to modern times.
