Commit f57a8af7 authored by Kevin von Spiczak's avatar Kevin von Spiczak
Browse files

[TASK] formatting

parent facb7b6e
# Ext: sg_mail
# Ext: sg_mail
<img src="https://www.sgalinski.de/typo3conf/ext/project_theme/Resources/Public/Images/logo.svg" />
......@@ -8,19 +8,19 @@ Repository: https://gitlab.sgalinski.de/typo3/sg_mail
Please report bugs here: https://gitlab.sgalinski.de/typo3/sg_mail
TYPO3 version: >7.6
TYPO3 version: >7.6
## About
This extension provides an email templating service and mail queue functionality for all your TYPO3 extensions.
It also supports Templates in various languages, which can be managed in the backend.
It also supports Templates in various languages, which can be managed in the backend.
Additionally sg_mail comes with multiple features that help to integrate with [ext:form](https://docs.typo3.org/typo3cms/extensions/form/).
sg_mail ist multi-site and multi-language ready.
## Usage
### Registering your Extension
### Registering your Extension
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/Sgmail** of your extension.
......@@ -46,15 +46,15 @@ Inside the file you have mandatory and optional settings you can define:
- 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
......@@ -65,16 +65,16 @@ A marker needs to be structured as follows:
- 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**
**Optional**
- template_path
You can provide a path to your mail template that differs from the default path with this setting.
**The template folder**
If not overwritten in your configuration file, the default location for your extensions templates is **ext/sg_example/Resources/Private/Templates/SgMail/{TemplateNameInUpperCamelCase}**.
Inside this folder you need a folder for every template you want to register. The name of the template file itself should be **template.html**
......@@ -112,23 +112,23 @@ Basic Usage:
3. Set or override all desired fields (i.e. setLanguage, setToAddresses, setTemplateName, setExtensionKey etc.)
4. Invoke the **sendEmail()** function
Example:
Example:
// get an instance of the service
/** @var MailTemplateService $mailService */
$mailService = $this->objectManager->get(MailTemplateService::class, 'confirm_mail', 'sg_example', ['username' => $username]);
$mailService->setFromName($this->settings['fromName']);
$mailService->setFromAddress($this->settings['fromEmail']);
$mailService->setToAddresses([$emailAddress]);
$mailService->setIgnoreMailQueue(TRUE);
// set the pageId (mandatory since version 4.0!!!)
$mailService->setPid(123);
// 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
$mailService->sendEmail();
......@@ -136,7 +136,7 @@ Example:
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
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.
......@@ -158,7 +158,7 @@ For more information on the TYPO3 scheduler extension read its [manual](https://
## Language handling
When you provide no language to the MailService API, the default language of the TYPO3 instance is used.
When you provide no language to the MailService API, the default language of the TYPO3 instance is used.
This happens also if the given iso code of the language is not known (inside the **sys_lang** table).
In your template editor you have automatically all languages of your page shown.
......@@ -199,7 +199,7 @@ With the **Mail Queue** mode, you can see the current content of your mailing qu
<br>
<img height="20px" width="20px" src="https://camo.githubusercontent.com/ee057cb37045beeccf8078f74e65e1774ec5e001/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f616374696f6e732f616374696f6e732d646f63756d656e742d696e666f2e737667"> Show further information
<br>
<img height="20px" width="20px" src="https://camo.githubusercontent.com/91c383d7beded93dbe6a62e2a1ae94bf82d1d783/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f616374696f6e732f616374696f6e732d646f63756d656e742d686973746f72792d6f70656e2e737667"> Show history
<img height="20px" width="20px" src="https://camo.githubusercontent.com/91c383d7beded93dbe6a62e2a1ae94bf82d1d783/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f616374696f6e732f616374696f6e732d646f63756d656e742d686973746f72792d6f70656e2e737667"> Show history
<br>
.... Expand/Collapse the options menu
<br>
......@@ -208,13 +208,13 @@ With the **Mail Queue** mode, you can see the current content of your mailing qu
<img height="20px" width="20px" src="https://camo.githubusercontent.com/53fd52618f310e4c31cca5a57df3b314bd0a7a9c/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f616374696f6e732f616374696f6e732d696e736572742d7265666572656e63652e737667"> Send this mail (if not already sent)
<br>
<img height="20px" width="20px" src="https://camo.githubusercontent.com/4b1188209e740e17a4ec0cd6583425696809017b/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f616374696f6e732f616374696f6e732d646f63756d656e742d766965772e737667"> View the content of this mail
Additionally you can now filter the mail queue or export it to a csv file.
## Blacklisting templates
It is possible to exlude certain templates for all or specific domains. Excluded templates are not shown in the backend module
and their mails are never send.
Mails from these templates are still logged and you can search for them in the backend module.
Mails from these templates are still logged and you can search for them in the backend module.
### Blacklisting templates for all domains
In the extension configuration setting **general.excludeTemplatesAllDomains**, you can specify which templates should be excluded for all domains with a comma seperated list.
......@@ -222,7 +222,7 @@ In the extension configuration setting **general.excludeTemplatesAllDomains**, y
Example:
sg_comments.approved, sg_comments.declined
The templates "approved" and "declined" of the extension sg_comments are blacklisted for every domain.
### Blacklisting templates for certain domains
......@@ -233,7 +233,7 @@ The comma seperated lists contain the page id and the templates to be excluded.
Example:
1, sg_comments.approved, sg_example.welcome;10, sg_comments.declined
The template "approved" of the extension sg_comments and the template "welcome" of the extension sg_example are blacklisted for the domain with the page id 1.
The template "declied" of the extension sg_comments is blacklisted for the domain with the page id 10.
......@@ -260,21 +260,21 @@ This extension uses two database tables:
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 an email 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.
### Service Classes
#### MailTemplateService
This class provides you with an API to the mailing functionality and various helper functions regarding the your templates.
This class provides you with an API to the mailing functionality and various helper functions regarding the your templates.
Here is an overview of some important functions:
###### function getDefaultTemplateMarker
Reads custom example template marker from your **locallang.xlf**. This is only useful if you need multi language examples in your Backend Marker
Reads custom example template marker from your **locallang.xlf**. This is only useful if you need multi language examples in your Backend Marker
###### 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
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
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment