Passing parameters into partials in Umbraco
If you're familiar with the MVC pattern, you're probably familiar with the concept of partial views. Modern Umbraco, being based on MVC, makes good use of partials. If you're not familiar with them, they're chunks of reusable template (AKA View) code. They're useful for injecting components into your pages that you'd find across your site, such as a navigation bar or a footer menu. Here's a very simple partial:
This partial can be used wherever you need to inject the main page heading. It's useful to do it like this because, if we want to change the class attribute, we only have to do it in one place, and the change will be reflected everywhere. This is what's known as keeping things DRY.
To inject the partial into your page, you call it by using the
Partial() HTML Helper method like this:
But what if you want to control what gets rendered by passing in an argument? For instance, say I want to control the name of the tag, or the class attribute? There are a couple of ways to do this in Umbraco.
Passing in a ViewDataDictionary
This is a concept inherited from MVC. Normally a model is passed into a partial. In the case of Umbraco, the model passed in by default is the bundle of data associated with the current page. This allows us to access the current page data within the partial. But if we need some data that isn't part of the model then we can pass in a
ViewDataDictionary. For example, if we want to pass a tag name and class into a partial, we could do this:
This should be fairly self explanatory. We're passing in two key-value pairs: one with a key of
tag and value of
h1, and the other a key of
klass and value of
page-name (I've called it klass because C# already uses the word class internally). The syntax is explained in more detail on StackOverflow.
We can now dig out those arguments in our partial like this:
Now, arguably, it would be simpler to just not use a partial in this simple example and write the Razor directly into the template, but this example is just to demonstrate the concept.
The other way to pass data into a view is to use an Umbraco Partial View Macro.
Partial View Macros
Macros in Umbraco are resusable pieces of code, much like partials. They come in several flavours: MVC Partial View, XSLT, usercontrol, and "Razor script". All can be considered legacy and safely ignored apart from MVC Partial View Macros, which are now the recommended type.
Partial view macros are essentially normal partials, but you can enable them for use in the Rich Text Editor. This means editors can insert a macro easily into content. You can assign parameters to macros that will pop-up a nice UI element in the backoffice such as a media picker, allowing the editor to select some media easily. The macro wraps the selected media in some custom Razor that you setup in your partial view macro
.cshtml file. That's really the difference between a normal partial and a macro view partial. If you don't need editors to insert macros on-demand in the RTE, then use a normal partial instead as described above.
So, example. Say we create a macro that will accept two arguments -
klass, just like we did with the partial earlier. Let's call it
pageName2. We'll add the parameters as simple textboxes because we just want to pass in simple text strings. This is how to call that macro in a view:
They syntax is a little bit cleaner than using a normal partial view, but it's hardly worth the effort of maintaining a macro in the backoffice, especially as they're harder to keep under version control. So my rule of thumb remains: use a partial view macro only if you need to add a macro to the Rich Text Editor, otherwise use a normal partial view.