Macros are a powerful Umbraco feature. Macros are, first of all, a good way to granulize functionality. Rather than pasting a lot of code into a template, it is obviously better to package logic into small, self-containing and re-usable sections. This is what a macro allows you to do.
A macro generally consists of two parts:
We will start with the latter. This is where the actual work is being done. Below you will see an example of a macro that will display links to a Previous and a Next page, for instance in a tutorial. This is the content of the Partial View Macro File where all Razor functionality is available, as well as the context of the current page.
Umbraco automatically creates an equivalent Macro entry when you create a partial view macro file (and vice versa).
The Macro itself has a number of important properties.
One of the questions here is whether you want editors to be able to add the macro to a content item or that your macro can only be called inside a template. In case you want to give control to the editor, check the "Use in Rich Text Editor and Grid". And, optionally, "Render in Rich Text Editor and Grid". The latter basically gives the editor a chance to preview the resulting output of the macro.
The Macro has a selector for a Partial View Macro File. If you created your Partial View Macro File in Umbraco, the generated Macro will contain the right selection.
Advanced macros may have one or more parameters that can not be derived from the content item context. A simple example is the number of items that should be displayed.
Each rendering process takes computing power. This holds true for macros as well. Macros that iterate over large numbers of content pages tend to be compute power intensive. The first remedy for this is to optimize your code.
The second option that Umbraco offers is caching. Macros can be cached for a certain duration. For instance, the Previous ... Next Macro is a good candidate for caching as its output is unlikely to change frequently. Caching is however no excuse to not optimize your code!
@inherits Umbraco.Web.Macros.PartialViewMacroPage
@{
var nextItem = Model.Content.FollowingSibling();
var previousItem = Model.Content.PrecedingSibling();
<p>
@if (previousItem != null) {
<a href="@previousItem.Url">Previous chapter</a>
if (nextItem != null) {
<span>|</span>
}
}
@if (nextItem != null) {
<a href="@nextItem.Url">Next chapter</a>
}
</p>
}