[Html2PdfConverter] Html2PdfConverter FAQ

[Html2PdfConverter] Html2PdfConverter FAQ

Forge Component
Published on 2016-03-24 by Guilherme Pereira
40 votes
Published on 2016-03-24 by Guilherme Pereira

Hi Guys,

While helping to maintain this component I’ve got several questions regarding it’s configuration and usage.

The Html2PdfConverter component is a wrapper around the wkhtmltopdf command line tool that generates pdf documents or images based on web pages.

The tool itself comes in two versions: one that is MinGW based (bundles all dlls) on that is MSVC based (and requires installation of MSVC 2013 on the server).

This post is written as a FAQ with the most common questions collected over time and separated by category


Q) Does this component work on the free Personal Environment?

A) Yes. It works on both personal and enterprise cloud and also on on premises installations.

Q) What version of wkhtmltopdf should I install?

A) I recommend using the MinGW one. Actually if you’re using a cloud environment (Personal or Enterprise) you have no other choice as you cannot install the dependencies on the machine required by the other version. The MSVC based one it’s supposed to be faster but in practice I never saw the difference.

Note: The lastest stable version of HTML2PDF do not include the MinGW version so for those trying to configure you can use the latest "Bleeding Edge" version.

Q) What binaries should I upload?

A) The binaries for windows include two executables and a few dlls. You should upload each exe (wkhtmlpdf.exe and wkhtmlimage.exe) to the correct places as well as the accompanying dlls. t’s not described anywhere but for the windows version the wkhtmltox.dll is not necessary. I found this by trial and error and it’s a good way to save 50MB on your HD and DB.

The linux versions do not have dlls only the binaries (wkhtmlpdf and wkhtmlimage)

Q) I’m having troubles uploading the binaries. What can I do?

A) This issue is usually related with network configuration. I suggest using google chrome as it has a nice progress indicator and sometimes you can see it reach 100% and get back to 0%.  

In those cases the best recommendation I can give is to use a different network or a wired connection (it has worked on most of the cases).

Some community members have worked around by extending the max request length and timeout by using Factory configuration to change the web.config. I never had the need to try this approach but you can find more details here

Q) I cannot export. I’m getting a blank page. What can I do?

A) There can be several reasons for this:

  • First and foremost if you’re using an on premises installation log onto the machine and navigate to the HtmltoPdfConverter folder and execute the component from the command line. The output is usually a good indicator of potential problems.

  • If you cannot log into the machine activate the LogDebugMessages option on the Administration page of the component and check service center logs.

  • Make sure the page you’re trying to print is accessible from the server.

  • On some occasions the machine cannot reach when using the machine domain or localhost due to bad dns resolving/configuration. Try to use the IP or instead or log into to the machine and try to access the URL from the browser.

  • There’s a known incompatibility between the component and a SilkUi based widget to detect the mobile devices because it is blocking the execution of javascript on the component. In such scenarios create an empty theme not SilkUi based and use it as the theme for the webflow of the page you’re trying to export.

Q) My content is broken when exporting to pdf. Why?

A) If you’re using a responsive theme (London, SILK or other) then you need to understand that the default page size is much closer to a tablet resolution than a desktop so the elements will break accordingly. Try to fix your page to have a good L&F on a tablet resolution and it should work when exporting A4 out of the box.

Q) I cannot export I’m getting the invalid permissions screen. What can I do?

A) The screen to import needs to be accessible anonymously. This is because the component runs on a different session without the possibility to trigger the login.

Q) Sometimes the export works sometimes doesn’t. What’s wrong?

A) Please validate if you have more than one front end in your service center and if so activate the farm mode on the administration page. Also validate the potential network issues on the several frontends.


Q) If the screens to export have to be anonymous how can I secure them?

A) The best way is by generating a token and passing it to the page to generate and on the preparation of that page validate the token.

Q) How can I keep my content from splitting from one page to the other?

A) Use CSS page-breaks to control the behavior:

Q) How can I control the header on my pages?

A) By using css.

  • If you want to prevent your table header to be repeated on other pages, you should apply the following CSS styles on the page that you are printing:

  • If you want to maintain your table header repeated on all pages but still ensure that the content don't overlap you can try the below solution:

Q) Does the component allows me to do X?

A) Check the component command line parameters and try to use them accordingly.


Q) Is this component the official way of exporting PDF with the OutSystems Platform. Can I email OutSystems support with questions about it?

A) The Html2Pdf is a community driven initiative and not supported by OutSystems. The team is composed by OutSystems and Non OutSystems personnel that work in a best effort mode to keep it running and assist the community with the questions  

Q) What alternatives do I have to this component.

A) There are several alternatives on the forge. Just search for pdf