A thin Spring Boot server "wrapper" around Open HTML to PDF. Allows you to create PDF documents via REST (POST) requests. It also employs a templating engine to enable the creation of dynamic PDFs (template parameters are passed as JSON in the POST request). Currenty only Handlebars (via Handlebars.java) is supported, but it is easily possible to add further templating engines (see Extensibility). The server itself barely contains any code but mostly combines the following projects:
- Only Java is required to run the server
- Download the Zip file from the latest release, extract it and place the Jar file in any directory
- Create a subdirectory named "templates" (this can be customized, see Configuration)
- Place a Handlebars template file (.hbs file ending) in that directory
- Start the server via "java -jar openhtmltopdf-server-X.X.X.jar"
- Send a POST request (e.g. via Postman*) to
http://localhost:8080/pdf/<name of a file in the templates folder>
You should receive a PDF with the contents of the file. When you request a Handlebars file you have to supply the template parameters as JSON in the POST request. You can also create any subfolders inside the "templates" directory which you then, of course, have to supply in the request. Suppose you have created a subfolder named "handlebars" in the "documents" folder. Inside that folder you have a file name "test.bhs". The request would have to go to http://localhost:8080/pdf/handlebars/test.hbs. Which folder structure you use is completely up to you.
*If you don't have Postman, see Template development
As a standard Spring Boot server is used, you can create a file named "application.properties" in the same folder as the Jar file. There you can, for example, change the port by adding the property server.port=<other port>. The server itself only offers three custom properties to configure:
| config name | default | description |
|---|---|---|
| root.dir | templates | Set the name of the root directory in which the template files are expected. |
| pdf.producer | openhtmltopdf.com | Configure which producer name should be set in the properties of the generated PDF documents. |
| handlebars.template.hot-reload | false | Causes changes to Handlebars templates to be directly picked up by the server. This has a slight performance penalty but is very useful when developing a template. |
Developing templates can be a tedious process because you always have to check how a change in the HTML looks in the actual PDF. For this reason this project contains the file 'template-dev.html' which is automatically served if you start the server in dev mode (pass -Dspring.profiles.active=dev as additional command line parameter). You can then open the file in your browser if you go to http://localhost:8080/template-dev.html (by default).
You should see a webpage with a textfield at the top where you can enter the URL to your template (by default http://localhost:8080/pdf/<template name>). Below the URL field you find a text area where you can put the template parameters (e.g. JSON for Handlebars templates). When you click the 'Generate' button, a preview of the PDF loads in the bottom part of the page. You can also trigger that button with the shortcut Alt + r or Alt + Shift + r depending on your browser. The shortcut does not work when the PDF preview is focussed. If you want to take a look at the HTML that is generated by the templating engine, you can replace the "pdf" in the URL with "html" (e.g. http://localhost:8080/html/<template name>). You will then get a preview of the rendered HTML.
In the sources you will find the subpackage "template". In there is a strategy to render HTML from a template ("HandlebarsHtmlContentStrategy"). It implements the interface "HtmlContentStrategy". To add another templating engine, add a new class implementing that interface. There is only one method to implement, which takes the path to the template file and the template parameters (a simple string which you have to parse yourself if necessary) as arguments. It returns a string which should be the rendered template (i.e. HTML). The only other thing you must do, so that the templating engine is picked up, is to add a method to your class that is annotated with "@PostConstruct" and registers the engine for a file extension. You have to inject the "HtmlContentStrategyFactory" for that and call the "registerStrategy" method. Make sure you don't overwrite existing file extensions (currently .hbs) because one file extension can only have one templating engine associated.