Introducing Razor Smart Mailer

• Download source - 13.8 MB

Introduction

RazorSmartMailer is simply the most complete VB.NET Class Library for sending email via web forms available. RazorSmartMailer supports advanced HTML email templating using HttpWebRequest. Any web connected document, even an executable, can be used as a template because the HttpWebRequest method retrieves the rendered document. RazorSmartMailer supports advanced email messaging with support for Helpers.WebMail and System.NET.Mail. Attachment upload and embed, embed linked resources, and image processing including resize, crop, watermark, and add text are built into RazorSmartMailer. RazorSmartMailer includes advanced file renaming options to handle file name conflicts. Conflicting files can be deleted or uploaded files can be renamed using sequential numeric suffixes. RazorSmartMailer also supports inline CSS via the PreMailer.Net assembly and ReCAPTCHA via the ReCAPTCHANet class. Razor Smart Mailer is the complete email solution.

And wait, there's more. The download includes string manipulation via the StringExtensions class, Record Set paging via the RecordSetPaging class, Record ID encoding via the ApplicationSecurity class, and URL rewriting via the RewriteURLs class. There's also support for file uploads and imaging without sending an email which can be used anywhere you need it. The *.vbhtml files included demonstrate usage of all these classes. More information on using the classes included in the download is avaible at my repository https://github.com/wwwebconcepts.

RazorSmartMailer in its compiled form can also be used in C# applications, though the scope of this article doesn’t include C#.

Using the Code

RazorSmartMailer has a number of dependencies and many methods. More information on using the classes included in the download is avaible at my repository https://github.com/wwwebconcepts.

Dependencies

RazorSmartMailer requires the System.Web.Helpers and PreMailer assemblies. Property PreMailerCss set True moves Css inline via Premailer.Net. The image processing features implement the Web.Helpers.WebImage class.

Order of Imaging Operations

Resize, Crop, AddWaterMark, AddCaption. Resize creates a list for the remaining methods. RazorSmartMailer supports multiple operations on images in the order given.

Construct RazorSmartMailer Instance

Using RazorSmartMailer is very straightforward. True, there are many properties the user can define, but only a few the user must define. Most have default values you're unlikely to change.

To send an HTML templated email using the simplest method, use the WebMail helper. The following code block shows you how (assumes WebMail SMTP server properties are configured in the _AppStart.vbhtml file as shown in the sample code):

  Dim theMailer As New RazorSmartMailer
  With theMailer
      .MailTemplatePath = "~/Mail_Templates/contact_template.vbhtml?your passed values"
      .SuccessRedirect = "~/thanks.vbhtml?your passed values"
      'RazorSmartMailer sendmail properties
      .EmailFrom = "web@razorsmartmailer.com" '
      .EmailRecipient = "user@razorsmartmailer.com"
      .EMailSubject = "RazorSmartMailer is the great new email solution!"
      SendWebMail()
End With

Usage: Configure Properties

