From 1c72c5258602be688503cd1a35dd049b61d87966 Mon Sep 17 00:00:00 2001
From: Torsten Oppermann <torsten@sgalinski.de>
Date: Mon, 8 May 2017 17:43:07 +0200
Subject: [PATCH] [TASK] First draft of the readme wip
---
README.md | 141 +++++++++++++++++++++++++++++++++++++++++++++++++++---
1 file changed, 135 insertions(+), 6 deletions(-)
diff --git a/README.md b/README.md
index a74ad7bf..239c4c61 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# Ext: sg_mail
+# Ext: sg_mail
<img src="https://www.sgalinski.de/typo3conf/ext/project_theme/Resources/Public/Images/logo.svg" />
@@ -53,7 +53,13 @@ Basic Usage:
2. Set all desired fields (i.e. setLanguage, setToAddresses, setTemplateName, setExtensionKey etc.)
3. Invoke the **sendEmail()** function
-You can also set the priority (setPriority function of the service) for your mails with the constants
+
+
+### The mail queue
+
+The mail queue holds all the mails that have been sent or should be sent in the future. You can view the mail queue in the backend module and interact with the entries.
+
+You can set the priority (setPriority function of the service) for your mails with the constants
of the **SGalinski\SgMail\Domain\Model\Mail** class. With the Flag **ignoreMailQueue** you can switch between
queueing your Mail(false) or immediately(true) sending it.
@@ -65,6 +71,14 @@ queueing your Mail(false) or immediately(true) sending it.
The higher the priority, the more likely the mail will get send immediately (depending how "busy" the MailQueue is).
+#### The command controller
+
+To enable the mail queue functionality you need to configure the **SendMailCommandController**.
+
+Go to your scheduler module in the TYPO3 Backend and setup a scheduled CommandController task. Chose the **SgMail SendMail:runSendMail** CommandController command and supply a frequency in seconds or [cron](https://en.wikipedia.org/wiki/Cron) format.
+
+For more information on the TYPO3 scheduler extension read its [manual](https://docs.typo3.org/typo3cms/extensions/scheduler/Index.html).
+
## Using sg_mail with Formhandler
In your **setup.ts** of your formhandler extension, you have to invoke the **FormhandlerFinisherService** of sg_mail.
@@ -89,17 +103,132 @@ finishers {
}
```
-
## Developer Guide
### Service Classes
-#### RegisterInterface
+##### Register Interface
+To register your extension you need at least one implementation of this interface.
+Inside the **init()** function of your Implementation you should define variables for the following purposes:
+
+######Template Key
+A unique Identifier for this particular template. It should be obvious from the template key for what purpose this template is intented.
+
+######Extension Key
+The extension key of the TYPO3 extension registering with sg_mail. This should be the same for all of your extensions!
+
+######Description
+A brief description about the template, visible in the backend module
+
+######subject
+The default subject text for the emails. It is possible to specify language specific texts with an associative array:
+
+ [
+ 'en' => 'english subject',
+ 'de' => 'german subject',
+ ...
+ ]
+
+######markers
+This is an array of information for substitute variables that are used to replace certain values at runtime.
+
+Each Array element should be its own array and structured like this:
+
+ [
+ 'marker' => 'marker_name',
+ 'type' => \SGalinski\SgMail\Service\MailTemplateService::MARKER_TYPE_STRING,
+ 'value' => 'some value',
+ 'description' => 'This marker is used for X in the email'
+ ]
+
+marker = the variable name you use in the template
+type = the date type of the variable
+value = an example value, visible in the backend to the editors
+description = a brief description for what this variable is intented for
+
+Finally you have to call the function **\SGalinski\SgMail\Service\MailTemplateService::registerTemplate** (this is only marked deprecated for public use)
+inside your **register()** function and pass all the necessary values.
+
+Now you can register the class in your **ext_localconf.php** with
+
+ \SGalinski\SgMail\Service\MailTemplateService::registerByFile('SGalinski\SgMail\Example\Register');
+
+
+You find a complete example of this process in the file **SGalinski\SgMail\Example\Register**
+
#### MailTemplateService
+This class provides you with an API to the mailing functionalitiy and various helper functions regarding the your templates.
+
+Here is an overview of some important functions:
+
+######function registerTemplate
+A static function that adds your template to the service. Should be called from within your **Register** class (see **RegisterInterface**).
+
+######function registerByFile
+Registers a template by providing a complete class name of your **RegisterInterface** implementation as an argument.
+Needs to be called from within your **ext_localconf.php**.
+
+######function getDefaultTemplateMarker
+Reads custom example template marker fom your **locallang.xlf**. This is only useful if you need multi language examples in your Backend Marker
+
+######function getRegisterArray
+Returns an array of all registered templates, with each element in the following format:
+
+ [
+ 'templatePath' => '/path/to/template',
+ 'description' => 'description of the template',
+ 'marker' => $arrayOfMarkers,
+ 'extension' => 'extension_key',
+ 'templateName' => 'unique_template_name',
+ 'subject' => 'The mail subject',
+ 'usage' => 'optional description of this templates usage'
+ ]
+
+######function loadPredefinedValuesForTemplate
+Sets the predefined values for this template that have been supplied by the editor. Use this method if you have no custom values for
+cc, bcc, replyTo, fromMail and fromName. Returns **false** if the template & extension key combination was not found.
+
+######function sendEmail
+Sends your mail or adds it to the mailing queue, depending on the settings. You can specify in with the boolean parameter if the preview values should be used or not.
+
+######function sendMailFromQueue
+Forces the sending of an E-Mail from within the queue. If it has already been sent, it gets send again.
+
+######function setRegisterArray
+Enables you to overwrite the register array. This overwrites **ALL** registered templates with the supplied data
+and should be handled with care.
+
+######function addAttachment
+With this function you can add attachments to your mail. The attachment must be of type *Swift_OutputByteStream*. You must also specify the content-type of the attachment.
+
+######function getMailMessage
+You can get the instance of **\TYPO3\CMS\Core\Mail\MailMessage** that is internally used by the service, if you want a more direct interaction with the mail object.
+
+######functions setX
+Sets the various variables to the supplied values. With these functions you can overwrite for instance from/cc/bcc Adresses, from name etc.
+
+You can also tell the **MailTemplateService** to not ignore this mail when adding to the mailing queue: **function setIgnoreMailQueue**.
+
#### FormhandlerFinisherService
+
+This class is an implementation of the **Typoheads\Formhandler\Finisher\AbstractFinisher** Class
+that is used by the extension [formhandler extension](https://typo3.org/extensions/repository/view/formhandler).
+
#### TypoScriptSettingsService
+This Service enables you to access your typoscript settings outside of your controller classes. You simply need to supply your page id and the extension key.
+If you have no page id specific settings, set the page id to 0.
+
## Database and Models
-### The mail queue
+This extension uses two database tables:
+- tx_sgmail_domain_model_template
+
+ Stores all template settings that have been provided via the backend module. The Default settings exist only in the register array and not in the database.
+
+- tx_sgmail_domain_model_mail
+
+ This table holds all the mails in the mailing queue. When they are sent, the flag **sent** is set to true and the **sending_time** is inserted. You can inspect the mailing queue with the backend module.
+ If a mail should ignore the mail queue, it is still inserted in this table with the **sent** flag set to true.
+
+The extbase model classes for these tables are located at the *Domain\Model* folder.
-#### The command controller
\ No newline at end of file
--
GitLab