It’s been a long time coming, but i’m happy to say that today is the release of version 2.7.0 of the WP Job Manager Emails plugin, which includes a TON of new features, including previewing emails directly from admin area, integration with WP Job Manager Screening Questions plugin, Astoundify’s Private Messages plugin, support for Multipart emails, nested and conditional IF shortcodes, and more! So let’s go ahead and dig right in to it

Preface

While this update contains a ton of new features and bug fixes, I can not stress enough that you should only upgrade when you have time available to test your site, and the emails after upgrading!

A lot of the code base that handled the HTML and plain text formatting had to be refactored (modified), and while doing so I found a handful of minor bugs, and other things along the way that had to be updated.   Things like additional line breaks being added when a shortcode did not have a value (resulting in large spacing between fields), or how shortcode values were pulled directly from meta instead of using a specific callback (when defined).

I have been testing this thoroughly for the past week (as well as a few beta testers), and believe there should not be any issues.  Either way, you should ALWAYS test this yourself, on your own site, after upgrading, to make sure emails are being sent and formatted the way you want/expect.

With that said, let’s go ahead and dig into some of the biggest new features available in this release:

Email Preview

WP Job Manager Emails Generate Preview Email Data

A very highly requested feature that landed in this release, is the ability to generate previews of emails, on the fly, directly from the admin area!  The hardest part about integrating this new feature was the ability to select demo data to use, and then making sure preview works correctly with all the different integrations (Resumes, Applications, Reviews, Claim Listing, Alerts, Private Messages, Screening Questions, etc).

Users who upgrade to version 2.7.0 will notice the button on the top right of the screen that says Preview Email.  When clicking on this you will be prompted with a modal similar to the one on the left, to select example data to use for generating the email preview.  Depending on the hook for the email template, there may be more than one dropdown to select from.

Selecting Demo Data for Preview

You have three options when it comes to selecting demo data to use for the email preview feature.

The first option is to just click the small dropdown icon on the right of the dropdown field, and it will automatically populate the dropdown with 5 random listings for you to choose from.

The second option is to type in a search term in the dropdown box, after the first 3 characters it will automatically start searching all of your available posts  (searching the Post/Listing Title) for your search term.

The third option is to type in id: followed by a post/listing ID, to return a specific post/listing ID (ie id:105)

If you have already searched for a listing and did not find what you want, and want to load random listings, or just need to reset the form, click the Reset button to reset the dropdowns back to their default state.

When you have selected demo data source to use, click on the Preview button to generate the email preview.

Email Previews

WP Job Manager Emails Generate Preview Email

WP Job Manager Emails Generate Preview Email Plaintext

On the preview screen you will see the generated email, based on your selected data source.

If your email is configured as a multipart email (new feature as well, more details below), you will see two tabs, one for the HTML version, and one for the Plain Text version.

If you want to send this generated email to specific email address, you can click on the Send Email button and it will prompt you for an email address to send it to.

Please note that there are some hooks where the data for the email is actually obtained through PHP’s POST from a form, so there is a chance of some data not showing a value in the preview form.

It’s always a good idea to go through your site just like a normal user would, to trigger your emails, to make sure they are formatted and send the way you want/expect.

Multipart Emails

This release also adds a new format type to the email template, called multipart.  Multipart is a format used to send both HTML and Plain Text versions of emails, allowing the user’s email client to select which version to display.  You can enable multipart by selecting it from the format meta box.

Using this format allows the user’s email client to display the email based on their preferences, email client support, etc.  Email clients will only show one version of the email (it will not show HTML and Plain Text), and 95% of the time HTML will be shown, unless the email client does not support it, and then it will show the plain text version.

There is also an option to select the Use custom plain text for multipart which will show a new metabox with a textarea when you check/enable it.  This allows you to specify a custom plaintext version to send with the multipart email (if you want), otherwise a stripped plain text version will be generated from the HTML version.

Shortcodes are supported just like normal in this textarea, and you do not need to use this unless you want a custom plaintext version to be sent.

WordPress and Multipart

The unfortunate thing about Multipart emails is that WordPress does not natively support sending multipart emails.  This is due to a couple things, a lack of people complaining about not having it, and PHPMailer which is the framework used by default in WordPress for sending multipart emails (core trac ticket).   Fortunately enough I was able to find a way to work around this, and force PHPMailer to send emails as multipart when required.

Email Plugins and Multipart

I have not fully tested the multipart handling with different plugins like Mailgun, Sendgrid, etc, but in theory they should work correctly as when I originally designed the multipart email integration, I built the emails generating my own boundaries, which is what is still used when sending an email as multipart … so as long as any plugins you use for sending emails, handle plugging (or filtering) wp_mail correctly, the headers and content should be formatted as required for multipart.  If you have issues with a 3rd party mail plugin (for sending emails, like SendGrid), please open a ticket and let me know.

IF Shortcodes

