PDFs are used for just about everything in business these days - contracts, invoicing, eSignatures, record keeping, you name it. So, for many companies looking for Retool apps, PDF end products are essential. The possible applications of having a simple and easy to implement method for producing PDFs from Retool data cannot be underestimated.
There are currently two ways using Retool’s native features that allow you to generate PDFs. We will first take a look at the PDF Exporter option, and the downloadPage utility method, as well as their uses and limitations, before going through another (much more customizable) method that utilizes an external API to generate PDFs within our Retool environment.
Finally, we’ll run through some handy tips for how to complete your perfect PDF Generator App.
*Disclaimer: as Retool is a highly hackable program and also often updated, there may be other methods currently available. The following are the methods I found most suitable at the time this tutorial was made. (5/13/2021)
The PDF Exporter query requires Markdown for document formatting and is a good option for relatively simple PDFs. Markdown is a lightweight markup language for creating formatted text using a plain-text editor.
First, create a new query and select “PDF Exporter” from the resource dropdown. In the PDF Exporter’s value box, you can pull data from your app into the Markdown layout using curly bracket references. Running the query will open a window, allowing you to save your PDF to your PC.
To illustrate how this can work, the following is an example of a simple contract generator app and the PDF that was exported using this query.
If you, like me, are more familiar with HTML than Markdown, a simple workaround here is to write your PDF template for the PDF exporter in HTML and then use an HTML to Markdown converter online. Once converted, you n paste the results into the value box of the PDF exporter. There are several converters online, and the one I used to create the above example is here.
The main limitations of the PDF Exporter:
Summary: So for those looking for a simple method to produce a very basic PDF, with no need for specific formatting in terms of exact font size, text alignment etc., this is a good option. If being able to change the file name directly in your application before saving is essential, read on for another option that does allow you to do so.
To use this function you need to run a JavaScript query using:
utils.downloadPage("your_filename", { selectorsToExclude:[‘selector1’], componentsToExclude:['component1', 'component2'], scale: 1, fullscreen: true})
Note: Everything within the curly brackets is optional and anything in italics is dynamic (where you put in your own values: filename, retool data you want to exclude, etc).
To read more about this utility, follow this link to the Retool documentation.
What it essentially does is download the current Retool page as a PDF (basically a screenshot). Based on my experience, this only seems to work if everything you want in the PDF is all in one container component. This method is suitable if you want part or all of the current Retool page as a PDF but not if you want it formatted differently. It just displays exactly what is in the container, minus any selector or components you chose to exclude in the query above. While it may be possible to format this utility to work outside of a container, the syntax can be extremely tricky and takes a while to figure out.
Below you can see the same contract generating app as used in the previous example. I added a rich text editor inside a container component as my vehicle for formatting the contract. You can see on the right hand side that I have used HTML in the Default value box to build the contract and add my Retool references. The text editor is the only component inside the container since it is the only feature I want in the PDF.
You can see the new query and the results when it’s run, here.
As you can see from the clip, the PDF is just a replica of the container and, again, doesn’t look particularly professional. A benefit of this method is that you can generate unique file names, unlike the PDF exporter query, but, much like the first option, formatting is definitely a limitation here.
Summary: If you are looking for a simple PDF generator and are not particularly bothered about formatting or layout, but you do need to change your file name when saving this will be a better option for you than the first. Our final option, the external API, gives you much more customizability options, so if that’s what you need - keep reading!
While the above two methods do produce a PDF, they are limited in scope and customizability. A way to work around these drawbacks is to use an external API for PDF generation.
I have experimented with several different APIs that offer PDF generation, but, in the end, the one I found easiest to use was APItemplate.io.
Using this template system allows for elaborate formatting, easy customization and straight-forward referencing to all your Retool data. Once set up, creating professional-looking PDFs is quick and easy.
The first step in this process is to go to their site, sign up (it’s free) and start making a template. After signing in, you are directed to your dashboard, which shows your subscription information, remaining API calls and most recent transactions.
Under your Dashboard on the left hand menu is ‘Manage Templates’. Click there and then you’ll see a button ‘+ New Template’. (see GIF below for animated instructions)
Now, there are various templates to choose as a starting point, depending on what you’d like to do and how you’d like to do it. For this example, I’ll be using the Visual Editor – PDF template editor (middle option) and the Business Contract Sample, which uses a WYSIWYG editor (“what you see is what you get”). This editor requires little to no coding, so is very easy to use.
After naming your new template and clicking on ‘Create’, you will be taken back to your Manage Templates page. Find your new template and click ‘Launch WYSIWYG Editor’ (far right). You will now see the WYSIWYG editor on the left and the template preview on the right.
You will notice here that in the editor they have used curly brackets to reference different items, such as company name, contractor, address, etc. This is what you want to do anywhere in your PDF template where you reference Retool data (more on how that works later). So, for example, if you have a textinput.value called ‘client_name’ in Retool that you want in your PDF, you could add {{client_name}} where you’d like that value to appear in the template.
It doesn’t matter what is inside the curly brackets in the template, as long as you keep track of what they reference in Retool as they will be used later when we connect the API to Retool. If you click on the ‘</> Sample Json’ tab in the template editor you can see the values that have entered in the sample template and can also use that area to enter your own values to check how it looks as you go along. Anytime you want to see how it’s looking, just click on Quick Preview.
Check out the example contract below. I copied my contract from the rich text editor that was made in the previous example and pasted it into the WYSIWYG. I then added my Retool references in curly brackets and connected them with dummy values in the ‘</> Sample Json’ tab to see how the contract looked. It’s also possible to change some things under the ‘Settings’ tab, such as page settings, margins and header and footer content, but I left them as the default values for this tutorial.
Once the template is finished and saved, you will need two pieces of information from APITemplate to connect your new template with your Retool app:
1. Your template ID. This can be found under ‘Manage Templates’ in your profile
2. Your API key. This can be found under ‘API Integration’ in your profile
For the next step we go back to Retool (finally!) and add a new RESTQuery (restapi), which is a Resource type query. The action type is POST and the URL to enter is https://api.apitemplate.io/v1/create.
Now we need the template ID and the API key. In URL parameters, the key is template_id and the value is (you guessed it!) your template ID. Once you enter that you will see that it has been added to the end of the url above.
In the Headers box, the key is X-API-KEY and your API key is the value.
The Body section is where we will enter our Retool values that will appear in the PDF (Remember the curly bracket references you added to your template? This is where they will go!) Pick JSON in the dropdown next to Body. Then enter all your keys and values. The keys are all the references inside curly brackets in your template and the values are the matching references from Retool. This tutorial only used textinput values, but anything that outputs a value should work here.
Here’s how your Body fields should look:
After saving, hit Preview or Run and, if successful, the query will return a response from the API that looks like this:
The API has responded to the query by giving you a url (download_url) to your PDF. You can copy and paste it into your browser and then do what you like with it. Here’s the result of my Sample Contract. The PDF has a header since those settings on the template editor were left as default (you could remove it completely or change the values if so desired), but as you can see, all the Retool references have been added.
Keep reading for tips on how to make this PDF app easier to use - such as adding buttons to download, open in new tab, and insert a PDF viewer component!
Now that the query is running smoothly, there are a couple of things that can be done to ease usability.
Instead of manually running the query each time, let’s insert a button, call it ‘Generate PDF’ and set it up so that On click it runs our query (which I have renamed api_template). This step could also easily be applied to all three of the methods in this tutorial.
Another useful thing to add here is a PDF Viewer so that you can see the results immediately. The File URL is {{api_template.data.download_url}}. Your PDF will show up as soon as you click the Generate PDF button.
If you get a “failed to load PDF” message in your PDF viewer (it happens!), you can do the following to get your PDF using Base64-encoded binary instead:
Now, when using the external API, copying and pasting a URL into a browser every time you generate a PDF can get a little busy, so let’s add another button that will run the query automatically.
Instead of, or in addition to, the ‘Open PDF in a new tab’ button, you can also create a button to download the PDF to your computer.
So mine looked like:
utils.downloadFile(api_template.data.download_url, [textinput1.value] , "pdf")
(Here you’ll need to add the name of your RESTQuery, and, in the box brackets, the unique file name (I connected mine to a text input component so that each file could be customised). The “pdf” defines the file type you wish to download)
So now we have a tidy little app that generates an easily formattable PDF that can be viewed, opened or downloaded right from our Retool environment – mission accomplished!
Joey has been an absolute pleasure to work with! He’s provided a lasting impact on our organization by building out our Retool portal in a way that allows us to optimize how we track, communicate and launch our clients. His attention to detail and rapid ability to implement all of our product requests was unmatched. I highly recommend the Bold Tech team for all things related to Retool!!
Joey and the Bold Tech team have been an invaluable help for us this past year. Quick, efficient, straightforward and a real pleasure to work with, I can not recommend them highly enough!
We build internal tools, fast.
