Describes how to set up a macro, use macro parameters & configuring caching. Defines the different types of macros and provides details on the different macro engine APIs and their usage
Macros and Partial View Macros will be removed in the next version. Consider using Partial Views or Blocks in Rich Text Editor.
A macro is 'wrapper' for a reusable piece of functionality that you can utilise in different places throughout your site.
You can use macros in your templates, like MVC Partial views - however they differ in that they can be configured to work with Parameters and Caching, that can be updated by editors via the Umbraco Backoffice. So if you allow a macro to be added to a Rich Text Editor or Grid cell, the editor, at the point of inserting the macro can supply the parameter values.
For example imagine adding an Image Gallery within a rich text editor, and at the point of insertion 'picking' the images to display.
Define the parameters
Using in a Rich Text Area
A Rich Text Editor should be enabled with macros in the toolbar to allow inserting macros.
Rich Text Area with macro toolbar option
Insert the macro into a Rich Text Area
The same implementation logic can be used in lots of different places on your site, and the editor can customise the output by choosing different parameters.
Macros can be implemented using an MVC Partial View - Partial View Macros. It uses the exact same syntax and objects as MVC views.
Here's a basic method to render macros:
This renders a macro with some parameters using an anonymous object:
This renders a macro with some parameters using a dictionary
Request Collection
To retrieve a value from the request collection such as a query string parameter we specify it by prefixing with an "@" symbol.
To get a query string parameter with the key "productId" we would specify our parameter like this [@productId]
Document Type Property
Document type properties are specified by a leading "#" and then the alias of the document property.
To pass a property with the alias "bodyText" we would specify [#bodyText] in the parameter value.
Recursive Document Type Property
Recursive Document type properties are specified by a leading "$" and then the alias of the document property.
Umbraco resolves recursive parameters by looking at the current page for a value and then traversing up the content tree until a value with that alias is found.
Session Collection
Retrieve values from the session collection or cookies by prefixing with a "%" symbol.
To retrieve a value with the key "memberId" from the session collection we would specify our Macro parameter value as [%memberId]
For long running macros that return the same results, caching boosts site performance, you can specify caching levels for the Macro in the backoffice.
Options are:
Cache by Period - set the number of seconds to cache the output of the Macro for
Cache by Page - Whether to create a different cached instance of the macro for each page (think breadcrumb - you wouldn't want the same breadcrumb on every page)
Cache Personalized - whether to create a difference cached instance of the macro for each site visitor (if your Macro says 'Hi Niels' using the currently logged in Members name, you wouldn't want this cached to be the same for every visitor to the site, unless they were all called Niels)
Partial View Macros reference
Partial View Macros are the recommended macro type to use in Umbraco. They work in both MVC and Webforms and use the unified query syntax that is available via the UmbracoHelper.
All Partial View Macro views inherit from Umbraco.Cms.Web.Common.Macros.PartialViewMacroPage and the header of each Partial View Macro file will contain:
The model type for a Partial View Macro is Umbraco.Cms.Core.Models.PartialViewMacroModel. This contains all of the properties you need to render out content alongside some additional properties about the macro itself:
MacroName
MacroAlias
MacroId
MacroParameters
By default, Partial View Macros are stored in this folder:
~/Views/MacroPartials
However, if you are bundling up Partial View Macros as part of a package, they can also exist in this folder:
~/App_Plugins/[YourPackageName]/Views/MacroPartials
Since Partial View Macros are a normal MVC partial view, their file extension is cshtml. All Partial View Macro views inherit from the following view class:
Therefore, all files will contain the header (which is done automatically for you if creating Partial View Macros via the Umbraco backoffice):
You can use @CurrentPage, @Model.Content, @Umbraco, ...
You can access the macro's parameters using the:
MacroParameters property on the model which is of type IDictionary<string, object>:
Typed GetParameterValue method in Umbraco.Cms.Core.Models namespace:
Typed GetParameterValue method with the default value fallback:
In this article you can learn how to create and update a Macro, as well as how to configure its parameters.
There are a couple of ways to create a macro.
The first way is to manually create a macro, by right-clicking the Macro folder in the Settings section:
Give it a name in the dialog screen, and you'll be presented with the macro editor.
The second option is to create the macro through Partial View Macro Files.
The dialog provides the following options:
New partial view macro: Will give you an empty macro with an associated empty partial view file
New partial view macro (without macro): Will give you a partial view, without an associated macro
New partial view macro from snippet...: Will give you the option to choose between a pre-defined set, including a macro and a partial view with a code snippet
Folder...: Will give you the option to create a folder below "Partial View Macro Files"
The macro editor view comes with a set of configuration options.
Associate the macro with a partial view. This will already have been configured if you created the macro through the second option described above, where a Partial view was created along with the macro.
Use in rich text editor and the grid
If selected will allow an editor to insert this macro in to a Rich Text Editor and/or into a Grid editor.
Cache period
Defines how many seconds the macro output will be cached for once it is rendered
Cache by page
If selected, then the macro will be cached based on the current page it is rendered on. This is useful if your macro has content that is dynamic to the current page it is being rendered on. If your macro's output is static (the same) no matter what page it is rendered on then it is better to not check this box.
Cache personalized
Similar to the 'Cache by page', this will cache the output of a macro based on a member that is logged in. If your macro is static (the same) no matter what member is logged in, or if your website does not have membership then it is better to not check this box.
Macro parameters can be used to change the output of a macro at runtime. Macro parameters are often used as a way for your editors to change the output of a macro when they insert them into rich text editors. As an example, suppose you have a widget that displays a list of links which are children of a particular content item. You could define a macro parameter that indicates for which content item to render child links for and your editor can select this content item when inserting the macro into the rich text editor.
The macro parameter dialog looks like this:
Here you can add/modify/remove macro parameters.
This list defines the different types of macro parameters:
Checkbox(Umbraco.TrueFalse) - A true/false value
Content Type picker (contentType) - Choose a type from existing Document Types
Decimal (Umbraco.Decimal) - accepts only numbers
Email address (Umbraco.EmailAddress) - validates to valid email addresses
Multiple Content Picker (Umbraco.MultiNodeTreePicker) - pick 1 or more nodes from the Content tree
Multiple Content Type Picker (contentTypeMultiple) - pick 1 or more types from existing Document Types
Multiple Media Picker (Umbraco.MultipleMediaPicker) - pick 1 or more media items
Multiple Property Type Picker (propertyTypePickerMultiple) - pick 1 or more from existing property types
Multiple Tab Picker (tabPickerMultiple) - pick 1 or more from existing tabs
Numeric (Umbraco.Integer) - accepts only numbers
Property Type Picker (propertyTypePicker) - choose property from existing property types
Tab picker (tabPicker) - select 1 from list of existing tabs
Textarea (Umbraco.TextArea) - multiple lines of text
Textbox (Umbraco.TextBox) - single line of text
Media picker (Umbraco.MediaPicker) - select a single media item
Content Picker (Umbraco.ContentPicker) - select a single content node from the Content tree
Form Picker (UmbracoForms.FormsPicker) - choose from existing Umbraco Forms
Forms Theme Picker (UmbracoForms.ThemePicker) - choose from existing Forms Themes
In some case you want to have the macro in the middle of a sentence.
To enable editors to add the macro inline, follow these steps:
Add a macro parameter called: enableInlineMacro.
Choose Checkbox (Umbraco.TrueFalse) as the type.
The next time you add the macro, enable the new parameter to add the macro inline.
In some cases, you want to have a checkbox that is enabled by default. This would enable you to create your own type of macro parameter that has 1 as the default value. To achieve this, create a DataEditor class anywhere in your Umbraco Project with the following definition:
You can create a MacroParameter however you want, the importance is to have a parameter called enableInlineMacro with the value 1 to enable it.
The syntax in Partial View Macros is similar to the syntax. In fact, they are driven by the exact same engine as MVC Views.
