Overview

Many business websites show their email addresses and phone numbers so their customers can contact them. In this lesson we will create wrapper classes around ‘mailto’ and ‘tel’ HTML links. Those classes will allow you to read and generate those links with ease.

Introduction

If you need an introduction to mailto and tel links please check this and this.

Base

To avoid duplication, we will start by laying out our base class.
  1. public abstract class WebLink {
  2. /// <summary>
  3. /// Link prefix. Examples are: 'mailto:' and 'tel:'
  4. /// </summary>
  5. public abstract string Prefix { get; }
  7. /// <summary>
  8. /// Clears instance fields.
  9. /// </summary>
  10. public abstract void ClearFields();
  12. /// <summary>
  13. /// Loads link input into relevant fields.
  14. /// </summary>
  15. public virtual void ReadLink(string link) {
  16. if (link == null)
  17. throw new ArgumentNullException("link");
  19. if (link.ToLower().StartsWith(Prefix.ToLower()) == false)
  20. throw new FormatException("Invalid link.");
  21. }
  23. /// <summary>
  24. /// Generates link from instance fields.
  25. /// </summary>
  26. public virtual string GenerateLink(bool includePrefix) {
  27. var str = string.Empty;
  29. if (includePrefix)
  30. str += Prefix;
  32. return str;
  33. }
  35. /// <summary>
  36. /// Can be used to exclude prefix from a link string.
  37. /// </summary>
  38. protected string ExcludePrefix(string link) {
  39. link = link.Trim();
  40. if (link.ToLower().StartsWith(Prefix.ToLower()))
  41. link = link.Substring(Prefix.Length).Trim();
  42. return link;
  43. }
  45. public override string ToString() {
  46. return GenerateLink(true);
  47. }
  48. }
The code is self-explanatory. Every child class will have to fill its link prefix, add some code to clear its fields, and some other code to read and write links.

mailto

