Package: templates

Source: api/packages/templates · imported version 0.2.37. The sections after the README are extracted from the code on every docs build.

README

Purpose

General purpose of this package is to store various templates in database and assigning them to Events so that content based on these templates is automatically generated and/or sent to users.

Usage

Each template is defined by

• channel: class defining how the template is handled
• event: event to which the template is assigned

For every channel & event pair a single Variables definition is registered, which contains tokens that can be used in the template and replaced with values based on the data from the Event.

Analysing these three example files in tests:

• TestChannel.php
• TestVariables.php
• TestEventWithGetters.php

and looking at the Template facade is simplest way to understand how this package works.

Facade

There is a Template facade declared, which is used to register Event-Channel-Variable sets and can be used in testing (as it can be replaced with a fake using Template::fake()).

To register Event-Channel-Variable set, Template::register($eventClass, $channelClass, $variableClass) must be called, where:

• $eventClass can be any class that is dispatched as an event in any Ulams package
• $channelClass must be a class implementing TemplateChannelContract interface declared in this package
• $variableClass must be a class implementing TemplateVariableContract interface declared in this package

Channels & variables

This package has no Channels or Variables defined, everything should be created in separate packages.

• Templates-Email
• Templates-Certificates
• Templates-Pdf

Event Wrapper

Ulams\Templates\Events\EventWrapper is a class that wraps any event before trying to generate notification for it (and feed data from it to Template). This class contains methods for extracting necessary data from Event if that data is not available directly (for example User to which notification is being sent, and any other data that is required by registered Template).

Endpoints

All the endpoints are defined in

Tests

Run ./vendor/bin/phpunit --filter 'Ulams\\Templates\\Tests' to run tests. See tests folder as it’s quite good staring point as documentation appendix.

Test details:

Listeners

• Ulams\Templates\Listeners\TemplateEventListener this listeners listens to all Ulams namespace events, checks if event is registered for any Template, and passes the event wrapped in EventWrapper to processing (so if event is registered and has corresponding Template, notification using that Template will be sent)

Usage on front end

Admin panel

These screens will only be available if at least one Template is registered (for example any package implementing Channel and Variables is installed).

Left menu

List of templates

Creating/editing template

Permissions

Permissions are defined in Enum and seeded in Seeder.

Roadmap. Todo. Troubleshooting

• ???

More documentation in the package

• api/packages/templates/ADMIN.md
• api/packages/templates/docs/edit.png
• api/packages/templates/docs/list.png
• api/packages/templates/docs/menu.png

API endpoints

Method	Path	Auth	Action
GET	/api/admin/templates	yes	TemplatesAdminApiController@list
POST	/api/admin/templates	yes	TemplatesAdminApiController@create
GET	/api/admin/templates/events	yes	TemplatesAdminApiController@events
GET	/api/admin/templates/variables	yes	TemplatesAdminApiController@variables
GET	/api/admin/templates/assignable	yes	TemplatesAdminApiController@assignable
GET	/api/admin/templates/assigned	yes	TemplatesAdminApiController@assigned
GET	/api/admin/templates/{id}	yes	TemplatesAdminApiController@read
GET	/api/admin/templates/{id}/preview	yes	TemplatesAdminApiController@preview
PATCH	/api/admin/templates/{id}	yes	TemplatesAdminApiController@update
DELETE	/api/admin/templates/{id}	yes	TemplatesAdminApiController@delete
POST	/api/admin/templates/{id}/assign	yes	TemplatesAdminApiController@assign
POST	/api/admin/templates/{id}/unassign	yes	TemplatesAdminApiController@unassign
POST	/api/admin/events/trigger-manually/{id}	yes	EventAdminApiController@triggerManually

Permissions

Permission	Seeded for roles	Constant
template_create	admin	TemplatesPermissionsEnum::TEMPLATES_CREATE
template_delete	admin	TemplatesPermissionsEnum::TEMPLATES_DELETE
template_update	admin	TemplatesPermissionsEnum::TEMPLATES_UPDATE
template_list	admin	TemplatesPermissionsEnum::TEMPLATES_LIST
template_read	admin	TemplatesPermissionsEnum::TEMPLATES_READ
events_trigger	admin	TemplatesPermissionsEnum::EVENTS_TRIGGER

Settings

Registered with AdministrableConfig::registerConfig (editable in the admin panel under Configuration → Settings).

None.

Events

Event	Description	Notification templates
EventWrapper	Event should have methods declared for retrieving its data, for example Course related event should have getCourse() method, but if it does not, we can try to extract ‘course’ property of the object (either from toArray method or by using Reflection) This wrapper exists for enabling extraction of any available data from event instance.
ManuallyTriggeredEvent		Email, Pdf, Sms

Notification templates registered here

None.

Artisan commands

None.

Scheduled jobs

None.

Environment variables read

None.