What Is An Umbraco Macro?

In Umbraco, we can customise the user experience in several different ways.  One handy feature to allow content editors to add re-usable components onto a page is to implement custom macros in your project.  In case you haven't run into macro's before, a macro is a reusable piece of code that developers can build into an Umbraco project, that allows content editors to add into any rich text block that's defined on any document type within the site. When we define a macro, we can define one or more parameters to be associated with it.  When a content editor drops the macro into a text area, they can populate these parameters which can be used to render the macro.  There are two types of macros in Umbraco, partial view macros (via code) and XSLT macros.  It is best practice to only use partial via macros and this is the option we will explore in today's tutorial.

Creating a Macro

To create a macro, in your '~/Views/MacroPartials' folder, create a new .cshtml file/view. The view will need to inherit from 'Umbraco.Web.Macros.PartialViewMacroPage'. The PartialViewMacroModel base type contains everything required to render the macro, including things like MacroName, MacroAlias, MacroId, and MacroParameters.

Parameters

To access a macro parameter, you can use the MacroParameters property.  Under the hood, MacroParameters is a simple dictionary, so you can add any key/value combo you want into it.
var parameter = Model.MacroParameters["customParamter"];

Creating A Macro In Umbraco

Now we've covered some of the basics about macro and how to create the code for it, I'll cover how to create this basic macro within Umbraco. First, log into the Umbraco backend, click on the developer section, click 'Macros' and click create: umbraco_custom_section Next, in the Macro Properties, select 'MVC Partial view' and from here select your macro view in MVC; for a very basic example of what a view would look like, see this:
@inherits Umbraco.Web.Macros.PartialViewMacroPage
@{
   Render Content
}
From this screen, we can add any parameters that we want to pass to our views. In the 'Properties' tab you can create as many parameters as you need. For each parameter, you can add a name, an alias and it's type. The type can be Content Type Picker, Multiple Content Type Picker, Multiple Media Picker, Multiple Tab Picker, Multiple Property Type Picker, Tab Picker, Property Type Picker, Single Media Picker, Numeric, Content Picker, Textarea or Textbox.

Adding A Macro

To add a macro to a page, go to the Content section and find a document type that has a text area property and select the 'Macro' button. umbraco_textarea_macro Select, the macro name and add in any parameters you have defined: umbraco_text_area_select_macro Now, when you render the page the macro will be displayed. It's as simple as that.

Conclusion

In today's post, we've covered what an Umbraco macro is and how to implement it within your project. To do this, you create a partial view as usual and use PartialViewMacroPage as the model. In Umbraco, create a new macro, use the view as the default view to render. After you add the macro into a text area it will then display on the page.

Jon D Jones

Software Architect, Programmer and Technologist Jon Jones is founder and CEO of London-based tech firm Digital Prompt. He has been working in the field for nearly a decade, specializing in new technologies and technical solution research in the web business. A passionate blogger by heart , speaker & consultant from England.. always on the hunt for the next challenge

Back to top