Now we are going to inherit from the base class to create the mailto handler,
  1. public class MailWebLink : WebLink {
  2. #region Prefix
  3. protected static string LinkPrefix { get { return "mailto:"; } }
  4. public override string Prefix => LinkPrefix;
  5. #endregion
  7. #region Delimiters
  8. protected static readonly char[] MailDelimiters = new char[] { '?' };
  9. protected static readonly char[] RecipientDelimiters = new char[] { ',', ';' };
  10. protected static readonly char[] ParamDelimiters = new char[] { '&' };
  11. protected static readonly char[] ParamValueDelimiters = new char[] { '=' };
  12. #endregion
  14. #region Field Names
  15. protected static readonly string ToField = "to";
  16. protected static readonly string CcField = "cc";
  17. protected static readonly string BccField = "bcc";
  18. protected static readonly string SubjectField = "subject";
  19. protected static readonly string BodyField = "body";
  20. #endregion
  23. #region Fields
  24. public string[] To { get; set; }
  25. public string[] Cc { get; set; }
  26. public string[] Bcc { get; set; }
  27. public string Subject { get; set; }
  28. public string Body { get; set; }
  29. #endregion
  31. public MailWebLink() {
  33. }
  34. public MailWebLink(string link) {
  35. ReadLink(link);
  36. }
  38. public static bool CanHandle(string link) {
  39. return link.ToLower().Trim().StartsWith(LinkPrefix);
  40. }
  42. #region Link Loading
  43. public override void ClearFields() {
  44. To = Cc = Bcc = null;
  45. Subject = Body = null;
  46. }
  48. public override void ReadLink(string link) {
  49. base.ReadLink(link);
  51. try {
  52. ClearFields();
  54. // Exclude prefix if necessary
  55. link = ExcludePrefix(link);
  57. // Get mail 'To' Field
  58. string tmpVal = null;
  59. int idx = -1;
  61. idx = link.IndexOfAny(MailDelimiters);
  63. if (idx > -1)
  64. tmpVal = link.Substring(0, idx);
  65. else
  66. tmpVal = link;
  68. this.To = LoadRecipients(tmpVal).ToArray();
  70. if (idx == -1)
  71. return;
  73. link = link.Substring(idx + 1);
  75. // Handle rest of fields
  76. var parameters = GetParameters(link, true);
  77. foreach (var par in parameters) {
  78. if (par.Key == ToField) // overrides the above code
  79. this.To = LoadRecipients(par.Value).ToArray();
  80. else if (par.Key == CcField)
  81. this.Cc = LoadRecipients(par.Value).ToArray();
  82. else if (par.Key == BccField)
  83. this.Bcc = LoadRecipients(par.Value).ToArray();
  84. else if (par.Key == SubjectField)
  85. this.Subject = par.Value;
  86. else if (par.Key == BodyField)
  87. this.Body = par.Value;
  88. }
  89. } catch {
  90. throw new FormatException();
  91. }
  92. }
  94. /// <summary>
  95. /// Splits a mail string into a list of mail addresses.
  96. /// </summary>
  97. protected virtual IEnumerable<string> LoadRecipients(string val) {
  98. var items = val.Split(RecipientDelimiters, StringSplitOptions.RemoveEmptyEntries);
  99. return items.Select(s => s.Trim().ToLower()).Distinct();
  100. }
  102. /// <summary>
  103. /// Splits a parameter string into a list of parameters (kay and value)
  104. /// </summary>
  105. /// <param name="skipEmpty">Whether to skip empty parameters.</param>
  106. protected virtual IEnumerable<KeyValuePair<string, string>> GetParameters(string val, bool skipEmpty = true) {
  107. var items = val.Split(ParamDelimiters, StringSplitOptions.RemoveEmptyEntries);
  109. foreach (var itm in items) {
  110. string key = string.Empty;
  111. string value = string.Empty;
  113. var delimiterIdx = itm.IndexOfAny(ParamValueDelimiters);
  114. if (delimiterIdx == -1)
  115. continue;
  117. key = itm.Substring(0, delimiterIdx).ToLower();
  118. value = itm.Substring(delimiterIdx + 1);
  119. value = UnscapeParamValue(value);
  121. if (key.Length == 0)
  122. continue;
  124. if (skipEmpty && value.Length == 0)
  125. continue;
  127. yield return new KeyValuePair<string, string>(key, value);
  128. }
  129. }
  130. #endregion
  132. #region Link Generation
  134. public virtual string GetLink() { return GenerateLink(true); }
  136. public override string GenerateLink(bool includePrefix) {
  137. string str = base.GenerateLink(includePrefix);
  139. if (this.To != null && this.To.Length > 0) {
  140. str += GetRecipientString(this.To);
  141. }
  143. str += MailDelimiters.First();
  145. if (this.Cc != null && this.Cc.Length > 0) {
  146. str += GetParameterString(CcField, GetRecipientString(this.Cc), false);
  147. str += ParamDelimiters.First();
  148. }
  150. if (this.Bcc != null && this.Bcc.Length > 0) {
  151. str += GetParameterString(BccField, GetRecipientString(this.Bcc), false);
  152. str += ParamDelimiters.First();
  153. }
  155. if (this.Subject != null && this.Subject.Length > 0) {
  156. str += GetParameterString(SubjectField, this.Subject, true);
  157. str += ParamDelimiters.First();
  158. }
  160. if (this.Body != null && this.Body.Length > 0) {
  161. str += GetParameterString(BodyField, this.Body, true);
  162. str += ParamDelimiters.First();
  163. }
  165. str = str.TrimEnd(MailDelimiters.Concat(ParamDelimiters).ToArray());
  167. return str;
  168. }
  170. /// <summary>
  171. /// Joins a list of mail addresses into a string
  172. /// </summary>
  173. protected virtual string GetRecipientString(string[] recipients) {
  174. return string.Join(RecipientDelimiters.First().ToString(), recipients);
  175. }
  177. /// <summary>
  178. /// Joins a parameter (key and value) into a string
  179. /// </summary>
  180. /// <param name="escapeValue">Whether to escape value.</param>
  181. protected virtual string GetParameterString(string key, string value, bool escapeValue) {
  182. return string.Format("{0}{1}{2}",
  183. key,
  184. ParamValueDelimiters.First(),
  185. escapeValue ? EscapeParamValue(value) : value);
  186. }
  188. #endregion
  190. #region Helpers
  191. protected static readonly Dictionary<string, string> CustomUnescapeCharacters =
  192. new Dictionary<string, string>() { { "+", " " } };
  194. private static string EscapeParamValue(string value) {
  195. return Uri.EscapeDataString(value);
  196. }
  198. private static string UnscapeParamValue(string value) {
  199. foreach (var customChar in CustomUnescapeCharacters) {
  200. if (value.Contains(customChar.Key))
  201. value = value.Replace(customChar.Key, customChar.Value);
  202. }
  204. return Uri.UnescapeDataString(value);
  205. }
  206. #endregion
  207. }
