INTRODUCTION TO UMBRACO MACROS
In order to introduce custom functionality and specialty output to your Umbraco site, you will need to know about macros. A macro is essentially a callable action that executes a predefined chunk of code. This code can be made up of the following technologies/languages:
- .NET C# and VB User Controls
- .NET Custom Control (Server Control)
- XSLT Template
- IronPython, LOL Code, Ruby, and more
Macros are created in the Developer section 
Macros node. You can create one using the following steps:
- Navigate to the Developer section in the backoffice, found at http://<install domain>/umbraco.
- Right-click Macros, then click the Create menu option, as shown in Figure 5-1.
- Select the .NET User Control, XSLT template, or other code source and save your Macro.
Figure 5-2 shows a “bird's-eye-view” of how to create macros in Umbraco, giving an overview of the fields and functions, which are described in Table 5-1.
Umbraco will create the Alias automatically by concatenating the Name value, stripping out spaces and special characters.
In addition to creating the macro manually, you can specify that your XSLT file automatically generate the macro and preselect the newly create XSLT file as the source for this macro. This is the best practice way of creating your XSLT macros.
In a typical site there is little concern about caching your macros. The Cache Period option is mostly for high-traffic sites and should be used with care because it may impact the rendering of certain content. For example, if you are using a .NET user control to pull in stock quotes, the caching set here can impact the information if it is presented in real-time.
Macro Parameters
You've surely noticed that we have two tabs for editing a macro. The Parameters tab allows you to specify public properties that can be used to pass in values to the macro. Umbraco comes with a set of predefined types that pick the intended value for the specified property. Table 5-2 shows the details of the various types, while Figure 5-3 shows the output of the various types and how they are presented to the user when inserting your macro.
TABLE 5-2: Macro Parameter Types
Naming your macro parameters with reserve .NET tag property names will not work. For example, do not create a macro parameter named Id or CssClass as those are reserved for use in standard .NET tags.
Rendering Macros In Your Site
You have two ways of displaying the results of your created macros independent of how they are sourced (XSLT, .NET, or other). Depending on how you configured the macro in the settings, as described earlier in this chapter in Table 5-2, you can add the macro tag in a Rich Text Editor data type control within your content, as shown in Figure 5-4, or you can add the macro tag directly in your master page templates, as shown in Figure 5-5.
A macro inserted in your template will have the following format:
<umbraco:Macro Alias=“NameOfMacroHere” parameter1=“” parameter2=“” runat=“server”></umbraco:Macro>
This example shows that parameters, as we discussed in the previous section, are added as simple tag attributes. The result in the Rich Text Editor is slightly different and is not meant to be edited by hand: you use the Macro button shown in Figure 5-4 to edit and control your macro.