Rules Tokens and Forms API in Orchard 1.3

Rules Tokens and Forms API in Orchard 1.3

To recap, I have presented the following Orchard Tutorials with the release of Orchard 1.3: Markdown support for authoring new content items like Pages and Blog Posts in Orchard, a new Preview Feature for viewing unpublished and draft blog posts in Orchard, the ability to Delete Content Types, and the new ITitleAspect and Title Part for helping Orchard Web Developers. Now it is time to introduce a set of additional features in Orchard 1.3 that go hand-in-hand and provide amazing extensibility for your Orchard Websites: Rules, Tokens, and the new Forms API. These three features will change the way you look at adding functionality to Orchard, and I can't wait to see what Orchard Web Developers will dream up to exploit this new functionality.

Send a Tweet Whenever a New Blog Post is Published

To best understand the new rules, tokens, and forms API in Orchard 1.3 we really need to look at a typical customer request. We get a customer request that everytime a new blog post is published on the Orchard Website they want a Tweet to go out publicizing that blog post. The tweet must contain the title of the post, the name of the author, and a link back to the post itself!

No problem you say. You are an expert Orchard Web Developer. You know exactly how to tie into the Pub/Sub Functionality of Orchard and can have something developed by the end of a day or two providing this functionality. Then later it turns out the customer also wants to have an email message sent to the site owner, too, so she can keep up-to-date on all posts published on the website. Again, being the ace Orchard Developer you are, you can write the code to have an email message sent out. It will just take you another day or two. New rules and requirements like these just keep coming and coming and the code is getting harder to maintain and you need a better solution.

It would be easier to not have to write any code at all, but instead have a rules engine that would allow us to subscribe to events and based on those events specify actions to take place. This is exactly what we have in Orchard 1.3 and how we are going to solve this simple problem.

Rules in Orchard 1.3

Click on the Modules Tab in Orchard 1.3 and type "rules" into the filter. By default you will see 5 features:

  1. Comments Rules
  2. Contents Rules
  3. Email Rules
  4. Rules, and
  5. Scripting Rules

Rules provides the default rules functionality while the other features provide various events and actions that can be subscribed to and performed on the Orchard Website.

Rules in Orchard CMS

Of course, you also see another feature called:

  • Twitter Rules

in the image above. I created that new feature in a custom Orchard Module to show you that as an Orchard Developer you can and will create your own rules to make Orchard even better. In this case, the client asked for the ability to send a tweet when a new blog post was published, so I had to develop this functionality myself. It was pretty quick and painless given the tools provided by Orchard and is reusable for any event that can be subscribed to in Orchard.

To solve this request by the client, I will need to enable Rules, Contents Rules, and Twitter Rules. Notice that when you enable Rules both Tokens and Forms are a dependency and get enabled as well. As I said before, they go hand-in-hand and you will see this soon. Once I enable Rules a new Admin Menu option appears in the Orchard Dashboard, called Rules. Clicking on Rules allows me to manage all my rules. I can create, edit, and delete rules.

Here is the rule already created to send a tweet when a blog post is published in Orchard.

Send a Twitter Tweet when a blog post is published in Orchard

If I choose to add or edit a rule as show below, you will notice that the rule has a name, a list of events, and a list of actions. Based upon a set of events a number of actions can be performed. In this case I just have 1 action and 1 event:

  • Event - When content with types (BlogPost) is published.
  • Action - Send a tweet.

Rules Events Actions in Orchard CMS Rules Engine

Ok, so where did the events and actions come from? They came from the Contents Rules and Twitter Rules Features I enabled earlier. When you click on the Add a new Event button a list of events that you can subscribe to are displayed from which you can pick and choose. In this case we are only seeing the events for the Contents Rules feature, but this list will grow and grow as you enable more features that expose events.

Content Rules in Orchard CMS

In the list you see the Content Published Event and behind the scenes I chose it to fire when the content type "BlogPost" is published and only for that content type in this rule.

Then when I chose the Add a new Action button, we see a number of actions, including the Send Tweet Action that I developed as part of my Twitter Rules Feature!

Twitter Rules in Orchard CMS

Send Tweet is the action we want, but when we choose the action it asks us for a bit of information in a Form I created using the new Forms API in Orchard 1.3.

Forms API in Orchard

To send the tweet the action needs to know which Twitter account to use and the text for the body of the tweet. In order to create a form to request this information I used the new Forms API in Orchard. The Forms API in Orchard allows a developer to use a fluent interface to display labels, form controls, and other display items on your forms. When the Orchard Administrator chooses to send a tweet as an Orchard Action, he or she must choose the user / account associated with the Tweet from a dropdown list and then type in the body of the tweet in a textarea to be posted to Twitter.

Forms API Orchard CMS

In this case the tweet will be associated with the author's Twitter Account ( configured separately ). The body of the tweet, on the otherhand, varies from blog post to blog post as it will contain the title of the blog post, the author's name, and a link to the post. How do we specify a placeholder in the tweet to represent the blog post title, author and url? You guessed it. Tokens!

Tokens in Orchard

The last piece to this puzzle is Tokens. Looking back at the client's requirements, the tweet must contain the title of the post, the name of the author, and a link back to the post itself! These values will change from post-to-post so I need a way to represent these values and where they are positioned in the body of the tweet. I do this with Tokens. The result will look as follows.

Tokens in Orchard 1.3

I use three tokens in the body of the tweet:

  1. {Content.DisplayText} - The Title of the Orchard Blog Post
  2. {User.Name} - The name of the author
  3. {Content.DisplayUrl.Absolute} - The absolute URL of the Blog Post

Click Save and enable this awesome rule! Everytime an author now publishes a blog post on the website a tweet will be sent encouraging his loyal followers to read the post on the website. Now aren't you glad you chose Orchard :)

Conclusion

Hopefully this Orchard Tutorial on Rules, Tokens, and the Forms API gets you excited about Orchard CMS and it's possibilities. I encourage you to read the other Orchard Tutorials focusing on the new features in Orchard 1.3.

If you're a small business owner looking for a new Orchard Website and/or custom Orchard Modules and Widgets, please contact me about my services. I absolutely love developing for Orchard CMS!