Orchard CMS is a great CMS for two important reasons: extending and increasing its core functionality.

Even as the lead developer (and owner) of a .NET development agency in Boston, I had a hard time understanding how all the quote-unqoute magic happens in Orchard CMS, with template overriding and shape objects. But it’s part of my role here at Cloud Construct, heading up what I think is one of the best web development teams in Boston, to understand the in’s and out’s of the tools we use or recommend to our web development clients.

I discovered the source of the magic. The creators coded Orchard CMS to override templates and shape objects. More so, template overriding is basically the same thing you do when you want to pass a View template to a controller, except the Orchard core checks for alternates and similarly named templates in your theme first.

Okay, so it’s not really magic. Just great architecture. So great, I showed my team of .NET and azure developers, User Experience, and even Information Architecture designers. As I dug deeper, I realized shape objects were simply dynamic objects that were getting resolved at runtime. The Drivers build them, and we (meaning my web development team) can modify them as needed along the Orchard pipeline. I also discovered how to add more features into the core functionality.

Typically, you add new functionality to the CMS by building out a custom module and utilizing that module for whatever you need to do. But there are some instances where what you want to do is so minor that you don’t want to build a whole module for it. Rather, it’s more efficient not to build a whole module for one simple functionality task. At least, that’s my viewpoint: How can we make web development tools more efficient? Not only for us but also for our Cloud Construct clients who look to us as the experts.

For instance, you might just want to add a new parameter to an object in a core module and do something with that value during its normal processing. Case in point: Adding an option for a “reply-to” field to be added to emails coming from custom forms.

But the Orchard Email Activity, EmailMessage class, and SmtpMessageChannel class do not support this. Obviously, I could just modify those and call it a day; but if the Orchard.Email module ever gets updated, I would lose my changes.

Orchard.Email Module :

NOTE: I could also update the Orchard.Email module and then push my changes up to the public repo, so all can take advantage of this change. But in most cases, I am working disconnected from that repo and using standalone release code bases for our web development, .NET development or website design clients. Again, it came down to being efficient ... for the long-term.

The No-Module Solution

In Orchard, a theme is just like a module, for the most part. It is an MVC area and is checked by the Core before rendering for templates that might override any module. The secret is that its also checks any classes as well. This is pretty powerful. This lets you override classes that are present in the core and in modules by simply adding them to your theme. What did I do?

I added four new files in specific folders to my theme:

1. MyEmailActivity.cs is a direct copy of the EmailActivity.cs file in the Orchard.Email module. I then changed the namespace and class name and modified the Execute method to support my new "From" parameter.

As you can see from above, we are now passing a From parameter into the messageservice. Step 2 details how to get that parameter into the Activity. You will also need to swap out the Form and Name category properties of the class as well. This will make sure your activity is unique and it gets bound to the form you're going to create in the next step.

2. The next file to add is MyEmailForm.cs. This is also an exact copy from EmailForm.cs in the Orchard.Email module. I then changed the namespace and class name and modified the Describe method to support adding the new "From" parameter to the Action form. Actions are associated with a form in order to provide additional information for your action to process.

TIP: Make sure you also set the Id of the form to MyEmailActivity, which corresponds to the activity you created in Step 1.

3. Next, copy the EmailMessage.cs class from Orchard.Email and also add it to your theme like it is shown above. Update the namespace. Add an additional property called From which is a string field. This object will be used to build the new MailMessage in the Process method of the next file.

4. Create the last file called SmtpMessageChannel.cs and also copy this from Orchard.Email. You can update the namespace but leave the class name the same. This will allow for Orchard to resolve this as the SmtpMessageChannel class to use when sending the email. Orchard will use this class over the one defined in the Orchard.Email module. Next in this class, add some code to abstract out the new From parameter.

Next, assign this parameter to the MailMessage being passed to the SmtpClient.

This will then allow for you to provide a "reply-to" for your email. If you're familiar with the Form that is shown for the email activity, you know you can just paste in a hardcoded value or use a token. In my example, I am having users submit a contact form and then alerting the admin of the system through my new "MyEmailActivity." In the form for the activity, I use a token so that the recipient of the form action can easily respond to the person submitting the contact form. Below our new field, we added being seeded with a token from the contact form being submitted.

Here is the workflow definition:

5. For the last part, include the appropriate view files and stylesheets for the new Action so it is displayed in the Admin. Because we did this in the theme and not a module, we added two files to the Admin theme so they are found when the Workflow editor is brought up.

Finally, add the css file shown in the picture above and also the Activity view file so that the Activity toolbox properly loads. I copied the ones from Orchard.Email.

That's it!

Let me know if you tried this too, or if you encountered any errors in my description. Some of the inner workings of the Orchard CMS are still magic to me.

‍

Arra Derderian serves as the President and Lead Technical Architect for Cloud Construct, a top Boston web development firm, and founder of the Boston Orchard CMS User Group. He is a member of the Windows Azure Insiders group. Cloud Construct is a digital agency with capabilities that span web development, information architecture, UX, and design.