Development Guide

PDF Renderer Plugin

This plugin Slot is available starting from ILIAS 5.3.x

The new process to generate PDF documents with ILIAS supports two renderers in the core. In order to allow for more solutions to be used in different and/or specialized scenarios, this plugin slot is provided, so emerging pdf render engines can be put to work with ILIAS quickly.

All pdf renderer plugins have to be installed into directories at:

Customizing/global/plugins/Services/PDFGeneration/Renderer/<Plugin_Name>

Plugin Directory Structure

A renderer plugin has the following minimal file/directory structure and the name conventions you can see here:

<PluginName> (Directory)
	classes (Directory)
		class.il<PluginName>RendererPlugin.php
	lang (Directory)
		ilias_<LangKey>.lang
	sql (Directory)
		dbupdate.php
	plugin.php

Plugin Files

We will now have a detailed look on all mandatory files and an example implementation. The name of the plugin is "ShinyPDFRenderer", so its location will be at:

Customizing/global/plugins/Services/PDFGeneration/Renderer/ShinyPDFRenderer

plugin.php

All plugins must include a plugin.php file.

<?php
/* Copyright (c) 1998-2016 ILIAS open source, Extended GPL, see docs/LICENSE */
 
$id                = 'shpdfr';
$version           = '0.0.1';
$ilias_min_version = '5.3.0';
$ilias_max_version = '5.3.999';
$responsible       = 'Your Name';
$responsible_mail  = 'your_spambox@the_mailman_cometh.com';

Take this, make it yours.

classes/class.il<PluginName>Plugin.php

The implementation of the plugin class is quite easy. It must be derived from ilPDFRendererPlugin. All requirements are coming from here, the following scaffold takes the description inline, so you can use it for your development as is.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
<?php
/* Copyright (c) 1998-2017 ILIAS open source, Extended GPL, see docs/LICENSE */
 
require_once './Services/PDFGeneration/classes/class.ilPDFRendererPlugin.php';
 
/**
 * Class ilShinyPDFRenderer
 *
 * @author Your Name <your_spambox@the_mailman_cometh.com>
 * @version $Id$
 */
class ilShinyPDFRenderer extends ilPDFRendererPlugin
{
	/**
	 * Returns the plugins name for display.
	 *
	 * @return string Name of the plugin
	 */
	public function getPluginName() {
	 // TODO: Implement getPluginName() method.
	}
 
	/**
	 * Central call to create and deliver the PDF files generated.
	 *
	 * Please see the \ilPDFGenerationJob for details on the information provided by it.
	 *
	 * @param string              $service Name of the service/component the generation is triggered for
	 * @param string              $purpose Purpose title the generation is triggered for
	 * @param array               $config  A config this renderer has use for
	 * @param \ilPDFGenerationJob $job     A PDF generation job, holding the HTML itself among other data
	 *
	 * @return void
	 */
	public function generatePDF($service, $purpose, $config, $job) {
	 // TODO: Implement generatePDF() method.
	}
 
	/**
	 * Adds configuration form inputs to the given form
	 *
	 * @param \ilPropertyFormGUI $form    A reference to the form the renderer should add it's form elements to
	 * @param string             $service Service title for the config form, if the plugin fancies to vary on that.
	 * @param string             $purpose Purpose title for the config form, if the plugin fancies to vary on that.
	 *
	 * @return void
	 */
	public function addConfigElementsToForm(\ilPropertyFormGUI $form, $service, $purpose) {
	 // TODO: Implement addConfigElementsToForm() method.
	}
 
	/**
	 * Fills in values of the given config into the given form
	 *
	 * Please note the form MUST have the specific input items from addConfigElementsToForm.
	 *
	 * @param \ilPropertyFormGUI $form    A reference to the form the renderer should add it's form elements to
	 * @param string             $service Service title for the config form, if the plugin fancies to vary on that.
	 * @param string             $purpose Purpose title for the config form, if the plugin fancies to vary on that.
	 * @param array              $config  A config this renderer has use for
	 *
	 * @return void
	 */
	public function populateConfigElementsInForm(\ilPropertyFormGUI $form, $service, $purpose, $config) {
	 // TODO: Implement populateConfigElementsInForm() method.
	}
 
