Skip to content

Commit

Permalink
merged 3.x code into email-template-themes
Browse files Browse the repository at this point in the history
  • Loading branch information
@akshaybokaderanium
akshaybokaderanium committed Sep 11, 2023
2 parents b1550e5 + d48e82a commit 1fe362a
Show file tree
Hide file tree
Showing 53 changed files with 256 additions and 801 deletions.
29 changes: 0 additions & 29 deletions .github/workflows/php-cs-fixer.yml
View file

This file was deleted.

117 changes: 59 additions & 58 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,8 @@
# Email template editor for Filament
# Email template editor for Filament 3.0

[![Latest Version on Packagist](https://img.shields.io/packagist/v/visualbuilder/email-templates.svg?style=flat-square)](https://packagist.org/packages/visualbuilder/email-templates)
[![Total Downloads](https://img.shields.io/packagist/dt/visualbuilder/email-templates.svg?style=flat-square)](https://packagist.org/packages/visualbuilder/email-templates)
[![Tests](https://github.com/visualbuilder/email-templates/actions/workflows/run-tests.yml/badge.svg)](https://github.com/visualbuilder/email-templates/actions/workflows/run-tests.yml)
[![Check & fix styling](https://github.com/visualbuilder/email-templates/actions/workflows/php-cs-fixer.yml/badge.svg)](https://github.com/visualbuilder/email-templates/actions/workflows/php-cs-fixer.yml)
[![run-tests](https://github.com/visualbuilder/email-templates/actions/workflows/run-tests.yml/badge.svg?branch=3.x)](https://github.com/visualbuilder/email-templates/actions/workflows/run-tests.yml)

### Why businesses and applications should use Email Templates
- **Time-saving**: Email templates eliminate the need to create emails from scratch, saving valuable time and effort.
Expand All @@ -22,22 +21,26 @@
- Templates can include model attribute tokens or config values which will be replaced, eg ##user.name## or ##config.app.name##
- Templates can be saved with different locales for multi-lingual capability.
- A generic method for quickly creating mail classes to speed up adding new templates and faster automation possiblities.
- Theme editor - Set your own colours and apply to specific templates.

We use the standard Laravel mail sending capability, the package simply allows content editing and faster adding of new templates.
We use the standard Laravel mail sending capability, the package simply allows content editing and faster adding of new template Classes

![Email Preview](./guides/TemplateScreenShot.png)
![Email Preview](./media/ThemeEditor.png)

## Installation

Get the package via composer:
```bash
composer require visualbuilder/email-templates
```
Run the install command
Running the install command will copy the template views, migrations, seeders and config file to your app.

The --seed option will populate 7 default templates which you can then edit in the admin panel.
```bash
php artisan filament-email-templates:install
php artisan filament-email-templates:install --seed
```


### Adding the plugin to a panel
Add this plugin to panel using plugins() method in app/Providers/Filament/AdminPanelProvider.php:
```bash
Expand All @@ -53,20 +56,14 @@ public function panel(Panel $panel): Panel
]);
}
```
Menu Group and sort order can be set in the config

## Publish EmailTemplateResource

You can publish EmailTemplateResource to your project. Run the command given below then go to `config/email-templates.php` and set `publish_resource` to `true`

```bash
php artisan email-template:publish
```

## Usage

### HTML Editor
Edit email content in the admin and use tokens to inject model or config content.
![Email Preview](./guides/EmailEditor.png)
![Email Preview](./media/EmailEditor.png)

Note: The seeder can also be edited directly if you wish to prepopulate with your own content.
`Database\Seeders\EmailTemplateSeeder.php`
Expand All @@ -92,13 +89,24 @@ The following email templates are included to get you started and show different
- **User Locked Out** - Oops - What to do now?
- **User Login** - Success

Not all systems will require a login notification, but it's good practice for security so include here.
Not all systems will require a login notification, but it's good practice for security so included here.

#### New User Registered Email
A new **Registered** event is triggered when creating a new user.

It's good practice to welcome the new user to your platform with a friendly email, so we've included a listener for the Illuminate\Auth\Events\Registered Event
and will send the email if enabled in the config.
We want to welcome new users with a friendly email so we've included a listener for the Illuminate\Auth\Events\Registered Event
which will send the email if enabled in the config:-

```php
'send_emails' => [
'new_user_registered' => true,
'verification' => true,
'user_verified' => true,
'login' => true,
'password_reset_success' => true,
],

```

#### User Verify Email
This notification is built in to Laravel so we have overidden the default toMail function to use our custom email template.
Expand All @@ -120,6 +128,9 @@ and include the **verified** middleware in your routes.
Another Laravel built in notification, but to enable the custom email just add this function to your authenticatable user model.

```php

use Visualbuilder\EmailTemplates\Notifications\UserResetPasswordRequestNotification;

/**
* @param $token
*
Expand All @@ -129,68 +140,57 @@ Another Laravel built in notification, but to enable the custom email just add t
{
$url = \Illuminate\Support\Facades\URL::secure(route('password.reset', ['token' => $token, 'email' =>$this->email]));

$this->notify(new \Visualbuilder\EmailTemplates\Notifications\UserResetPasswordRequestNotification($url));
$this->notify(new UserResetPasswordRequestNotification($url));
}
```


### Customising the email template
Some theme colour options have been provided. Email templates will use the default theme unless you specify otherwise on the email template.

In the config file ``config/email-templates.php`` logo,colours and messaging can be updated.
In the config file ``config/filament-email-templates.php`` logo, contacts, links and admin preferences can be set
```php
//Default Email Styling
'logo' => 'media/email-templates/logo.png',

//Default Logo
'logo' => 'media/email-templates/logo.png',

//Logo size in pixels -> 200 pixels high is plenty big enough.
'logo_width' => '476',
'logo_height' => '117',
'logo_width' => '476',
'logo_height' => '117',

//Content Width in Pixels
'content_width' => '600',

//Background Colours
'header_bg_color' => '#B8B8D1',
'body_bg_color' => '#f4f4f4',
'content_bg_color' => '#FFFFFB',
'footer_bg_color' => '#5B5F97',
'callout_bg_color' => '#B8B8D1',
'button_bg_color' => '#FFC145',

//Text Colours
'body_color' => '#333333',
'callout_color' => '#000000',
'button_color' => '#2A2A11',
'anchor_color' => '#4c05a1',
'content_width' => '600',

//Contact details included in default email templates
'customer-services' => ['email' => '[email protected]',
'customer-services' => ['email' => '[email protected]',
'phone' => '+441273 455702'],

//Footer Links
'links' =>[
['name'=>'Website','url'=>'https://yourwebsite.com','title'=>'Goto website'],
['name'=>'Privacy Policy','url'=>'https://yourwebsite.com/privacy-policy','title'=>'View Privacy Policy'],
'links' => [
['name' => 'Website', 'url' => 'https://yourwebsite.com', 'title' => 'Goto website'],
['name' => 'Privacy Policy', 'url' => 'https://yourwebsite.com/privacy-policy', 'title' => 'View Privacy Policy'],
],

```

If you wish to directly edit the template blade file see the primary template here:-
If you wish to directly edit the template blade files see the primary template here:-
`resources/views/vendor/vb-email-templates/email/default.php`

You are free to create new templates in this directory which will be automatically visible in the email template editor for selection.
You are free to create new templates in this directory which will be automatically visible in the email template editor dropdown for selection.

### Translations
Each email template has a key and a language so

**Key**: user-password-reset
**Language**: en_gb

Allows the relevant template to be selected based on the users locale - You will need to save the users preferred language to implement this.
We opted to use a separate record for each locale (rather than using a json column with an object) as most of the attributes values are content that should be translated. So in this case it makes
more sense to have a separate row.
**Language**: en_gb

This allows the relevant template to be selected based on the users locale - You will need to save the users preferred language to implement this.

Please note laravel default locale is just "en" we prefer to separate British and American English so typically use en_GB and en_US instead.
Please note laravel default locale is just "en" we prefer to separate British and American English so typically use en_GB and en_US instead but you can set this value as you wish.

Languages that should be shown on the language picker can be set in the config

```php
'default_locale' => 'en_GB',

Expand All @@ -205,22 +205,22 @@ Languages that should be shown on the language picker can be set in the config
]
```

![Email Preview](./guides/Languages.png)
![Language Picker](./media/Languages.png)

Flag icons are loaded from CDN: https://cdn.jsdelivr.net/gh/lipis/[email protected]/css/flag-icons.min.css
see https://www.npmjs.com/package/flag-icons


### Creating a new Mail Class
### Creating new Mail Classes

As normal create a new mail with :-
We've currently opted to keep using a separate Mailable Class for each email type. This means when you create a new template in the admin, it will require a new php Class.
The package provides an action to build the class if the file does not exist in app\Mail\VisualBuilder\EmailTemplates.

```php
php artisan make:mail MyFunkyNewEmail
```
![Build Class](./media/BuildClass.png)

Add the **BuildGenericEmail** Trait which saves duplication of code in each mail class keeping the code dry.
Note: I think we could easily implement a GenericMailable class to eliminate the need to create classes for each mail type.

Currently generated Mailable Classes will use the BuildGenericEmail Trait
```php
<?php

Expand Down Expand Up @@ -342,14 +342,15 @@ You should also include the filetype.
'title' => $this->replaceTokens($template->title, $this)
];

return $this->from($template->from, config('app.name'))
return $this->from($template->from['email'],$template->from['name'])
->view($template->view_path)
->subject($this->replaceTokens($template->subject, $this))
->to($this->sendTo)
->with(['data'=>$data]);
}
```

To maximise compatibility we've kept with the L9 mailable methods -> which still work on L10.

### Testing

Expand Down
32 changes: 7 additions & 25 deletions config/email-templates.php → config/filament-email-templates.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,47 +5,32 @@
'table_name' => 'vb_email_templates',
'theme_table_name' => 'vb_email_templates_themes',

//If you want to use your own resource for email templates,
//you can set this to true and use `php artisan email-template:publish` to publish the resource
"publish_resource" => false,

//This is the app directory where generated Classes should be put
"mailable_directory" => 'Mail/Visualbuilder/EmailTemplates',

//Admin Panel Resource Navigation Options
'navigation'=>[
'sort'=>50,
'group'=>'Settings',
],

//Email templates will be copied to resources/views/vendor/vb-email-templates/email
//default.blade.php is base view that can be customised below
'default_view' => 'default',

'template_view_path' => 'vb-email-templates::email',

//Default Email Styling
//Default Logo
'logo' => 'media/email-templates/logo.png',

//Logo size in pixels -> 200 pixels high is plenty big enough.
'logo_width' => '476',
'logo_height' => '117',
'logo_width' => '500',
'logo_height' => '126',

//Content Width in Pixels
'content_width' => '600',

//Background Colours
'header_bg_color' => '#B8B8D1',
'body_bg_color' => '#f4f4f4',
'content_bg_color' => '#FFFFFB',
'footer_bg_color' => '#5B5F97',
'callout_bg_color' => '#B8B8D1',
'button_bg_color' => '#FFC145',

//Text Colours
'body_color' => '#333333',
'callout_color' => '#000000',
'button_color' => '#2A2A11',
'anchor_color' => '#4c05a1',

//Contact details included in default email templates
'customer-services' => ['email' => '[email protected]',
'phone' => '+441273 455702'],
Expand All @@ -57,8 +42,8 @@
],

//Options for alternative languages
//Note that Laravel default locale is just 'en'
//We are being more specific to cater for English vs USA languages
//Note that Laravel default locale is just 'en' you can use this but
//we are being more specific to cater for English vs USA languages
'default_locale' => 'en_GB',

//These will be included in the language picker when editing an email template
Expand All @@ -76,9 +61,6 @@
'\\App\\Models\\User',
],

//Guards who are authorised to edit email templates
'editor_guards' => ['web'],

/**
* Allowed config keys which can be inserted into email templates
* eg use ##config.app.name## in the email template for automatic replacement.
Expand Down
9 changes: 4 additions & 5 deletions database/factories/EmailTemplateFactory.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ class EmailTemplateFactory extends Factory
* @var string
*/
protected $model = EmailTemplate::class;

/**
* Define the model's default state.
*
Expand All @@ -23,12 +23,11 @@ class EmailTemplateFactory extends Factory
public function definition() {
return [
'key' => Str::random(20),
'language' => config('email-templates.default_locale'),
'view' => config('email-templates.default_view'),
'language' => config('filament-email-templates.default_locale'),
'view' => config('filament-email-templates.default_view'),
'cc' => null,
'bcc' => null,
'send_to' => 'user',
'from' => $this->faker->email,
'from' => ['email'=>$this->faker->email,'name'=>$this->faker->name],
'name' => $this->faker->name,
'preheader' => $this->faker->sentence,
'subject' => $this->faker->sentence,
Expand Down
Loading

0 comments on commit 1fe362a

Please sign in to comment.