Manual Mail Templates

The concept of 'Manual Mail Templates' is best described as a feature which enables services/modules to provide text templates for a 'User-to-User Email' in a specific context.

Often tutors / admins send the emails with the same purpose and texts to course members, e.g. to ask them if they have problems with the course because they have not used the course yet.

Context Registration

A module or service MAY announce its email template contexts to the system by adding them to their respective module.xml or service.xml. The template context id has to be globally unique. An optional path can be added if the module/service directory layout differs from the ILIAS standard, where most files are located in a ./classes directory.

<?xml version = "1.0" encoding = "UTF-8"?>
<module xmlns="http://www.w3.org" version="$Id$" id="crs">
    ...
    <mailtemplates>
        <context id="crs_context_manual" class="ilCourseMailTemplateContext" />
    </mailtemplates>
</module>

If registered once, every email template context class defined in a module.xml or service.xml has to extend the base class \ilMailTemplateContext. All abstract methods MUST be implemented to make a template context usable.

• getId(): string
• getTitle(): string
• getDescription(): string
• getSpecificPlaceholders(): array
• resolveSpecificPlaceholder(string $placeholderId, array $contextParameters, \ilObjUser $recipient = null, $htmlMarkup = false): string

A collection of context specific placeholders can be returned by a simple array definition. The key of each element should be a unique placeholder id. Each placeholder contains (beside its id) a placeholder string and a label which is used in the user interfaced.

return [
    'crs_title' => [
        'placeholder' => 'CRS_TITLE',
        'label' => $lng->txt('crs_title')
    ],
    'crs_link' => [
        'placeholder' => 'CRS_LINK',
        'label' => $lng->txt('crs_mail_permanent_link')
    ]
];

Supposing the context registration succeeded and you properly derived a context PHP class providing all necessary data and placeholders, you are now able to use your registered context in your component and build hyperlinks to the mail system, transporting your context information.

Context Usage Example

Given you created a context named crs_context_tutor_manual ...

global $DIC;

class ilCourseMailTemplateTutorContext extends \ilMailTemplateContext
{
    // [...]
    const ID = 'crs_context_tutor_manual';
    // [...]
}

... you can provide a hyperlink to the mail system (or more precisely to \ilMailFormGUI) as follows:

$DIC->ctrl()->redirectToUrl(
    \ilMailFormCall::getRedirectTarget(
        $this, // The referring ILIAS controller aka. GUI when redirecting back to the referrer
        'participants', // The desired command aka. the method to be called when redirecting back to the referrer
        [], // Key/Value array for parameters important for the ilCtrl/GUI context when when redirecting back to the referrer, e.g. a ref_id
        [
           'type' => 'new', // Could also be 'reply' with an additional 'mail_id' paremter provided here
        ],
        [
            \ilMailFormCall::CONTEXT_KEY => \ilCourseMailTemplateTutorContext::ID, // don't forget this!
            'ref_id' => $courseRefId,
            'ts'     => time(),
            // further parameters which will be later automatically passed to your context class 
        ]
    )
);

Parameters required by your mail context class MUST be provided as a key/value pair array in the fifth parameter of \ilMailFormCall::getRedirectTarget. These parameters will be passed back to your context class when the mail system uses \ilMailTemplateContext::resolveSpecificPlaceholder(...) as callback when an email is actually sent and included placeholders should be replaced. You also MUST add a key \ilMailFormCall::CONTEXT_KEY with your context id as value to this array.