How we use markdown in Laravel Mailables

Scaffolding the front end series

Created on: July 31, 2017

Updated on: April 25, 2018

Written by Sehinde Raji

Laravel 5.4 was released in the first month of this year. This release has a number of incremental updates.

Since, I am a seasoned full stack developer, I got stuck in to learning the new features that this release has brought.

Creating a new brand does have its own challenges and one particular challenge I wanted to resolve was how do you amend the look and feel of the emails that you send out after a customer has successfully purchased a digital download on the e-commerce site (gamesstation) I built earlier on in the year.

Thankfully, I realised that the latest release of Laravel has the ability to change the css of a mailable.

What is markdown?

If you don't already know markdown is a text to html conversion tool for web writers. It allows web writers to not get bogged down with the small imprecisions that occur whilst you copy and paste code from MS Word to Html, eliminating the cumbersome structural elements that interfere with the overall look and feel of your html document.

Our goal

We will investigate how you can amend an existing mailable to incorporate the structural and style changes to improve the look and feel of your app.

Current state

My e-commerce application is set up to send an email after a user has purchased a digital games key using stripe. The digital download is a mailable and these are classes that are an easier and more readable way to send and receive emails. In my case I created a mailable class and this is shown in the snippet listed below:

app/mail/digitaldownload.php

    class DigitalDownload extends Mailable implements ShouldQueue
        {
        use Queueable, SerializesModels;
        /**
        * @var Order
        * /
        protected $order
        /**
        * Create a new message instance
        * @param Order $order
        * /
        public function __construct(Order $order) 
        {
            $this->order = $order;
        }

        /**
        * Build the message.
        * @return $this
        * /
            public function build() 
            {
            return $this->view('emails.download')
                       ->from('[email protected])
                      ->subject('Your key download instructions')
                      ->with([
                        'orderName'=>$this->order->billing_name,
                        'orderNumber'=>$this->order_number,
                        'orderEmail'=>$this->order->email,
                        'orderURL'=>$this->order->onetimeurl
                                                            ]);
         }}

We will now assume that you have successfully upgraded your application from Laravel 5.3 or below to Laravel 5.4.

We will amend the build method by replacing the this view with this markdown as detailed within the snippet below:

    return $this->view('emails.download')

    to

    return $this->markdown('emails.download')

This means that we can now use markdown to alter the look and feel of the email.

We will amend the download template to reflect the new components that we can use with markdown:

download.blade.php
@component('mail::message')
   <p> Hi {{ $orderName }} </p>
    <p> Your order number is {{ $orderNumber }} </p>
    <p>We would like to thank you for your purchase today.</p>
        <p> Please click on the link below to download your purchase</p>
@component('mail::panel')
    The information contained in this website is for general information purposes only. The information is provided by Gamesstation, while we endeavour to keep the information up to date and correct, we make no representations or warranties of any kind. Any reliance you place on such information is strictly at your own risk.
@endcomponent
   Thanks </br> {{ config('app.name') }}
@endcomponent

<br>

Template changes

Firstly, notice that there is a component called mail message this is where you would typically place the contents of the email message such as the order name order number and the link to the digital purchase.

Next, we have a panel. This is where you would place any website disclaimer or descriptions.

We tend to keep a corporate feel to our email by fetching the application name off the name section within our config/app.php file. This is placed just before the end of the component.

Here is the fun part we can customise the overall look and feel by publishing the tags.

At the command prompt type:

php artisan vendor:publish

This command publishes all of your blade templates in to a series of directories.

Go to resources/ vendor /mail /html / all of your email blade templates.

Email Styling

Take a look at the themes folder and notice that there is a file called default.css

This is the default styles that are applied to your email template.

Front end developers and full stack developers will be well versed in css and they can easily amend the styles to create the corporate feel to your email templates.

To create your own styles rename the default.css to something else (in my case I renamed it to games.css).

Please check out the code below:

vendor/mail/html/themes/games.css

.header {
    padding: 25px 0;
     
text-align: center;
     background-color: #003434;
    }
    
 .header a {
     color: #f9f1dc;
     font-size: 19px;
     font-weight: bold;
     text-decoration: none;
     text-shadow: 0 1px 0 white;
    }

/* Body */

.body
{
     background-color: #FFFFFF;
     border-bottom: 1px solid #EDEFF2;
     border-top: 1px solid #EDEFF2;
     margin: 0; padding: 0;
     width: 100%;
     -premailer-cellpadding: 0;
     -premailer-cellspacing: 0;
     -premailer-width: 100%;
    }

Activate your new theme

Go to config/mail.php and at the bottom of the page where it says markdown settings change the theme from default to games.css.

Markdown Mail

Or alternatively you can use markdown mail to carefully craft your own css theme.

Markdown Mail