MailtoLink Docs

A tag, modifier and api to create mailto links with ease


Arguments / Parameters

Argument Description
email The email.
subject Sets the subject of the mail.
cc Indicates those who are to receive a copy of a message addressed primarily to another (CC is the abbreviation of carbon copy). The list of recipients in copy is visible to all other recipients of the message.
bcc An additional BCC (blind carbon copy) field is available for hidden notification; recipients listed in the BCC field receive a copy of the message, but are not shown on any other recipient's copy (including other BCC recipients).
body Allows you to specify a short content message for the new email.
display The visible text shown instead of the email address
* Any other argument will be used as html attribute

Data format for email, cc and bcc

You can use any email notation an email client would understand, you can even use multiple addresses seperated by comma.

{{ mailto_link email="[email protected]" display="Get in Touch" }}
{{ mailto_link email="Jane Bacon <[email protected]>" display="Get in Touch" }}
{{ mailto_link email="[email protected], [email protected]" display="Get in Touch" }}
{{ mailto_link email="Jane Bacon <[email protected]>, John Bacon <[email protected]>" display="Get in Touch" }}
<a href="mailto:[email protected]">Get in Touch</a>
<a href="mailto:Jane Bacon <[email protected]>">Get in Touch</a>
<a href="mailto:[email protected], [email protected]">Get in Touch</a>
<a href="mailto:Jane Bacon <[email protected]>, John Bacon <[email protected]>">Get in Touch</a>

Usage

The Tag

Like any other [Tag] you can use variables as parameters. There is also a {{ glide }} like shorthand, so you don't have to set the email parameter explicit.

contact: "[email protected]"
{{ mailto_link :email="contact" }}

<!-- shorthand syntax: -->
{{ mailto_link:contact }}
<a href="mailto:[email protected]">[email protected]</a>

Multiple email addresses

If you have a list of email addresses you can loop over them like you would normaly do.

contacts: 
  - "[email protected]"
  - "[email protected]"

Since the current iteration of the loop would be output using {{ value }}, you can reference that in the tag. This is very much like the glide tags behaves.

{{ contacts }}
  {{ mailto_link :email="value" }}
{{ /contacts }}

<!-- shorthand syntax: -->
{{ contacts }}
  {{ mailto_link:value }}
{{ /contacts }}
<a href="mailto:[email protected]">[email protected]</a>
<a href="mailto:[email protected]">[email protected]</a>

Complex Templates

If you need the email address to be generated with another tag, you can’t just drop that into the email parameter. Instead, use the tag as a tag pair. The contents of the tag will be used as the email parameter.

contact: "[email protected]"
{{ mailto_link }}
  {{ contact }}
{{ /mailto_link }}
<a href="mailto:[email protected]">[email protected]</a>

Specifying details

In addition to the email address, you can provide other information. Supported parameters are subject, cc, bcc and body. Each parameter and its value is specified as a query term.

contact: "[email protected]"
subject: "Interest in Bacon"
cc: "[email protected]"
{{ mailto_link :email="contact" :subject="subject" :cc="cc" }}

<!-- shorthand syntax: -->
{{ mailto_link:contact :subject="subject" :cc="cc" }}
<a href="mailto:[email protected]?subject=Interest in Bacon&[email protected]">[email protected]</a>

If you want to change the text node of the anchor element, you can use the display parameter.

contact: "[email protected]"
{{ mailto_link :email="contact" display="Get in Touch" }}

<!-- shorthand syntax: -->
{{ mailto_link:contact display="Get in Touch" }}
<a href="mailto:[email protected]">Get in Touch</a>

Adding html attributes and classes

Every parameter that is not email, subject, cc, bcc, body, display or href will be added as a html attribute. If you want to add a couple of classes to the anchor element, just add a class parameter.

contact: "[email protected]"
{{ mailto_link :email="contact" class="link email-link" }}

<!-- shorthand syntax: -->
{{ mailto_link:contact class="link email-link" }}
<a href="mailto:[email protected]" class="link email-link">[email protected]</a>

Consuming arrays

When using the short hand syntax, you can add use an array instead of a simple email string.

contact:
  email: "Jane Bacon <[email protected]>"
  cc: "John Bacon <[email protected]>"
  bcc: "Eliah Bacon <[email protected]>"
  subject: "Interest in Bacon"
  body: "Don't forget to add your contact informations :)"
  display: "Get in Touch"
<!-- shorthand syntax: -->
{{ mailto_link:contact class="link email-link" }}
<a href="mailto:Jane Bacon <[email protected]>?cc=John Bacon <[email protected]>&bcc=Eliah Bacon <[email protected]>&subject=Interest in Bacon&body=Don't forget to add your contact informations :)" class="link email-link">Get in Touch</a>

The modifier

The modifier takes the same parameters as the tag. The very basic example looks like this:

contact: "[email protected]"
<!-- shorthand syntax: -->
{{ contact | mailto_link }}
<a href="mailto:[email protected]">[email protected]</a>

Consuming arrays

You can add use an array instead of a simple email string.

contact:
  email: "Jane Bacon <[email protected]>"
  cc: "John Bacon <[email protected]>"
  bcc: "Eliah Bacon <[email protected]>"
  subject: "Interest in Bacon"
  body: "Don't forget to add your contact informations :)"
  display: "Get in Touch"
<!-- shorthand syntax: -->
{{ contact | mailto_link }}
<a href="mailto:Jane Bacon <[email protected]>?cc=John Bacon <[email protected]>&bcc=Eliah Bacon <[email protected]>&subject=Interest in Bacon&body=Don't forget to add your contact informations :)">Get in Touch</a>

The API

In another addon, you may do $this->api('MailtoLink')->create() to get a MailtoLinkModel object.

<?php

/**
 * MailtoLinkModel constructor.
 * 
 * @param array $parameters
 */
$mailto = $this->api('MailtoLink')->create()

/**
 * You can set any parameter like so
 */
$mailto->email = "Jane Bacon <[email protected]>";
$mailto->cc = "John Bacon <[email protected]>";
$mailto->bcc = "Eliah Bacon <[email protected]>";
$mailto->subject = "Interest in Bacon";
$mailto->body = "Don't forget to add your contact informations :)";
$mailto->display = "Get in Touch";

/**
 * Access any parameter
 */

echo $mailto->email;
// Jane Bacon <[email protected]>

/**
 * Output your html
 */
echo $mailto->html();
<a href="mailto:Jane Bacon <[email protected]>?cc=John Bacon <[email protected]>&bcc=Eliah Bacon <[email protected]>&subject=Interest in Bacon&body=Don't forget to add your contact informations :)">Get in Touch</a>

Migrating from Version 1

Except the real new stuff, there are a couple of breaking changes:

  • The tag mailto is renamed to mailto_links to avoid name collisions
  • The shorthand syntax wont take emails anymore
<!-- this won't work anymore -->
{{ mailto_link:[email protected] }}

Tag