The RazorSmartMailer class has a number of properties you will need to set. Below are the properties and default settings as well as input formats.

  'RazorSmartMailer calling code
  Dim theMailer As New RazorSmartMailer
  With theMailer
     'RazorSmartMailer templater properties
     .AppInstallFolder = "" ' Only if the application is not in the
                                      ' website root do you need to supply the folderpath.
     .MailTemplatePath = "" ' Path to email body template. May be an executable
                                      ' any page available via http in any coding language.
     .SuccessRedirect = ""  ' Path to form confirmation "Thanks" page.
     .PreMailerCss = False ' To Move CSS styles inline with Premailer.Net set True.
     .AddHTMLBasePath = False '  When True writes base path into the html document
                              ' <head>, the quickest way to fix relative links.
     .ParsePaths = False ' Parse HTML with regular expression and make relative links absolute.

     'SMTP Server properites for System.Net.Mail
     .SmtpUsername =""
     .SmtpPassword =""
     .SmtpHost =""
     .SmtpEnableSsl = False
     .SmtpPort = 25

     'RazorSmartMailer sendmail properties
     .EmailFrom = "" ' SendSystemMail(): From as string in format
                               ' "emailaddress, name" or "emailaddress".
     .EmailRecipient = "" ' SendSystemMail(): Multiple recipient lists are strings
                                    ' in format "emailaddress, name | emailaddress,
                                    ' name" or "emailaddress | emailaddress".
                                    ' Single addresses use the same format as From.
                                    ' The closing "|" may be omitted.
     .EmailCC = "" ' SendSystemMail(): Multiple recipient lists are strings in format
                             ' "emailaddress, name | emailaddress, name" or "emailaddress |
                             ' emailaddress". Single addresses use the same format as From.
                             ' The closing "|" may be omitted.
     .EmailBC = "" ' SendSystemMail(): Multiple recipient lists are strings in
                             ' format "emailaddress, name | emailaddress, name"
                             ' or "emailaddress | emailaddress".
                             ' Single addresses use the same format as From.
                             ' The closing "|" may be omitted.
     .EmailReplyTo = "" ' SendSystemMail(): Multiple recipient lists are strings
                                  ' in format "emailaddress, name | emailaddress, name"
                                  ' or "emailaddress | emailaddress". Single addresses
                                  ' use the same format as From. The closing "|" may be omitted.
     .EMailEncoding = "utf-8"
     .EMailSubject = "Razor Smart Mailer Is the eMail Solution"
     .IsBodyHtml = True
     .EmailPriority = "Normal"
     .AdditionalHeaders = Nothing ' Takes a List(Of String)
     .AttachmentFolder = "SmartMailerAttachments"
     .SaveAttachments = True
     .SendWebMail() ' Set WebMail SMTP properties in _AppStart. Supports attachments.
                    ' Does not support embedded images.

     'System.Net.Mail Send Properties
     .SystemMailHeaders = Nothing 'Takes a NameValueCollection
     .SystemMailEncoding = Encoding.UTF8
     .EmbedAttachments = False
     .EmbedAllowExtensions = ".jpg, .jpeg, .gif, .png, .ico" ' These are the
                                      default allowed extensions for embedded attachments.
     .ImagesToEmbed = "" ' String Format:  "image.gif,
                                   ' image.jpg, image.jpeg, image.ico, image.png"
     .SendSystemMail() ' Send mail message using System.Net.Mail.

  'Resize
   .ImageSizes = "" ' String Format:  "width, height, suffix | width,
                              ' height, suffix |". ' Resize only works if sizes defined.
   .PreventEnlarge = True
   .PreserveAspectRatio = True

   'Crop
   .CropSizes = "" ' String Format:  "width, height | width, height".
                             ' *Must match resize order. Crop only works
                             ' if sizes defined in Resize and Crop.
   .CropPosition = "center-middle"


    'Watermark
    .WatermarkMask = "" ' Add path to watermark mask to enable watermarks.
    .WatermarkPadding = 10
    .WatermarkOpacity = 50
    .WatermarkSizes = "128, 128" ' Accepts multiple sizes in string format: width,
                                 ' height | width, height |"
    .WatermarkAlign = "Center-Middle"

    'Captions
    .CaptionText = "" ' Add text to enable captions.
    .CaptionFont = "Ariel"
    .CaptionFontSizes = "16" Takes multiple arguments in comma separated string format: "16, 14, 12"
    .CaptionFontColor = "Black"
    .CaptionFontStyle =  "Bold" Valid values are: "Regular", "Bold",
                         "Italic", "Underline", and "Strikeout".
    .CaptionOpacity = 100
    .CaptionPadding = 10
    .CaptionAlign = "Center-Middle"
     'Uploader
    .UploadFolder = "SmartMailerUploads"
    .ProcessUploads() ' Constructs file upload and imaging without an email message.
End With

Usage: Configure ReCAPTCHA

The Razor Smart Mailer includes a ReCAPTCHANet class to validate your users. The VB.NET RecaptchaNet class provides simple Google Recaptcha implementation using either the robots or classic Recaptcha interface.

See Contact.vbhtml for usage example.

GetControl() function call creates the robots style Google recaptcha control.

GetControl(theme, language) function call creates the classic style Google recaptcha control.

    ' 
'ReCAPTCHANet sample calling code
Dim theCAPTCHA As New ReCAPTCHANet
With theCAPTCHA
  .PrivateKey = "" & ReCAPTCHAPrivateKey & ""
  .PublicKey = "" & ReCAPTCHAPublicKey & ""
  .QueryParameter = "querystring parameter when using redirect. default is Recaptcha="
  .RedirectURL = "redirect to on success"
  .FailURL = "redirect to on fail"
  Construct() ' Returns validation as boolean
