Parameterized Snippets in Orchard CMS

Parameterized Snippets in Orchard CMS

Orchard CMS 1.10 was just released and it offers a new feature called Parameterized Snippets for Orchard Layouts. Parameterized Snippets provide an easy method for including user data for Snippets in your Orchard Layouts. Parameterized Snippets also save you the burden of developing an Element for Orchard Layouts when you don't have any complex logic or external dependencies and only need the ability to add user data to the snippet. Parameterized Snippets are definitely a welcome sight and help bridge the large gap that was initially between Snippets and Elements in Orchard Layouts.

Developing Snippets and Elements in Orchard Layouts

If you read a couple of my earlier posts, you will start to realize the usefulness of Parameterized Snippets for Orchard Web Developers.

In my blog post about developing Snippets for Orchard CMS, I provided an example of developing a Subscribe to Newsletter Snippet to help an Orchard CMS client sprinkle a subscription form throughout their website. The data is completely static and is fine as a snippet, but we have recently talked about offering a bit more customization of the snippet to allow for user-configurable hidden fields that help provide a bit more market segmentation. Parameterized Snippets will provide this functionality easily without having to move the functionality to an Element in Orchard Layouts.

In my blog post about developing Elements for Orchard CMS, I provided an example of developing a Blockquote Element for an Orchard CMS client to help with sprinking quotes throughout their website. The Blockquote Element could now be completely built as a Parameterized Snippet, because all I really needed was the ability to add user data ( e.g. quote and author ) to construct the Blockquote Element.

And, in my blog post about integrating Snipcart with Orchard CMS for e-commerce, I showed custom Elements I developed for Snipcart to add buy now, show cart, and cart summary functionality. Although I would personally still keep them as Orchard Layout Elements for maximum flexibility, one could technically make those Parameterized Snippets.

As you can see, the Parameterized Snippet is indeed very useful and really helps bridge the gap between Snippet and Element in Orchard Layouts.

Developing Parameterized Snippets in Orchard CMS

It is very easy to create a Parameterized Snippet in Orchard CMS.

First, make sure you are running Orchard CMS 1.10 or better. There are no Parameterized Snippets available in Orchard 1.9.x.

Second, make sure you enable the Layout Snippets Feature in Orchard CMS. If you don't do this, none of your custom Snippets will be harvested by the Snippet Harvester and show up in the Orchard Layouts Toolbox.

Third, create a shape in your current Orchard Theme's Views Folder ( e.g. TheThemeMachine > Views ) and make sure it ends with "Snippet.cshtml". In this example, I created a quick Notify Snippet that will be used to customize the Orchard Admin Dashboard, and I named the shape "NotifySnippet.cshtml".

Fourth, add a "using" statement to your shape so that you can reference an HTML Helper used by Orchard Layouts to provide the parameterized magic.

@using Orchard.Layouts.Helpers

And last, provide all the necessary HTML in the shape and use the SnippetField Helper Method to designate fields as appropriate. Here I am designating a field for the user to enter the Notification Type of Information, Warning, or Error to be used to display the notification. A similar idea would be useful for developing a Parameterized Snippet for Bootstrap Alerts.

@Html.SnippetField("NotificationType")
   .DisplayedAs(T("Notification Type"))
   .WithDescription(T("Information, Warning, or Error."))

Complete all those steps and you should have yourself a custom Parameterized Snippet for Orchard CMS!

Parameterized Snippet in Action

Let's fire up the Orchard CMS website and view the custom Parameterized Snippet in the Orchard Layouts Toolbar. The Notify Snippet has been found by the Snippet Harvester in the current theme and added to the Orchard Layouts Toolbar as "Notify" under the "Snippets" category.

Custom Parameterized Snippet in Orchard CMS

When we add the Parameterized Snippet to the Layout Canvas we get the magical dialog that includes both Snippet Fields that were designated in Notify. I need to know the type of notification so we get a nice color to the notification and the message to display.

Custom Parameterized Snippet Dialog in Orchard CMS

When we view the Snippet on our custom Orchard Administrative Dashboard we get a warm welcome from Florida during Spring Break!

Custom Orchard Admin Dashboard Parameterized Snippet for Orchard CMS

Conclusion

Parameterized Snippets are very useful for adding content to Orchard Websites. I highly recommend you leverage them as well as Elements when building Orchard Websites. If you need my help, contact me. I am an Orchard Web Developer for hire.

Don't forget to check out all my other Orchard CMS Tutorials. I've been developing Orchard Websites professionally for several years and my blog is jam packed with helpful information and tutorials on Orchard CMS spanning many, many years!