The code is fairly simple. One thing to note is that Uri.UnescapeDataString cannot convert ‘+’ to a space. That’s why we added a dictionary of custom un-escape characters.
Now here’s a list of input to test back and forth:
  1. mailto:[email protected]
  2. mailto:[email protected]?subject=Important!&body=Hi.
  3. mailto:[email protected][email protected],[email protected],[email protected]&[email protected]
  4. mailto:[email protected][email protected]&[email protected]&subject=The%20subject%20of%20the%20email&body=The%20body%20of%20the%20email

tel

The tel handler is more straightforward than mailto,
  1. public class TelephoneWebLink : WebLink {
  2. #region Prefix
  3. protected static string LinkPrefix { get { return "tel:"; } }
  4. public override string Prefix => LinkPrefix;
  5. #endregion
  7. #region Delimiters
  8. protected static readonly char ExtensionDelimiter = 'p';
  9. #endregion
  11. #region Fields
  12. public string Number { get; set; }
  13. public string Extension { get; set; }
  14. #endregion
  17. public TelephoneWebLink() {
  19. }
  20. public TelephoneWebLink(string link) {
  21. ReadLink(link);
  22. }
  24. public static bool CanHandle(string link) {
  25. return link.ToLower().Trim().StartsWith(LinkPrefix);
  26. }
  28. public override void ClearFields() {
  29. Number = null;
  30. Extension = null;
  31. }
  33. public override void ReadLink(string link) {
  34. base.ReadLink(link);
  36. try {
  37. ClearFields();
  39. // Exclude prefix if necessary
  40. link = ExcludePrefix(link).Trim();
  42. Number = string.Empty;
  43. Extension = string.Empty;
  45. bool foundExtension = false;
  46. int idx = 0;
  47. foreach (var c in link) {
  48. if (idx == 0 && c == '+')
  49. Number += "+";
  50. if (c == ExtensionDelimiter)
  51. foundExtension = true;
  52. else if (char.IsDigit(c)) {
  53. if (foundExtension == false)
  54. Number += c.ToString();
  55. else
  56. Extension += c.ToString();
  57. }
  58. idx++;
  59. }
  61. } catch {
  62. throw new FormatException();
  63. }
  64. }
  66. public override string GenerateLink(bool includePrefix) {
  67. var str = base.GenerateLink(includePrefix);
  69. if (Number != null)
  70. str += Number.ToString();
  72. if (Extension != null && Extension.Length > 0)
  73. str += ExtensionDelimiter.ToString() + Extension;
  75. return str;
  76. }
  77. }
And here’s a list to test:
  1. tel:+20123456789
  2. tel:+20123456789p113

What’s next?

You can use the same mechanism for any other special link. Adrian Ber wrote a very useful blog post about those links. Moreover, in a future post we will see how this mechanism can be integrated into Android WebView to allow your application to respond to mailto and tel links.
Many refactoring patterns and fixes can be applied to the code. Please feel free to comment with your updated code.