craft-newsletter
所属分类：建站系统
开发工具：PHP
文件大小：0KB
下载次数：0
上传日期：2023-08-05 14:16:58
上 传 者：
sh-1993
说明： Craft CMS新闻稿插件，
(Craft CMS Newsletter plugin,)
文件列表:
CHANGELOG.md (1999, 2023-08-05)
LICENSE.md (1072, 2023-08-05)
composer.json (2129, 2023-08-05)
ecs.php (478, 2023-08-05)
logo.png (9283, 2023-08-05)
src/ (0, 2023-08-05)
src/Newsletter.php (9146, 2023-08-05)
src/adapters/ (0, 2023-08-05)
src/adapters/BaseNewsletterAdapter.php (253, 2023-08-05)
src/adapters/Brevo.php (7206, 2023-08-05)
src/adapters/Dummy.php (1324, 2023-08-05)
src/adapters/Mailchimp.php (6301, 2023-08-05)
src/adapters/Mailjet.php (5636, 2023-08-05)
src/adapters/NewsletterAdapterInterface.php (528, 2023-08-05)
src/config.php (779, 2023-08-05)
src/controllers/ (0, 2023-08-05)
src/controllers/NewsletterController.php (1265, 2023-08-05)
src/icon-mask.svg (2693, 2023-08-05)
src/icon.svg (2693, 2023-08-05)
src/migrations/ (0, 2023-08-05)
src/migrations/m230729_210357_switch_sendinblue_to_brevo.php (844, 2023-08-05)
src/models/ (0, 2023-08-05)
src/models/NewsletterForm.php (1139, 2023-08-05)
src/models/Settings.php (1041, 2023-08-05)
src/templates/ (0, 2023-08-05)
src/templates/newsletterAdapters/ (0, 2023-08-05)
src/templates/newsletterAdapters/Brevo/ (0, 2023-08-05)
src/templates/newsletterAdapters/Brevo/settings.twig (1903, 2023-08-05)
src/templates/newsletterAdapters/Dummy/ (0, 2023-08-05)
src/templates/newsletterAdapters/Dummy/settings.twig (253, 2023-08-05)
src/templates/newsletterAdapters/Mailchimp/ (0, 2023-08-05)
src/templates/newsletterAdapters/Mailchimp/settings.twig (1021, 2023-08-05)
src/templates/newsletterAdapters/Mailjet/ (0, 2023-08-05)
src/templates/newsletterAdapters/Mailjet/settings.twig (815, 2023-08-05)
src/templates/settings.twig (1883, 2023-08-05)
src/translations/ (0, 2023-08-05)
src/translations/fr/ (0, 2023-08-05)
src/translations/fr/newsletter.php (2925, 2023-08-05)
# Newsletter Plugin for Craft CMS
[]((https://packagist.org/packages/jub/craft-newsletter))
[](https://packagist.org/packages/jub/craft-newsletter)
Newsletter for Craft CMS plugin makes it possible to let end users subscribe with various emailing services from a frontend form.
It currently supports the following services:
* Mailchimp
* Mailjet
* Brevo (ex Sendinblue)
This plugin is GDPR compliant and requires the user to give its consent when subscribing to the newsletter.
> Similar to Craft Mailer adapters, you can even [create your own adapter](#how-to-create-an-adapter) to connect to unsupported services.
## Requirements
This plugin requires Craft CMS 4.0.0 or later and PHP 8.0.2 or later.
> In order to support automatic Google reCAPTCHA verification, you will need to install `jub/craft-google-recaptcha` plugin.
## Installation
1. Install with composer via `composer require jub/craft-newsletter` from your project directory.
2. Install the plugin in the Craft Control Panel under Settings → Plugins, or from the command line via `./craft install/plugin newsletter`.
## Configuration
### Control Panel
You can manage configuration setting through the Control Panel by going to Settings → Newsletter
* From the **Service type** dropdown, select the service type you wish to use to handle newsletter users subscription
* Provide the required API keys and parameters [as described below](#service-configuration).
* If Google reCAPTCHA plugin is installed and enabled, choose whether to verify the submission or not using the **Enable Google reCAPTCHA** light-switch.
> When enabled, the Google reCAPTCHA feature will **not** render the frontend widget for you. You have to add `{{ craft.googleRecaptcha.render() }}` somewhere in the form view.
#### Service configuration
##### Mailjet settings
* **API Key** (`apiKey`)
* **API Secret** (`apiSecret`)
* **List ID** (optional) (`listId`)
You can find these informations in your [Mailjet account informations](https://app.mailjet.com/account) in the REST API keys section.
You can provide a [contact list ID](https://app.mailjet.com/contacts) in order to subscribe the enduser to a specific one.
> If no list ID is provided, user will only be created as a contact.
##### Brevo (ex Sendinblue) settings
* **API Key** (`apiKey`)
* **List ID** (optional, required if DOI is on) (`listId`)
* **Activate Double Opt-in (DOI)** (optional) (`doi`)
* **Mail Template ID** (required if DOI is on) (`doiTemplateId`)
* **Redirection URL** (required if DOI is on) (`doiRedirectionUrl`)
You can find these informations in your [Brevo account](https://app.brevo.com/settings/keys/api).
You can provide a [contact list ID](https://app.brevo.com/contact/list-listing) in order to subscribe the enduser to a specific one.
You can also enable Brevo Double Opt-in feature. You will need a Sendinblue template as described [here](https://help.brevo.com/hc/en-us/articles/360019540880-Create-a-double-opt-in-DOI-confirmation-template-for-Sendinblue-form).
> If no list ID is provided, user will only be created as a contact.
##### Mailchimp settings
* **API Key** (`apiKey`): You can find that information from your [Mailchimp account](https://us4.admin.mailchimp.com/account/api/).
* **Server prefix** (`serverPrefix`): You can find that information by looking at the url when logged into your Mailchimp account. For instance, `https://us4.admin.mailchimp.com/account/api/` indicate the server prefix to use is `us4`
* **Audience ID** (`listId`): You can find that information in `Audience` > `All contacts` > `Settings` > `Audience name and campaign defaults`
### Configuration file
You can create a `newsletter.php` file in the `config` folder of your project and provide the settings as follow (example):
```php
return [
"adapterType" => \juban\newsletter\adapters\Mailjet::class,
"adapterTypeSettings" => [
'apiKey' => '',
'apiSecret' => '',
'listId' => ''
],
"recaptchaEnabled" => true
];
```
Depending on the service and its specific settings, adjust the `adapterType` to the according service adapter class name and provide required parameters in the `adapterTypeSettings` associative array (see [Service configuration](#service-configuration)).
> Any value provided in that file will override the settings from the Control Panel.
## Front-end form
You can use the following template as a starting point for your registration form:
```twig
{# @var craft \craft\web\twig\variables\CraftVariable #}
{# @var newsletterForm \juban\newsletter\models\NewsletterForm #}
{% if craft.app.plugins.plugin('newsletter') is not null %}
{# If there were any validation errors, a `newsletterForm` variable will be passed to the template, which contains the posted values and validation errors. If that’s not set, we’ll default to a new newsletterForm. #}
{% set newsletterForm = newsletterForm ?? create('juban\\newsletter\\models\\NewsletterForm') %}
{# success notification #}
{% if success is defined and success %}
{{ 'Your newsletter subscription has been taken into account. Thank you.'|t }}
{% endif %}
{% endif %}
```
The `newsletter/newsletter/subscribe` action expects the following inputs submitted as `POST`:
* `email`: User email to subscribe
* `consent`: Any value indicating that the user gives its consent to receive the newsletter
> Don’t forget to add `{{ craft.googleRecaptcha.render() }}` in the form view if the Google reCAPTCHA verification is enabled.
## XHR / AJAX form
Alternatively, you can submit the newsletter form with Javascript.
This gives you more freedom to provide visual effects to the user and prevents the page from reloading and scrolling to the top of the page.
The downside is that you need to write the ajax-request.
Use the example below as a reference, note the required `application/json` header:
```javascript
var data = new FormData();
data.append("consent", consent);
data.append("email", email);
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function() {
if (this.readyState === 4) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://{YOUR_DOMAIN}/actions/newsletter/newsletter/subscribe/");
xhr.setRequestHeader("Accept", "application/json");
xhr.send(data);
```
> If the Google reCAPTCHA verification is enabled, add the `data.append("g-recaptcha-response", "");` to the request as well!
## Custom validations
You can provide your own validations on frontend form submission in a project module or a plugin using the `afterValidate` event on the `NewsletterForm` model:
```php
use yii\base\Event;
use juban\googlerecaptcha\GoogleRecaptcha;
Event::on(
NewsletterForm::class,
NewsletterForm::EVENT_AFTER_VALIDATE,
static function (Event $event) {
$form = $event->sender;
$isSpam = // custom spam detection logic...
if($isSpam) {
$this->addError('email', 'Spam detected!');
}
}
);
```
## How to create an adapter
To add a new adapter for unsupported services:
Create an adapter class that extends the `juban\newsletter\adapters\BaseNewsletterAdapter` class.
Some small example:
```php
namespace juban\newsletter\adapters;
use Craft;
class MySuperNewsletterAdapter extends BaseNewsletterAdapter
{
// Declare every attributes required by the service (ie API keys and secrets, etc...)
public $apiKey;
// Store any error occuring in the subscribe method here
private $_errorMessage;
/**
* @inheritdoc
*/
public function behaviors(): array
{
// Support for setting defined in environment variables or aliases
$behaviors = parent::behaviors();
$behaviors['parser'] = [
'class' => EnvAttributeParserBehavior::class,
'attributes' => [
'apiKey'
],
];
return $behaviors;
}
/**
* @inheritdoc
*/
public static function displayName(): string
{
return 'My Service Name'; // Service name as shown in the adapter type dropdown
}
/**
* @inheritdoc
*/
public function getSettingsHtml()
{
// Render the adapter settings templates
// Adapt the path according to your module / plugin
return Craft::$app->getView()->renderTemplate('newsletter/newsletterAdapters/MySuperNewsletterAdapter/settings', [
'adapter' => $this
]);
}
/**
* Try to subscribe the given email into the newsletter mailing list service
* @param string $email
* @return bool
*/
public function subscribe(string $email): bool
{
// Call the service API here
$this->_errorMessage = null;
if(!MySuperNewsletterService::subscribe($email)) {
// If something goes wrong, store the error message
$this->_errorMessage = MySuperNewsletterService::getError();
return false;
}
return true;
}
/**
* Return the latest error message after a call to the subscribe method
* @return null|string
*/
public function getSubscriptionError(): string
{
return $this->_errorMessage;
}
/**
* @inheritdoc
*/
protected function defineRules(): array
{
// Validation rules for the adapter settings should be defined here
$rules = parent::defineRules();
$rules[] = [['apiKey'], 'trim'];
$rules[] = [['apiKey'], 'required'];
return $rules;
}
}
```
The template settings view could look like this:
```twig
{% import "_includes/forms" as forms %}
{{ forms.autosuggestField({
label: "API Key"|t('newsletter'),
id: 'apiKey',
name: 'apiKey',
required: true,
suggestEnvVars: true,
value: adapter.apiKey,
errors: adapter.getErrors('apiKey')
}) }}
```
> The adapter model can be accessed in the twig view using the `adapter` variable.
Last, in a module or a plugin, register the adapter as follow:
```php
use craft\events\RegisterComponentTypesEvent;
use juban\newsletter\Newsletter;
Event::on(
Newsletter::class,
Newsletter::EVENT_REGISTER_NEWSLETTER_ADAPTER_TYPES,
static function (RegisterComponentTypesEvent $event) {
$event->types[] = MySuperNewsletterAdapter::class;
}
);
```
## Roadmap
* Support additional form fields
* Support for multiple lists
---
Base plugin icon makes use of [Font Awesome Free](https://fontawesome.com)
近期下载者：
相关文件：
收藏者：