Feature Wiki

Information about planned and released features

Tabs

Plugin Slot for PDF generation

Page Overview

[Hide]

Related feature request: PhantomJS

1 Initial Problem

ILIAS currently supports two engines for generation of PDF files: the php based TCPDF used for the Test object and the Java-based XSL-FO used for Certificates, Learning Modules and Surveys. Both have their pros and cons, however both lack a good support for CSS based styles. This makes, for example, the PDF files of test results looking different from the questions presented in the browser.

2 Conceptual Summary

There are a couple of PDF rendering engines that are faster and have a better support for CSS, for example wkhtml2pdf, PhantomJS or the commercial PrinceXML. The most of them need to run as external programs or services. As we do not know which of them will be the best in the future, I propose the following changes in ILIAS:

  1. All PDF generation in ILIAS should be wrapped by only one centeral PDF service. The existing PDFGeneration service used to wrap TCPDF can be taken as starting point and extended to handle the XSL-FO based generation, too. All calls for PDF generation should use this service.
  2. This service should get a plugin slot for additional PDF engine plugins that can produce PDFs directly or call external services.
  3. An administration interface should configure which PDF engine is used for which purpose (test results, certificates, learning modules, ...).
  4. The call of a rendering plugin should tell the purpose, so that this plugin is able to optimize the output for that purpose (e.g. by adding a specific stylesheet).

3 User Interface Modifications

3.1 List of Affected Views

There will be a new node in the Ilias Administration, where the PDF engine can be configured for the different purposes.

3.2 User Interface Details

Each PDF Engine brings their own Configuration Forms, since each PDF Engine needs different configuration options.

So the PDF Plugin slot only brings a general settings form, where only the mapping is done for the different Services. Simmilar to the "General Logging Settings".

PhantomJS Configuration Example
wkhtmltopdf Configuration Example

3.3 New User Interface Concepts

No.

4 Technical Information

{The maintainer has to provide necessary technical information, e.g. dependencies on other ILIAS components, necessary modifications in general services/architecture, potential security or performance issues.}

5 Contact

6 Funding

If you are interest in funding this feature, please add your name and institution to this list.

  • …

7 Discussion

Amstutz, Timon [amstutz] 4. April 2016: We are highly interested in this request. @Any possible maintainer: please contact us to elaborate this request further.

JourFixe, ILIAS [jourfixe], June 06, 2016: We highly appreciate this request and schedule it for 5.2. Maintenance for this plugin slot will be offered by Databay / Guido Vollbach.

JourFixe, ILIAS [jourfixe], Oct 24, 2016: In the meantime we are convinced that PhantomJS should become a core PDF renderer of ILIAS - and should not only be connected as a plugin. If PhantomJS becomes part of ILIAS, do we still need a plugin slot for PDF generation? And if yes: for which purposes and under which conditions? Does a maintainer has to guarantee that his components works fine with all possible renderers - or can we define per component if an additional renderer is used via plugin? Which other renderers would be used for improved PDF output?

Vollbach, Guido [gvollbach] Since we think the integration of PhantomJS to the core should not be dependent on the PDF Plugin slot we created another feature wiki entry for this (PhantomJs).

No to the other points:

  • Yes we still would need a plugin slot for other pdf engines. The problem we had in the past was, that since TCPDF and FOP were the only engines in Ilias an no one was really happy about this. If we would integrate phantomjs simple as another pdf engine, we could face the same problem in the future. With the integration of a simple plugin slot for other PDF engines, we could simple evaluate other engines which will appear in the future. Who knows maybe the Mozilla foundation will release an almighty PDF engine. With the plugins slot we could simple try this one out and if it would be better simple replace the core engines.
  • Does the maintainers at the moment guarantee that his components works fine with TCPDF? Or if it's complete and looks some way ok? Does the the pagecomponent maintainer has to guarantee that the pagecomponent plugins works in every way? 
  • I don't think it should be a problem to include a white-/blacklist for pdf engines.
To be honest each PDF engine which we have at the moment and PhantomJS and WKHTMLTOPDF have their different use cases. 
  • TCPDF is very useful if you want the full control over the PDF creation process, because you can get information on were you are on the page, or you have for example transactions and rolebacks to test if content fits on one page or not.
  • PhantomJS is useful if you have long Javascript call and you need a callback to know if your page is completly rendered.
  • WKHTMLTOPDF is great if you want to create full PDF forms, which PhantomJS can't, you can control how links get build, or if the print or screen CSS media query is used. You have here more control over the overall process.
So there does not exists the swiss army knife which could be used for all cases. There is no perfect PDF engine for everything and this is why I personally still think Ilias needs a plugin slot for this.

Neumann, Fred [fneumann], October 26, 2016

While I’m happy with PhantomJS in the core, I also believe in the purpose of a plugin slot. Some further arguments are:

  • Other renderers have advantages in the quality of the output. PrinceXML , for example is better in support of CSS3, handling orphaes and widows.
  • Plugins can have their own configuration page, which makes it possible to extend the output of TPDF or PhantomJS with advanced generation of headers including logo, page numbers etc.
  • Plugins are not bound to the version cycle of ILIAS. Workarounds and improvements can be provided on demand and not in a year. This is especially important for test archiving purposes. Improvements that are of general purpose can be added to the core in the next version.
