Extended mail action 1.0.0.1, built against Sitecore 5.0.7.3 and NVelocity 0.4.2.8582_Sitecore.

[Sitecore package]
Package now doesn't include NVelocity binaries - they need to be installed separately.

[Source]
Extract in the root of the Sitecore solution.

NVelocity 0.4.2.8582_Sitecore
[Source]

The only difference code wise is the 'if' clause in the constuctor of RecourceLocator class. It makes the recource locator skip the dynamic modules - they don't support GetManifestResourceNames() method

if (a is AssemblyBuilder == false)
{
    String prefix = a.FullName.Substring(0,a.FullName.IndexOf(",")).ToLower();
    String[] names = a.GetManifestResourceNames();
    foreach(String s in names) {
        if (s.ToLower().Equals(fn) || s.ToLower().Equals(prefix + "." + fn)) {
           this.filename = s;
           assembly = a;
           isResource = true;
        }
    }
}

Apart from that, I've excluded the supplementary projects like nAnt tasks from the solution. I wonder if I should merge commons into the nvelocity assembly..

Extended mail action adds a little extra to the standard Sitecore workflow mail notification by using the NVelocity template engine. In case you didn't know, standard Sitecore email action supports three hard-coded macro expansions: $itemPath$, $itemLanguage$ and $itemVersion$. So instead of sending a completely static mail notification saying that something had been changed somewhere you can add something like "Hello. Item $itemPath$ had been changed".

Well, thanks to the NVelocity template engine, extended mail action takes it to the next level! Here's the example message template:

Time: $time

State of the $item.Name item (located at $item.Paths.Path) had been changed from '$state.DisplayName' to '$nextState' by $user.Name ($user.Email).

Item workflow history:
#foreach ($historyItem in $history)
Date: $historyItem.Date | User: $historyItem.User | Action: $historyItem.Text
#end

The item was last updated on $item.Statistics.Updated.

and here's the the result:

Time: 26.09.2005 1:03:25

State of the Extended Mail Item item (located at /sitecore/content/Home/Extended Mail Item) had been changed from 'Editing' to 'Done' by Admin (jc-[at]-sitecore.net).

Item workflow history:
Date: 26.09.2005 1:02:45 | User: sitecore\Admin | Action: Item created

The item was last updated on 26.09.2005 1:03:22.

Even though it mostly looks like an additional number of hardcoded macros, its much more powerful: using the NVelocity templates you can code against the Sitecore API using the Sitecore client as long as the method/property evaluates to string. So now you don't have to start Visual Studio every time you need to change your custom template, and the educated users can do it themselves.

How to use it:

1. First of all, if you're not familiar with the Sitecore V5 workflows and workflow actions, I suggest that you read about them first.
2. Download and install the package.
3. Extended email action template is installed to the /templates/workflow folder.
4. There's also an example 1-step workflow installed with the package - Extended Mail Demo Workflow.

Here's how the shortcuts are defined:

/// <summary>
/// Populates the velocity template context. Only the objects that were
/// added in this method will be accessible in the mail template.
/// </summary>
/// <remarks>Override this to add your own data to the context</remarks>
protected virtual void PopulateContext(WorkflowPipelineArgs args)
{
   velocityContext.Put("args", args);
   velocityContext.Put("item", args.DataItem);
   velocityContext.Put("processor", args.ProcessorItem);
   velocityContext.Put("user", Sitecore.Context.User);
   velocityContext.Put("history", args.DataItem.State.GetWorkflow().GetHistory(args.DataItem));
   velocityContext.Put("state", args.DataItem.State.GetWorkflowState());
   velocityContext.Put("nextState", GetNextState(args));
   velocityContext.Put("site", Sitecore.Context.Site);
   velocityContext.Put("time", DateTime.Now);
}

As it says, if you need your own shortcuts/helpers than override the method, place your assembly into the /bin folder and change the 'type' field in the action item in Sitecore.

The Velocity itself is a powerful tool: you can define your own macros and variables, use basic conditions (#if) and loops (#foreach) and parse external templates. Google it if you need more information - most of the hits will come from the java version of Velocity, but it's almost the same.