Neptune PDF
PDF document generation
In June we started work on a second pilot project. A contact reached out to me about generating a kind of shipping document called a Bill of Lading.
At this point, the Neptune Engine was able to render templates with a set of simple data fields. But in order to support templates like invoices (and now, bills of lading) we needed to support lists of line items.
This was the first "complex" data type that we added for our live edito form: the list. Each item in a list type behaves like a line item: it can have sub-fields like name, price, and quantity.
To make things easier for toggling certain boolean settings, we also introduced a "checkbox" input type
With the increasing complexity of the editor, this is where React really helped us out. We were able to keep the code manageable by splitting everything into small components.
Meanwhile, anticipating the needs for different kinds of data forms for different kinds of documents in the future, we settled on a JSON definition format to describe our forms. This way, each new template form would require a new JSON definition, instead of an entire new React form. This dynamic form generation approach immediately started paying dividends and saved us many hours of work down the road, and kept things very approachable for newly onboarded developers.
My first pilot project was with a tree-planting charity called One Tree Planted.
Matt from One Tree Planted was already sending certificates to his donors, to thank them for their contributions for planting trees.
Since these certificates fit the format of transactional documents, being issues for every donation transaction, it was the perfect pilot project to validate the Neptune Engine and to get better insight into the needs of the market.
What we learned from generating certificates:
- Page size and format matters. In this case we needed a landscape 8.5x11 page.
- Images and backgrounds are important. Most of the graphics of the certificate template were static, so we implemented them with one large background image.
- Document delivery is a big part of the equation. Once the PDF is created, where should it end up? Sent via email? Uploaded to a server? Different clients would have different needs.
How do you preview a PDF inside the browser?
My project would have been stuck at this point, if not for the existance of a remarkable piece of software from Mozilla called PDF.js.
PDF.js is a renderer that allows to display a PDF right in the browser. It turns out that there are no shortcuts to do this: you have to do hard work of parsing the PDF format and rendering every text, image and path one by one onto a HTML canvas. That's exactly that PDF.js does.
It's a remarkable piece of software because the PDF format is complex and it's a lot of work to parse. Luckily for the developers, today the PDF standard is well-documented, but it still contains a lot of quirks that have accumulated over many years and many revisions.
I integrated PDF.js as a React component, using a library called react-pdf. Now, alongside the live editor form which allows to edit the document data, I can instantly show a preview of the resulting PDF right next to the form in the browser.
On this day I wrote the first lines of code of the Neptune Engine, part of my vision for a new PDF generation engine.
I had worked on several client projects that required automatically creating transactional PDFs like invoices and shipping documents. I was able to use existing PDF tools to implement these projects, but I saw an opportunity to create a better tools that I could re-use for future similar projects.
The main goal at the time was to make a set of PDF generation tools that would make the development process more ergonomic for myself and my own team of developers. But I could see a potential larger opportunity to make it a product that others could use as well.
The Neptune Engine was built from the start with a Chrome-based renderer, allowing me to use widespread technologies (HTML, CSS) to generate PDF layouts. The Chrome instance runs under the hood and prints the HTML page to a PDF file. That was the easy part (in large part thanks to a node.js library called Puppeteer). The hard part was building a live editor for the data fields that would get fed into the templates, and a PDF preview that would show the result right inside the editor.
Comment