diff --git a/README.md b/README.md index b6ff2389c32f758acd5357b77722661bf1da8195..3df0489d06b94d9ef571b16ae40a6884a44ddb31 100644 --- a/README.md +++ b/README.md @@ -21,53 +21,99 @@ Additionally sg_mail provides a finisher class for the [Formhandler](https://typ ## Usage ### Registering your Extension -To make sg_mail available for your extension, you have to register it inside your **ext_localconf.php** -by supplying a path string to an implementation of **SGalinski\SgMail\Service\RegisterInterface** with: +To register your extension with sg_mail, you need a **Configuration File** for each template you want to integrate. +It needs be a *.php* file and has to be inside the Configuration folder **typo3conf/ext/{your_extension}/Configuration** of your extension. +The naming of the file should be in upper camel case, matching your template name. -* your extension key -* a name for the template -* the path to your default template files (template files should be named *language_code*.template.html. Example: en.template.html) -* a brief description of the template (when is it used ?) -* the template markers(placeholder variables) -* the subjects for all templates. Here you have to use an associative array language_code => subject +sg_mail will automatically parse valid configuration files of all extensions within your TYPO3 instance. -**Example** : +Inside the file you have mandatory and optional settings you can define: -A fully working example class can be found here: **SGalinski\SgMail\Example\Register** +**Mandatory** -All you need to do to get the example to work is registering your class in **ext_localconf.php** with: +- extension_key + Needed to associate this template with the appropriate extension, - \SGalinski\SgMail\Service\MailTemplateService::registerByFile('SGalinski\SgMail\Example\Register'); +- template_key + A unique identifier of your template. + +- description + A short description of your templates usage, displayed in the backend template editor. This should be a **language label** + +- subject + The default mail subject used for this Template. Here you can also provide a language label. + +- markers + An array of placeholder variables. Are dynamically replaced by the appropriate values. If you don't want any markers, provide an empty array. + + A marker needs to be structured as follows: + + - marker + The variables name used in your templates. + + - type + Here you can specify the variable type by using one of the constants in the **\SGalinski\SgMail\Service\MailTemplateService** class. + + - value + An example value of this marker. Also used for previewing your mails in the backend module. + + - description + A short text describing the purpose of this marker. + + +**Optional** + +- template_path + You can provide a path to your mail template that differs from the default path with this setting. + + + +**Example:** + +Your configuration file for the template "confirm_mail" should be **../Configuration/ConfirmMail.php**. + +A possible ConfirmMail.php file could look like this: + + return [ + 'extension_key' => 'sg_example', + 'template_key' => 'confirm_mail', + 'description' => 'LLL:EXT:sg_example/Resources/Private/Language/locallang.xlf:mail.confirm.description', + 'subject' => 'LLL:EXT:sg_example/Resources/Private/Language/locallang.xlf:mail.confirm.subject', + 'markers' => [ + [ + 'marker' => 'username', + 'type' => \SGalinski\SgMail\Service\MailTemplateService::MARKER_TYPE_STRING, + 'value' => 'max.mustermann@example.org', + 'description' => 'LLL:EXT:sg_energieportal/Resources/Private/Language/locallang.xlf:mail.marker.username' + ], + .... // more markers + ] + ]; ### Send an email with the MailTemplateService Basic Usage: 1. Get an instance of MailTemplateService -2. Set all desired fields (i.e. setLanguage, setToAddresses, setTemplateName, setExtensionKey etc.) -3. Invoke the **sendEmail()** function +2. Provide the **template_name**, **extension_key** and marker array in the constructor +3. Set or override all desired fields (i.e. setLanguage, setToAddresses, setTemplateName, setExtensionKey etc.) +4. Invoke the **sendEmail()** function Example: // get an instance of the service /** @var MailTemplateService $mailService */ - $mailService = $this->objectManager->get(MailTemplateService::class); - - // set the extension key & template name (mandatory!) - $mailService->setExtensionKey('your_extension_key'); - $mailService->setTemplateName($this->settings['templateName']); + $mailService = $this->objectManager->get(MailTemplateService::class, 'confirm_mail', sg_example', ['username' => $username]); - // set all the custom fields, these fields all have fallbacks from your configuration or the code $mailService->setFromName($this->settings['fromName']); $mailService->setFromAddress($this->settings['fromEmail']); $mailService->setToAddresses([$emailAddress]); $mailService->setIgnoreMailQueue(TRUE); - $mailService->setMarkers(['link' => $uri]); // set the pageId (mandatory since version 4.0!!!) $mailService->setPid(123); - // set the proper language for the mail + // set the proper language for the mail (not necessary if you want the default language) $mailService->setLanguage($GLOBALS['TSFE']->config['config']['language']); // finally send the mail