Skip to content
Snippets Groups Projects
Commit a0f17ce3 authored by Tim Wagner's avatar Tim Wagner
Browse files

[TASK] Multiple README fixes with code block highlighting

parent b11b02c9
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
Showing
with 111 additions and 110 deletions
README.md
+ 111
− 110
View file @ a0f17ce3
...@@ -15,91 +15,77 @@ TYPO3 version: >9.5 ...@@ -15,91 +15,77 @@ TYPO3 version: >9.5
This extension provides an email templating service and mail queue functionality for all your TYPO3 extensions. 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/). 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. sg_mail is multi-site and multi-language ready.
## Usage ## 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. 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. It needs to be a *.php* file and has to be inside the configuration folder
**typo3conf/ext/{your_extension}/Configuration/Sgmail** of your extension.
Additionally you need to make your registration file known in your **ext_localconf.php** file: Additionally, you need to make your registration file known in your **ext_localconf.php** file:
// register mail templates ```PHP
$GLOBALS['sg_mail']['my_extension_key']['unique_template_name'] = \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::extPath('my_extension_key') . '/Configuration/SgMail/MyTemplate.php'; // register mail templates
$GLOBALS['sg_mail']['my_extension_key']['unique_template_name'] = \TYPO3\CMS\Core\Utility\ExtensionManagementUtility::extPath('my_extension_key') . '/Configuration/SgMail/MyTemplate.php';
```
sg_mail will automatically parse valid configuration files of all extensions within your TYPO3 instance. sg_mail will automatically parse valid configuration files of all extensions within your TYPO3 instance.
Inside the file you have mandatory and optional settings you can define: Inside the file you have mandatory and optional settings you can define:
**Mandatory** #### Mandatory
- extension_key - **extension_key**: Needed to associate this template with the appropriate extension,
Needed to associate this template with the appropriate extension, - **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:
- template_key - **marker**: The variables name used in your template.
A unique identifier of your template. - **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.
- description #### Optional
A short description of your templates usage, displayed in the backend template editor. This should be a **language label**
- **template_path**: You can provide a path to your mail template that differs from the default path with this setting.
- subject #### The template folder
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.
**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}**. 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** 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**
**Example:** #### Example:
Your configuration file for the template "confirm_mail" should be located at **../Configuration/ConfirmMail.php**. Your configuration file for the template "confirm_mail" should be located at **../Configuration/ConfirmMail.php**.
A possible ConfirmMail.php file could look like this: A possible ConfirmMail.php file could look like this:
return [ ```PHP
'extension_key' => 'sg_example', return [
'template_key' => 'confirm_mail', 'extension_key' => 'sg_example',
'description' => 'LLL:EXT:sg_example/Resources/Private/Language/locallang.xlf:mail.confirm.description', 'template_key' => 'confirm_mail',
'subject' => 'LLL:EXT:sg_example/Resources/Private/Language/locallang.xlf:mail.confirm.subject', 'description' => 'LLL:EXT:sg_example/Resources/Private/Language/locallang.xlf:mail.confirm.description',
'markers' => [ 'subject' => 'LLL:EXT:sg_example/Resources/Private/Language/locallang.xlf:mail.confirm.subject',
[ 'markers' => [
'marker' => 'username', [
'type' => \SGalinski\SgMail\Service\MailTemplateService::MARKER_TYPE_STRING, 'marker' => 'username',
'value' => 'max.mustermann@example.org', 'type' => \SGalinski\SgMail\Service\MailTemplateService::MARKER_TYPE_STRING,
'description' => 'LLL:EXT:sg_energieportal/Resources/Private/Language/locallang.xlf:mail.marker.username' 'value' => 'max.mustermann@example.org',
], 'description' => 'LLL:EXT:sg_energieportal/Resources/Private/Language/locallang.xlf:mail.marker.username'
.... // more markers ],
] //... more markers
]; ]
];
```
The default path to the template.html file: ext/sg_example/Resources/Private/Templates/SgMail/ConfirmMail The default path to the template.html file: ext/sg_example/Resources/Private/Templates/SgMail/ConfirmMail
...@@ -114,31 +100,34 @@ Basic Usage: ...@@ -114,31 +100,34 @@ Basic Usage:
Example: Example:
// get an instance of the service ```PHP
/** @var MailTemplateService $mailService */ // get an instance of the service
$mailService = GeneralUtility::makeInstance(MailTemplateService::class, 'confirm_mail', 'sg_example', ['username' => $username]); /** @var MailTemplateService $mailService */
$mailService = GeneralUtility::makeInstance(MailTemplateService::class, 'confirm_mail', 'sg_example', ['username' => $username]);
$mailService->setFromName($this->settings['fromName']); $mailService->setFromName($this->settings['fromName']);
$mailService->setFromAddress($this->settings['fromEmail']); $mailService->setFromAddress($this->settings['fromEmail']);
$mailService->setToAddresses([$emailAddress]); $mailService->setToAddresses([$emailAddress]);
$mailService->setIgnoreMailQueue(TRUE); $mailService->setIgnoreMailQueue(TRUE);
// set the pageId (mandatory since version 4.0!!!) // set the pageId (mandatory since version 4.0!!!)
$mailService->setPid(123); $mailService->setPid(123);
// set the proper language for the mail (not necessary if you want the default language) // set the proper language for the mail (not necessary if you want the default language)
$mailService->setLanguage($GLOBALS['TSFE']->config['config']['language']); $mailService->setLanguage($GLOBALS['TSFE']->config['config']['language']);
// finally send the mail // finally send the mail
$mailService->sendEmail(); $mailService->sendEmail();
```
### The mail queue ### 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. 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 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. queueing your Mail (false) or immediately sending it (true).
* PRIORITY_LOWEST * PRIORITY_LOWEST
* PRIORITY_LOW * PRIORITY_LOW
...@@ -146,13 +135,14 @@ queueing your Mail(false) or immediately(true) sending it. ...@@ -146,13 +135,14 @@ queueing your Mail(false) or immediately(true) sending it.
* PRIORITY_HIGH * PRIORITY_HIGH
* PRIORITY_HIGHEST * PRIORITY_HIGHEST
The higher the priority, the more likely the mail will get send immediately (depending how "busy" the MailQueue is). The higher the priority, the more likely the mail will get sent immediately (depending on how "busy" the MailQueue is).
#### The command controller #### The command controller
To enable the mail queue functionality you need to configure the **SendMailCommandController**. 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. Go to your scheduler module in the TYPO3 Backend and set up a scheduled CommandController task.
Choose 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). For more information on the TYPO3 scheduler extension read its [manual](https://docs.typo3.org/typo3cms/extensions/scheduler/Index.html).
...@@ -161,24 +151,26 @@ For more information on the TYPO3 scheduler extension read its [manual](https:// ...@@ -161,24 +151,26 @@ For more information on the TYPO3 scheduler extension read its [manual](https://
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). 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. In your template editor you automatically have all languages of your page shown.
### Example ### Example
finishers { ```Typoscript
1 { finishers {
class = SGalinski\SgMail\Service\FormhandlerFinisherService 1 {
config { class = SGalinski\SgMail\Service\FormhandlerFinisherService
checkBinaryCrLf = message config {
template_key = your_template checkBinaryCrLf = message
extension_key = extension_key template_key = your_template
to_address = admin@sgalinski.de extension_key = extension_key
from_address = info@sgalinski.de to_address = admin@sgalinski.de
from_name = sgalinski.de from_address = info@sgalinski.de
ignore_mail_queue = TRUE from_name = sgalinski.de
} ignore_mail_queue = TRUE
} }
} }
}
```
## The Backend Module ## The Backend Module
With this extension comes a new module in the "WEB" section of your TYPO3 Backend. With this extension comes a new module in the "WEB" section of your TYPO3 Backend.
...@@ -209,34 +201,40 @@ With the **Mail Queue** mode, you can see the current content of your mailing qu ...@@ -209,34 +201,40 @@ With the **Mail Queue** mode, you can see the current content of your mailing qu
<br> <br>
<img height="20px" width="20px" src="https://camo.githubusercontent.com/4b1188209e740e17a4ec0cd6583425696809017b/68747470733a2f2f7261776769742e636f6d2f5459504f332f5459504f332e49636f6e732f6d61737465722f646973742f616374696f6e732f616374696f6e732d646f63756d656e742d766965772e737667"> View the content of this mail <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. Additionally, you can now filter the mail queue or export it to a csv file.
## Blacklisting templates ## 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. It is possible to exlude certain templates for all or specific domains.
Mails from these templates are still logged and you can search for them in the backend module. Excluded templates are not shown in the backend module, and their mails are never sent.
Mails from these templates are still logged, and you can search for them in the backend module.
### Blacklisting templates for all domains ### 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. In the extension configuration setting **general.excludeTemplatesAllDomains**, you can specify which templates should be excluded for all domains with a comma seperated list.
Example: Example:
sg_comments.approved, sg_comments.declined ```
sg_comments.approved, sg_comments.declined
```
The templates "approved" and "declined" of the extension sg_comments are blacklisted for every domain. The templates "approved" and "declined" of the extension sg_comments are blacklisted for every domain.
### Blacklisting templates for certain domains ### Blacklisting templates for certain domains
In the extension configuration setting **general.excludeTemplates**, ou can specify which templates should be excluded for which domains with a Semicolon separated list of comma separated list. In the extension configuration setting **general.excludeTemplates**, ou can specify which templates should be excluded for which domains with a Semicolon separated list of comma separated list.
The comma seperated lists contain the page id and the templates to be excluded. The comma seperated lists contain the page id, and the templates to be excluded.
Example: Example:
1, sg_comments.approved, sg_example.welcome;10, sg_comments.declined ```
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 "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. The template "declined" of the extension sg_comments is blacklisted for the domain with the page id 10.
If the page ids are missing or not correspond to a site root, the configuration has simply no effect. If the page ids are missing or not correspond to a site root, the configuration has simply no effect.
...@@ -245,21 +243,21 @@ In the backend module mode "Queue" you can filter for "Blacklisted" mails. Note: ...@@ -245,21 +243,21 @@ In the backend module mode "Queue" you can filter for "Blacklisted" mails. Note:
## Known Facts ## Known Facts
### Countries aren't respected yet. Currently just languages are used. ### Countries aren't respected yet. Currently, just languages are used.
## Developer Guide ## Developer Guide
### Database and Models ### Database and Models
This extension uses two database tables: 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 - **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.
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. - **tx_sgmail_domain_model_mail**:
If an email should ignore the mail queue, it is still inserted in this table with the **sent** flag set to true. 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. The extbase model classes for these tables are located at the *Domain\Model* folder.
...@@ -303,7 +301,7 @@ To change a fields identifier, select it in the form editor and enter your desir ...@@ -303,7 +301,7 @@ To change a fields identifier, select it in the form editor and enter your desir
sg_mail comes with two new finisher for your forms with the following settings regarding sg_mail integration: sg_mail comes with two new finisher for your forms with the following settings regarding sg_mail integration:
- **Template key**: If this field is empty, a unique template name will be generated and automatically inserted into the field, after the form definition has been saved. - **Template key**: If this field is empty, a unique template name will be generated and automatically inserted into the field, after the form definition has been saved.
The generated template name is based on the form identifier, concatenated with the finisher identifier (separated by `-`). The generated template name is based on the form identifier, concatenated with the finisher identifier (separated by `-`).
- **Automatic Registration**: A sg_mail registration will automatically be created. See the **Automatic Registration** section for more information - **Automatic Registration**: A sg_mail registration will automatically be created. See the **Automatic Registration** section for more information
- **Ignore Mail Queue**: Mails will get send immediately and not added to the mail queue - **Ignore Mail Queue**: Mails will get send immediately and not added to the mail queue
...@@ -313,16 +311,19 @@ If you select to automatically register your forms with sg_mail, the default htm ...@@ -313,16 +311,19 @@ If you select to automatically register your forms with sg_mail, the default htm
You can customize the TypoScript settings in the **setup.ts** in order to have control over automatically generated registration files: You can customize the TypoScript settings in the **setup.ts** in order to have control over automatically generated registration files:
# extension where automatic generated registrations are put. Will be appended with /Configuration/MailTemplates/. Make sure these folders exist! ```Typoscript
configurationLocation = your_extension_key # extension where automatic generated registrations are put. Will be appended with /Configuration/MailTemplates/. Make sure these folders exist!
configurationLocation = your_extension_key
# default html template file, which serves as a fallback for all mail templates # default html template file, which serves as a fallback for all mail templates
defaultHtmlTemplate = EXT:project_theme/Configuration/MailTemplates/Default.html defaultHtmlTemplate = EXT:project_theme/Configuration/MailTemplates/Default.html
```
--- ---
#### TypoScriptSettingsService #### 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. This Service enables you to access your typoscript settings outside 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. If you have no page id specific settings, set the page id to 0.
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