Included with the 2.7.0 release of this plugin is also a long overdue enhancement to the standard [if] shortcode from earlier releases.  I’ve been working on these features for a while now, and finally worked out the majority of the bugs and issues to be able to include it in this release.

All of the screenshots below are from the Help tab of your site (top right corner) when editing an email template

Attributes/Modifiers

IF shortcode attributes and modifiers

Attributes and modifiers addition to the [if] shortcode now make it possible to combine multiple statements into  one, as well as doing specific comparisons on values with numerous different comparison operators (see below).

You can negate a statement by prepending an exclamation (!) point before the meta key, which basically means “NOT”, using comparisons or any of the other different combinations possible.

You can combine statements together to evaluate that ALL expressions are true, using the AND operator
You can combine statements together to evaluate that ANY expressions are true, using the OR operator

Nested IF Statements

Nested IF Statements

Unfortunately due to the way that WordPress parses shortcodes, it’s not possible to nest a shortcode inside of the same shortcode, and in previous versions you could not create if statements, inside of other if statements.

With this release nested if shortcodes are now available, [if_1][if_2][if_3][if_4][if_5][if_6][if_7][if_8]

So when you need to nest an if statement inside of another one, just increase the number on the shortcode, and you’re good to go!  Please note that your [else] and closing [if] must match the opening [if].  For example, this would be a correct nested [if] shortcode statement:

[if job_location]
    Has a job location!
    [if_2 job_title]
        [job_title]
    [else_2]
        No job title
    [/if_2]
[else]
   No job location, so i'm not showing the title
[/if]

IF Comparison Operators

IF Shortcode Comparison Operators

Comparison operators can be used to customize how the [if] shortcode will determine what to output.  Previous versions did not have this feature, and would only check if there was a value.

Now you can use the new comparison operators to check if a value contains a specific string, if it equals a specific string, starts (or ends) with a string, as well as arithmetic operators such as Less Than, Greater Than, and so on!

These arithmetic operators can also be used on multiple value (and taxonomy) field types to check the number of values in that field (explain more in detail below).

Like all other documentation, you can find examples, and more details in the Help tab while editing an email template.

IF for Taxonomies and Multiple Value fields

IF Shortcode Taxonomies and Multiple Value Field Types

When a field you want to use an [if] shortcode on is a taxonomy or a multiple value field type (multiselect, file, etc), there is an easy way to check for a specific value, or even check all the values.

As mentioned above,  when using an arithmetic operator on these types of fields, it does not check the value itself, but checks the number/amount of values.

When you need to check for a specific value, or check all the values, you can use one of the available comparison operators (such as CONTAINS or EQUALS ), but instead of just entering one value, you can separate each value using a comma , (which is also known as CSV or comma separated values).

Single Post Status Action Hooks

Single Post Status Hooks

A single post status action hook is one that is triggered anytime a listing is added/saved, and matches the single post status hook you selected.  The problem with this is that anytime a listing is saved/updated that hook will be triggered.

This is the reason the majority of hooks available in previous versions, required a specific previous status for the email to be triggered.

Single Post Status Transition Only

In earlier versions there were one or two of these available (mainly publish_POSTTYPE), but with this release you now have access to every single post status, both default and any custom ones you have added.

Along with having these available, there will now also show a warning area describing how single post status hooks work, and a checkbox you can check/enable to set how you want the single post hook to work.

When adding this feature to the plugin, I also rewrote a TON of the codebase for handling post status hooks, and instead of adding an action for each defined hook, we now use the transition post status hook to check the value, and send emails accordingly, which should result in a small speed improvement on your site.

Private Messages Plugin Integration

WP Private Messages Email Customization

This release also includes integration with Astoundify’s Private Messages plugin, adding an entirely separate email section (under the main Private Messages menu) for customizing emails sent when new Private Messages are added.

Initially there is only one hook available for email templates (when a new private message is created), which supports all of the dynamic fields from the plugin, plus a few extra, including attachments, and more.

If there’s a specific shortcode  you would like to see included in the next release of the emails addon (for Private Messages), please open a ticket and let me know and I will look into adding it.

If you have an email template enabled in my plugin, it will automagically prevent the default one from the Private Messages plugin from sending.

WP Job Manager Screening Questions Integration

This release also include integration with the WP Job Manager screening questions addon plugin (free), which you can find on WordPress.org:
https://wordpress.org/plugins/screening-questions-for-wp-job-manager/

The integration with this plugin adds a new shortcode available for use, [screening_questions] in email templates.  Due to the way the values for this plugin are saved (in their own MySQL table), this will output all of the screening questions for a listing.

Final Thoughts

While these new features/updates above are the most requested, there were a lot of other updates and minor bug fixes not mentioned here, which you can find all the details in the full changelog of the plugin.

A lot of these new features have been in the works for a while now, and I hope that you are as excited as I am to now have these available.

Please make sure that you test your site after upgrading to this version, to make sure you do not have any issues, and if you do, please open a support ticket and let me know.