End With

ReCAPTCHANet class can be used to secure a form or as gateway page to other content.

Displaying Images with RazorSmartMailer

RazorSmartMailer returns five List(of String) you can use to display data in your email template or on your pages:

• ImageArray
• UploadedFiles
• EmailAttachments
• EmbeddedImages
• EmbeddedAttachments

The first three lists return the full system path to the named file collection. The Embedded lists contain the content IDs of the embedded files:

1. "ImageArray" returns only images that have been resized. All images must pass through the resize method to be added to the list p_imageArray. This Private Shared List(of String) contains the system filepath to the images for processing created by the ResizeImages() method. It is used by the remaining image processing methods: CropImages(), AddWaterMark(), and AddTextCaption() methods and returned as "ImageArray."
2. "UploadedFiles" returns the list of files uploaded.
3. "EmailAttachments" returns the list of attachments including any image varients created by resize.
4. "EmbeddedImages" returns the list of linked resource embedded images. (These are the images used in your email template and embdedded in the email message rather than linked to a file on the Internet.)
5. "EmbeddedAttachments" returns the list of attachments embedded in the email body, including any image variants from imaging.

RazorSmartMailer has one more List(of WebException): "ErrorCodes". This list returns any application errors.

Imaging with RazorSmartMailer

Below are the imaging properties. These properties are used with the email utility and the file upload utility. All images follow the same path through the methods: Resize, Crop, AddWaterMark, AddCaption.

Resize is the first image processing executed. It creates the ImageArray list of paths which all the succeeding imaging methods use. We recommend the order from the largest to smallest, always saving any changes to original uploaded image for last.

Each set of Resize instructions has three elements, width, height, suffix. The two size elements are followed by a comma and each set is closed with a "|". To save an image with the original file name, leave the suffix element blank. You can also omit the closing "|" at the end of your string as the application will add it if not present.

Let's deconstruct this input string:

"525, 525, large | 175, 175, thumb | 325, 325, "

It makes three images, the first is 525 x 525 and is saved with the suffix "_large"; the second image is 175 x 175 and is saved with the suffix "_thumb"; the last image is 325 x 325 and is saved with the original file name. If you always save using the same file name at the end of the string, then image varients are made from the original uploaded image file. This prevents image degradation due to being  resized and saved several times over. Always leave save as same file name arguments in the last set of arguments in the string.

Why suffix naming? It provides a consistent method for naming generated images so one can easily display them. And it keeps all the images from an original source image together in alphabetized groups in file explorers.

  With theMailer
      'Resize
      .ImageSizes = "width, height, _
                    suffix | width, height, suffix |" ' Resize only works if size defined.
      .PreventEnlarge = True
      .PreserveAspectRatio = True

     Crop
      .CropSizes = "width, height | width, height" *Must match resize order. Crop only works if sizes defined in Resize and Crop.
      .CropPosition = "Center-Middle"

       'Watermark
       .WatermarkMask = ""  Add path to a Watermark mask to enable watermarks.
       .WatermarkPadding = 10
       .WatermarkOpacity = 50
       .WatermarkSizes = "128, 128"
       .WatermarkAlign = "Center-Middle"

       'Captions
       .CaptionText = "" Add text to enable captions.
       .CaptionFont = "Ariel"
       .CaptionFontSizes = "16"
    .CaptionFontColor = "Black"
     .CaptionFontStyle =  "Regular" ' Valid values are: "Regular", "Bold", _
                          "Italic", "Underline", and "Strikeout".
     .CaptionOpacity = 100
     .CaptionPadding = 10
     .CaptionAlign = "Center-Middle"
End With

When using the upload utility, configure any imaging properties you need and call ProcessUploads().

With theMailer
    ' Freestanding File Upload & Imaging
    ProcessUploads() ' Constructs file upload and imaging without an email message.
End With

Options

Crop, Watermark, and Caption methods all use the same 9 point location scheme. It is comprised of 3 horizontal and 3 vertical positions resulting in 9 permutations.

• Horizontal positions: Left Center Right
• Vertical positions: Top Middle Bottom

Combine the horizontal and vertical choices in any of the 9 possible combinations to select position. The required format is: horizontal-vertical.

Contributors

• James Threadgill

License

RazorSmartMailer is available under the MIT license. See the LICENSE file for more information.