Added docs v1

codedor · Jun 30, 2023 · 06813aa · 06813aa
1 parent dc1c855
commit 06813aa
Show file tree

Hide file tree

Showing 9 changed files with 164 additions and 79 deletions.
diff --git a/README.md b/README.md
@@ -1,8 +1,6 @@
-# A package to create customizable mail templates in Filament
+# Mail Templates for Filament
 
-## 
-
-This is where your description should go. Limit it to a paragraph or two. Consider adding a small example.
+A package to quickly create customizable mail templates in Filament
 
 ## Installation
 
@@ -12,65 +10,12 @@ You can install the package via composer:
 composer require codedor/filament-mail-templates
 ```
 
-You can publish and run the migrations with:
-
-```bash
-php artisan vendor:publish --tag="filament-mail-templates-migrations"
-php artisan migrate
-```
-
 You can publish the config file with:
 
 ```bash
 php artisan vendor:publish --tag="filament-mail-templates-config"
 ```
 
-This is the contents of the published config file:
-
-```php
-return [
-];
-```
-
-Optionally, you can publish the views using
-
-```bash
-php artisan vendor:publish --tag="filament-mail-templates-views"
-```
-
-## Usage
-
-```php
-$filamentMailTemplates = new Codedor\FilamentMailTemplates();
-echo $filamentMailTemplates->echoPhrase('Hello, Codedor!');
-```
-
 ## Documentation
 
 For the full documentation, check [here](./docs/index.md).
-
-## Testing
-
-```bash
-vendor/bin/pest
-```
-
-## Changelog
-
-Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
-
-## Upgrading
-
-Please see [UPGRADING](UPGRADING.md) for more information on how to upgrade to a new version.
-
-## Contributing
-
-Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
-
-## Security Vulnerabilities
-
-If you discover any security-related issues, please email [email protected] instead of using the issue tracker.
-
-## License
-
-The MIT License (MIT). Please see [License File](LICENSE.md) for more information.
diff --git a/docs/index.md b/docs/index.md
@@ -1,5 +1,144 @@
-# A package to create customizable mail templates in Filament
+# Mail Templates for Filament
 
-## Introduction
+A package to quickly create customizable mail templates in Filament
 
 ## Installation
+
+You can install the package via composer:
+
+```bash
+composer require codedor/filament-mail-templates
+```
+
+## Defining Mail Templates
+
+When adding mail templates there are a few things to do, first you'll need to add the `Codedor\FilamentMailTemplates\Models\Traits\HasMails` trait models that you want to have mail templates.
+
+```php
+namespace App\Models;
+
+use Codedor\FilamentMailTemplates\Models\Traits\HasMails;
+use Illuminate\Database\Eloquent\Model;
+
+class Inquiry extends Model
+{
+    use HasMails;
+}
+```
+
+After doing this, you'll also need to define what fields you want to be able to use in the mail template. To do this you'll need to define the fields in the `getMailVariables` method.
+
+The keys in this array will be the variables that show up in the mail template as labels, and the values will be the values that will be used in the mail template, when sent.
+
+```php
+namespace App\Models;
+
+use Codedor\FilamentMailTemplates\Models\Traits\HasMails;
+use Illuminate\Database\Eloquent\Model;
+
+class Inquiry extends Model
+{
+    use HasMails;
+
+    public function getMailVariables(): array
+    {
+        return [
+            'first name' => $this->first_name,
+            'last name' => $this->last_name,
+            'e-mail' => $this->email,
+            'message body' => $this->message,
+            'inquiry type' => $this->inquiryType?->working_title,
+        ];
+    }
+
+    public function inquiryType()
+    {
+        return $this->belongsTo(InquiryType::class);
+    }
+}
+```
+
+Lastly, you need to define the actual mail template. To do this you'll need to add the following to any Provider in your project:
+
+```php
+use App\Models;
+use Illuminate\Support\ServiceProvider;
+
+class AppServiceProvider extends ServiceProvider
+{
+    public function boot(): void
+    {
+        Models\Inquiry::registerMail('inquiry-admin')
+            ->description('Send an email to the admin when a new inquiry is made');
+
+        Models\Inquiry::registerMail('inquiry-user')
+            ->view('mail.inquiry-new')
+            ->description('Send an email to the user when a new inquiry is made');
+    }
+}
+```
+
+The `registerMail` method takes a string as the first argument, this is the name/identifier of the mail template and should be kebabcase. A description can be given as well, this is optional but will provide the admin additional information about the mail template in the Filament resource.
+
+## Saving the Mail Templates
+
+When you are done defining your templates, run the following command:
+
+```bash
+php artisan filament-mail-templates:create
+```
+
+This will loop over all your defined mail templates and create them in the database. It is recommended that you add this command in your deployment process, so that the mail templates are always up to date.
+
+## Sending Mail Templates from the front-end
+
+After filling in all data in the CMS, you can get the mail object in the front-end by using the `mail` method of the model. For example, this contact form:
+
+```php
+class ContactForm extends Component
+{
+    public array $fields = [];
+
+    public function submit()
+    {
+        $this->validate();
+
+        /** @var Inquiry $inquiry */
+        $inquiry = Inquiry::create($this->fields);
+
+        Mail::send($inquiry->mail('inquiry-admin')->to($inquiry->inquiryType?->to_email));
+        Mail::send($inquiry->mail('inquiry-user')->to($inquiry->email));
+    }
+}
+```
+
+This example will send a mail to the admin and the user.
+
+The `mail` method returns a Laravel Mailable object, so you can use all the methods that are available on that object.
+
+## Customizing Mail Templates
+
+The config file comes with the following:
+
+```php
+return [
+    'default' => [
+        'view' => 'filament-mail-templates::mail.template',
+        'to_email' => null,
+    ],
+    'navigation' => [
+        'templates' => [
+            'icon' => 'heroicon-o-inbox',
+            'group' => 'Mails',
+            'shown' => true,
+        ],
+        'history' => [
+            'icon' => 'heroicon-o-mail',
+            'group' => 'Mails',
+            'shown' => true,
+        ],
+    ],
+];
+```
+
+Here you can define some default values and customize the navigation icon/groups of the resources. The `shown` key can be used to hide the resource from the navigation completely.
diff --git a/src/Console/Commands/CreateMailTemplates.php b/src/Console/Commands/CreateMailTemplates.php
@@ -4,7 +4,7 @@
 
 use Codedor\FilamentMailTemplates\Facades\MailTemplateCollection;
 use Codedor\FilamentMailTemplates\Models\MailTemplate;
-use Codedor\FilamentMailTemplates\RegisteringMailTemplate;
+use Codedor\FilamentMailTemplates\MailTemplateBuilder;
 use Illuminate\Console\Command;
 
 class CreateMailTemplates extends Command
@@ -15,9 +15,9 @@ class CreateMailTemplates extends Command
 
     public function handle(): void
     {
-        MailTemplateCollection::each(function (RegisteringMailTemplate $template) {
+        MailTemplateCollection::each(function (MailTemplateBuilder $builder) {
             MailTemplate::updateOrCreate([
-                'identifier' => $template->getIdentifier(),
+                'identifier' => $builder->getIdentifier(),
             ]);
         });
     }

diff --git a/src/Filament/MailTemplateResource.php b/src/Filament/MailTemplateResource.php
@@ -63,6 +63,7 @@ public static function form(Form $form): Form
                         ->content(fn (Model $record) => $record->description),
 
                     Repeater::make('to_email')
+                        ->helperText('If left empty, the sites default e-mail will be used.')
                         ->label('Target e-mails')
                         ->schema([
                             Grid::make()->schema([

diff --git a/src/Mail/MailableTemplate.php b/src/Mail/MailableTemplate.php
@@ -4,7 +4,7 @@
 
 use Codedor\FilamentMailTemplates\Models\MailHistory;
 use Codedor\FilamentMailTemplates\Models\MailTemplate;
-use Codedor\FilamentMailTemplates\RegisteringMailTemplate;
+use Codedor\FilamentMailTemplates\MailTemplateBuilder;
 use Illuminate\Bus\Queueable;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Mail\Mailable;
@@ -21,12 +21,12 @@ class MailableTemplate extends Mailable
     public MailTemplate $template;
 
     public function __construct(
-        public RegisteringMailTemplate $registeredTemplate,
+        public MailTemplateBuilder $builder,
         public Model $item,
         string $locale,
         public bool $isPreview = false,
     ) {
-        $this->template = $registeredTemplate->getTemplateModel();
+        $this->template = $builder->getTemplateModel();
         $this->locale($locale);
     }
 
@@ -53,7 +53,7 @@ public function content(): Content
         $body = nl2br($this->parseVariables($this->template->body));
 
         return new Content(
-            view: $this->registeredTemplate->getView(),
+            view: $this->builder->getView(),
             with: [
                 'item' => $this->item,
                 'body' => new HtmlString($body),

diff --git a/src/RegisteringMailTemplate.php → src/MailTemplateBuilder.php b/src/RegisteringMailTemplate.php → src/MailTemplateBuilder.php
@@ -5,7 +5,7 @@
 use Codedor\FilamentMailTemplates\Mail\MailableTemplate;
 use Codedor\FilamentMailTemplates\Models\MailTemplate;
 
-class RegisteringMailTemplate
+class MailTemplateBuilder
 {
     public null|string $locale = null;
 

diff --git a/src/MailTemplateCollection.php b/src/MailTemplateCollection.php
@@ -6,15 +6,15 @@
 
 class MailTemplateCollection extends Collection
 {
-    public function addTemplate(RegisteringMailTemplate $template): self
+    public function addTemplate(MailTemplateBuilder $builder): self
     {
-        return $this->add($template);
+        return $this->add($builder);
     }
 
-    public function getTemplate(string $identifier): RegisteringMailTemplate
+    public function getTemplate(string $identifier): MailTemplateBuilder
     {
-        return $this->first(function (RegisteringMailTemplate $template) use ($identifier) {
-            return $template->getIdentifier() === $identifier;
+        return $this->first(function (MailTemplateBuilder $builder) use ($identifier) {
+            return $builder->getIdentifier() === $identifier;
         });
     }
 }
diff --git a/src/Models/MailTemplate.php b/src/Models/MailTemplate.php
@@ -3,7 +3,7 @@
 namespace Codedor\FilamentMailTemplates\Models;
 
 use Codedor\FilamentMailTemplates\Facades\MailTemplateCollection;
-use Codedor\FilamentMailTemplates\RegisteringMailTemplate;
+use Codedor\FilamentMailTemplates\MailTemplateBuilder;
 use Illuminate\Database\Eloquent\Model;
 use Illuminate\Support\Collection;
 use Spatie\Translatable\HasTranslations;
@@ -32,7 +32,7 @@ class MailTemplate extends Model
         'to_email' => 'array',
     ];
 
-    public function getMailTemplate(): RegisteringMailTemplate
+    public function getMailTemplate(): MailTemplateBuilder
     {
         return MailTemplateCollection::getTemplate($this->identifier);
     }

diff --git a/src/Models/Traits/HasMails.php b/src/Models/Traits/HasMails.php
@@ -4,7 +4,7 @@
 
 use Codedor\FilamentMailTemplates\Facades\MailTemplateCollection;
 use Codedor\FilamentMailTemplates\Mail\MailableTemplate;
-use Codedor\FilamentMailTemplates\RegisteringMailTemplate;
+use Codedor\FilamentMailTemplates\MailTemplateBuilder;
 
 trait HasMails
 {
@@ -20,13 +20,13 @@ public function mail(string $identifier, null|string $locale = null): MailableTe
         return new MailableTemplate($template, $this, $locale);
     }
 
-    public static function registerMail($identifier): RegisteringMailTemplate
+    public static function registerMail($identifier): MailTemplateBuilder
     {
-        $template = RegisteringMailTemplate::make($identifier, self::class);
+        $builder = MailTemplateBuilder::make($identifier, self::class);
 
-        MailTemplateCollection::addTemplate($template);
+        MailTemplateCollection::addTemplate($builder);
 
-        return $template;
+        return $builder;
     }
 
     public function getMailVariables(): array