It should not be the responsibility of core component maintainers to guarantee a good result with all renderers. It’s vice versa: the plugin providers should declare which components and rendering purposes they support. That’s the same principle as for the supported ILIAS version of a plugin.
That means:
  • Components declare their existing rendering purposes (e.g. “print view”, “user results”, etc. in the Test Module). For each rendering purpose they declare the supported built-in rendering engines and the preferred one. E.g. the “Test” module declares that TCPDF and PhantomJS are supported for “user results” and that PhantomJS preferred.
  • Rendering plugins declare for each component which purposes they support. The “Extended PhantomJS Plugin by FAU”, for example declares that it supports “print view” and “user results” in the test module.
These declarations are static information, depending only on the code. Additionally, core renderers and plugins can be activated or not.
The general administration page for PDF will then show all rendering purposes of components. For each purpose it will offer a selection of active renderers that support this purpose. The preferred renderer of a component will be the pre-selection.

Test

Print View of Questions

[PhantomJS                                ▼]

User Results

[Extended PhantomJS by FAU ▼]

Certificate

Preview and Download

[ILIAS Server (FO)                       ▼]

… and so on …

[Save]

Schneider, Stefan [sschneider], October 27, 2016

We highly appreciate the implementation of PhantomJS into the core. Althouh I totally agree with Freds statement to support an addtitional PDF-Plugin slot too. We can not look ahead how browser engines certain frameworks will support pdf rendering based on css for special purposes like exam archives or customized certificates and so on in the future.
So we should provide a lean and fast mechanism for using alternative renderes. In addition we surley need to optimize the core components to exsiting core renderer(s).
I don't see any serious drawbacks on getting best of both worlds. Most of the common PDF requirements will be coverable with builtin PhantomJS and TCPDF, so the maintainer should be able to pin and test their components against one or more of the builtin renderers and if not they have the chance to use a clean interface for a custom pdf renderer.

JourFixe, ILIAS [jourfixe], Nov 21, 2016: We appreciate this feature request and schedule the PDF plugin slot for 5.3. As already decided in October, PhantomJs shall become part of the ILIAS core as alternative PDF engine to TCPDF. All ILIAS components MUST work with either TCPDF or PhantomJs and must not rely on a plugin. We will monitor if the PDF plugin slot will lead to practice where modules or features are improved against a PDF plugin instead of improving the PDF generation in the core.

Alex Killing, 26 Aug 2017: The current alpha implementation in the trunk adds configuration options for every use case of a pdf rendering of all components. While I agree that the selection of the PDF engine per use case might be a rare requirement, the current solution forces the admin to configure same things a lot of times. Especially the ILIAS admins should not need to setup the paths for the binaries each time. This must be moved to the setup imo.

Vollbach, Guido [gvollbach], 28  Aug 2017: I already discussed this with Max a while ago, but since then there was no Jour fixe until now, and I think this is a decision must at least be documented and decided by the Jour fixe, but yes I agree a path setting in the setup would make sense. I the long run, we should probably get something like a template config which could be created and than applied.

Amstutz, Timon [amstutz], 1. September 2017: There are several things in the UI of this feature that need some improvement, one of which alex pointed already out. Further, If there are a lot of items to attach a renderer to, this form gets out of hand quickly (currently visible one ilias.de/test53 listing views repeatedly due to some strange bug). Why not putting that in a table? Freds Proposal puts Views of same Modules/Services in an own Section, but this is probably messy to do in a form. I would really go for a table here with an an inline editing option for selecting the renderer, a multy action to attach a renderer for multiple views at once and an action to configure a renderer. Further note, that the Icon does not fit in with the other Icons (Colors, Shoadow, non-Flat etc.). Yvonne could certainly assist, to improve that.

Vollbach, Guido [gvollbach], 05 Aug 2017: I think on the test installation there was a Bug which created multiple of purposes, this should be fixed by now, but there has to be done some cleanup on the installation. 
The problem which Alex adresses can be solved with the following pull request.

The Icon is only temporary, since there was need for a Icon, but this is not intended to stay there.

8 Implementation

Documentation:

Test Cases

Test cases completed at 18 August 2017 by mbecker

  • C18643 : Administration aufrufen
  • C18644 : Selected Renderer festlegen bzw. ändern 
  • C18645 : Selected Renderer konfigurieren 
  • C18658 : Selected Renderer konfigurieren abbrechen
  • C18646 : Selected Renderer festlegen und konfigurieren 
  • C18647 : Korrekt installiertes Plugin wird als Renderer angezeigt 
  • C18648 : Korrekt installiertes Plugin wird als Selected Renderer konfiguriert 

Approval

Approved at 2017-08-23 by Samoila, Oliver [oliver.samoila] (Technische Hochschule OWL) as agreed with DHBW Karlsruhe.

Last edited: 2. Apr 2019, 20:30, Samoila, Oliver [oliver.samoila]