From 22382bd394bb7ea64ae3af0f6eaa29fd431344f1 Mon Sep 17 00:00:00 2001
From: Torsten Oppermann <torsten@sgalinski.de>
Date: Wed, 27 Sep 2017 15:34:14 +0200
Subject: [PATCH] [TASK] Update documentation wip
---
README.md | 90 +++++++++++++++++++++++++++++++++++++++++--------------
1 file changed, 68 insertions(+), 22 deletions(-)
diff --git a/README.md b/README.md
index b6ff2389..3df0489d 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
--
GitLab