	/**
	 * Validates the given form
	 *
	 * @param \ilPropertyFormGUI $form    A reference to the form the renderer should add it's form elements to
	 * @param string             $service Service title for the config form, if the plugin fancies to vary on that.
	 * @param string             $purpose Purpose title for the config form, if the plugin fancies to vary on that.
	 *
	 * @return bool
	 */
	public function validateConfigInForm(\ilPropertyFormGUI $form, $service, $purpose) {
	 // TODO: Implement validateConfigInForm() method.
	}
 
	/**
	 * Extracts the specific config values from the given form and returns them as an array
	 *
	 * @param \ilPropertyFormGUI $form    A reference to the form the renderer should add it's form elements to
	 * @param string             $service Service title for the config form, if the plugin fancies to vary on that.
	 * @param string             $purpose Purpose title for the config form, if the plugin fancies to vary on that.
	 *
	 * @return array
	 */
	public function getConfigFromForm(\ilPropertyFormGUI $form, $service, $purpose) {
	 // TODO: Implement getConfigFromForm() method.
	}
 
	/**
	 * Returns a default config as an array
	 *
	 * @param string $service Service title for the config form, if the plugin fancies to vary on that.
	 * @param string $purpose Purpose title for the config form, if the plugin fancies to vary on that.
	 *
	 * @return array
	 */
	public function getDefaultConfig($service, $purpose) {
	 // TODO: Implement getDefaultConfig() method.
	}
}

sql/dbupdate.php

Again, the truth is in the code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
<#1>
<?php
/*
 * Use to register a renderer:
 * ===========================
 *
 * require_once './Services/PDFGeneration/classes/class.ilPDFCompInstaller.php';
 *
 * $renderer = 'DummyRenderer';
 * $path =  'Customizing/global/plugins/Services/PDFGeneration/Renderer/DummyRenderer/classes/class.ilDummyRendererPlugin.php';
 * ilPDFCompInstaller::registerRenderer($renderer, $path);
 *
 * $purpose = 'UserResults'; // According to name given. Call multiple times.
 * ilPDFCompInstaller::registerRendererAvailability($renderer, $service, $purpose);
 */
/*
 * Use to register a service/purpose:
 * ==================================
 *
 * require_once './Services/PDFGeneration/classes/class.ilPDFCompInstaller.php';
 *
 * ilPDFCompInstaller::registerPurpose($service,$purpose,$preferred);
 * or uninstall one:
 * ilPDFCompInstaller::unregisterPurpose($service, $purpose);
 * or uninstall all:
 * ilPDFCompInstaller::flushPurposes($service);
 *
 */
?>
<#2>
<?php
require_once './Services/PDFGeneration/classes/class.ilPDFCompInstaller.php';
 
 $renderer = 'ShinyPDFRenderer';
 $path =  'Customizing/global/plugins/Services/PDFGeneration/Renderer/ShinyPDFRenderer/classes/class.ilShinyPDFRendererPlugin.php';
 ilPDFCompInstaller::registerRenderer($renderer, $path);
 
 $service = 'Test';
 $purpose = 'UserResult'; // According to name given. Call multiple times.
 ilPDFCompInstaller::registerRendererAvailability($renderer, $service, $purpose);
 
 $purpose = 'PrintViewOfQuestions'; // According to name given. Call multiple times.
 ilPDFCompInstaller::registerRendererAvailability($renderer, $service, $purpose);
 
?>

lang/ilias_<LangKey>.lang

Some general information on how internationalization is handled in plugins can be found in the main plugin documentation.

Sample Plugin

Kickstart codebase is here: TestPDFRenderer

Please contact the maintainer for plugin ideas & suggestions.