Templates
Templates are a Claroline system which allow users to customize how thing are printed to PDF or sent by message/email.
Each template as default template generated by the application. Final users can define their own templates later in Administration > Templates
Plugin configuration file
Your plugin must define its properties and the list of its templates in the Resources/config/config.yml file.
This file will be parsed by the plugin installer to install your plugin and create all your declared templates in the database.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
plugin:
# New template types declared by the plugin
templates:
- name: my_email_template
type: email # values : email|pdf|other
placeholders:
- my_placeholder
# - the list of the custom placeholders
- name: my_pdf_template
type: pdf
placeholders:
- my_placeholder
# - the list of the custom placeholders
Placeholders are variables we will replace by the current application value when we will use
a template (they are used in the template contents with % delimiters, aka. %my_placeholder%).
System template
Each template type require at least one system templates.
The system templates are created using DataFixtures and are automatically loaded during the claroline update/install process.
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
<?php
// my-plugin/Installation/DataFixtures/Template/MyEmailData.php
namespace MyVendor\MyPluginBundle\Installation\DataFixtures\Template;
use Claroline\CoreBundle\Installation\DataFixtures\AbstractTemplateFixture;
class MyEmailData extends AbstractTemplateFixture
{
protected static function getTemplateType(): string
{
return 'my_email_template';
}
protected function getSystemTemplates(): array
{
return [
'Claroline Connect' => [
'en' => [
'title' => 'The email object with %my_placeholder%',
'content' => $this->twig->render('@MyVendorMyPlugin/template/my_email.en.html.twig'),
],
'fr' => [
'title' => 'L\'objet de l\'email avec %my_placeholder%',
'content' => $this->twig->render('@MyVendorMyPlugin/template/my_email.fr.html.twig'),
],
],
];
}
}
In my-plugin/Resources/views/template/my_email.en.html.twig :
1
2
3
4
5
<p>
The content of the my system template.
We can use HTML and placholders %my_placeholder%.
</p>
NB. Users can’t edit or delete the system templates. We maintain them through the claroline updates.
Usage
You can use defined templates with the Claroline\CoreBundle\Template\TemplateManager service.
Default template
1
2
3
4
5
6
7
8
9
10
11
12
13
$locale = 'en';
// provide values for the placeholders defined for the template type
$placeholders = [
'my_placeholder' => 'toto',
];
// get the title text with replaced placeholders
$title = $this->templateManager->getTemplate('my_email_template', $placeholders, $locale, 'title');
// get the content html with replaced placeholders
$content = $this->templateManager->getTemplate('my_email_template', $placeholders, $locale);
// do something with the generated content
Custom Template
You may want to customize the template to use per entity. For example, each badge can define the template to use to generate their certificate.
Update your entity class :
1
2
3
4
5
6
7
8
9
10
namespace MyVendor\MyPluginBundle\Entity;
use Claroline\CoreBundle\Entity\Model\Template;
class MyEntity
{
// ...
use Template;
}
Sometimes you will need multiple templates for the same entity (for example, a template for sending something by email and one for PDF print). In this case you cannot use the provided Trait, you have to manually create ManyToOne relationship to the Template entity (see Template trait implementation).
Don’t forget to update your serializer :
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
namespace MyVendor\MyPluginBundle\Serializer;
use Claroline\AppBundle\API\Options;
use Claroline\CoreBundle\Entity\Template\Template;
use MyVendor\MyPluginBundle\Entity\MyEntity;
class MyEntitySerializer
{
private TemplateSerializer $templateSerializer;
public function __construct(TemplateSerializer $templateSerializer)
{
$this->templateSerializer = $templateSerializer;
}
public function serialize(MyEntity $object, ?array $options = []): array
{
$serialized = [];
// ...
if (!in_array(Options::SERIALIZE_MINIMAL, $options)) {
if ($object->getTemplate()) {
$serialized['template'] = $this->templateSerializer->serialize($object->getTemplate(), [Options::SERIALIZE_MINIMAL]);
}
}
return $serialized;
}
public function deserialize(array $data, MyEntity $object, ?array $options = []): MyEntity
{
if (array_key_exists('template', $data)) {
$template = null;
if (!empty($data['template']) && !empty($data['template']['id'])) {
/** @var Template $template */
$template = $this->om->getRepository(Template::class)->findOneBy(['uuid' => $data['template']['id']]);
}
$object->setTemplate($template);
}
return $object;
}
}
Add the field in your entity form (UI) :
1
2
3
4
5
6
7
8
9
10
11
12
{
name: 'template',
label: Template,
type: 'template',
options: {
picker: {
filters: [
{property: 'typeName', value: 'my_email_template', locked: true}
]
}
}
}
You can now use the custom template :
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
$myEntity = new MyEntity(); // in this example, we don't set a custom template for $myEntity so we will fallback on the default template
// ...
if ($myEntity->getTemplate()) {
// get the
$title = $this->templateManager->getTemplateContent($myEntity->getTemplate(), $placeholders, $locale, 'title');
$content = $this->templateManager->getTemplateContent($myEntity->getTemplate(), $placeholders, $locale);
} else {
// or fallback to use the default template if none is defined for the current entity
$title = $this->templateManager->getTemplate('my_email_template', $placeholders, $locale, 'title');
$content = $this->templateManager->getTemplate('my_email_template', $placeholders, $locale);
}
// do something with the generated content
Send a message
For template types with type: email.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// Send a message using a template
use Claroline\CoreBundle\Event\CatalogEvents\MessageEvents;
use Claroline\CoreBundle\Event\SendMessageEvent;
// get the title text with replaced placeholders
$title = $this->templateManager->getTemplate('my_email_template', $placeholders, $locale, 'title');
// get the content html with replaced placeholders
$content = $this->templateManager->getTemplate('my_email_template', $placeholders, $locale);
// use the event_dispatcher service to send the message
$this->dispatcher->dispatch(MessageEvents::MESSAGE_SENDING, SendMessageEvent::class, [
$content,
$title,
$receivers // a list of users
]);
Generate a PDF
For template types with type: pdf.
1
2
3
4
5
6
7
8
9
10
$locale = 'en';
// provide values for the placeholders defined for the template type
$placeholders = [
'my_placeholder' => 'toto',
];
$content = $this->templateManager->getTemplate('my_pdf_template', $placeholders, $locale);
// use the Claroline\EvaluationBundle\Manager\PdfManager service to generate PDF
$this->pdfManager->fromHtml($content);
Translations
- template.xx.json
We use lower case for every translation keys.
Create the template file in your Resources/translations folder. You can translate your template names and placeholders here.
1
2
3
4
5
6
7
{
"my_email_template": "The translated name of my template",
"my_email_template_desc": "The translated description of my template.",
"my_placeholder": "My placeholder",
"my_placeholder_desc": "My placeholder description"
}
Where my_email_template is the name you defined in your config file.