Learning Umbraco in a week - Day V

 

This is my fifth post of the "Learning Umbraco in a week" series. The main agenda of this post is listed below.

• What are .Net Macros in Umbraco?
• How to use .Net User Controls in Umbraco?
• How to Parametrize a Macro? 
• Communication between Umbraco and User Control
• How to Debug a Macro in Umbraco?
• How to Cache Macro result in Umbraco? 

What are .Net Macros in Umbraco? 

.Net Macros are Umbraco's means of inserting .Net Controls into templates or content, to start. They are also the carrier for custom .NET controls. 

How to use .Net User Controls in Umbraco? 

Using .Net Controls in Umbraco is a two phase process, the phase are listed below. 

Phase 1 - Copying Files

• First you need to copy your control. Whether it’s a User Control or a Custom Control you’ll need to copy the assembly (dll) into the /bin folder of your Umbraco installation.
• If it’s a User Control you’ll need to copy the .ascx file as well.
• Your installation already contains a / User Controls folder which is recommend to be used, but you’re free to place them anywhere in your application.

Phase 2 - Registering a .Net User Control as Macro

• Go to Umbraco Default Page (Admin Page) > Sections > Developer
• Right click on the Macros folder, and select Create.
• You will receive a dialog where you can specify the name of the Macro to be created.
• Specify the name of the new Macro, check Create Macro. Click Create.
• Now select the macro from the list "Browse usercontrols on server…".
• You have now created the Macro for rendering the content.

How to Parametrize a Macro? 
It is possible to pass values from to a Macro in Umbraco. Values can be passed through the following ways.

1. Current Page node
2. Request collection
3. Cookies 

To pass the Current Page's property with the alias "bodyText", the following syntax is used.

<umbraco:macro alias = "RenderProperties" pagevalue = "[#bodyText]" runat = "server"/>

Syntax for passing parameters through different ways is as follows.

• To insert page value: [#propertyAlias]
• To insert recursive page value: [$propertyAlias]
• To insert cookie value: [%cookieValueKey]
• To insert value from request collection: [@requestValueKey]
• For passing multiple values <umbraco:macro value = "[#propertyAlias], [#propertyAlias2], my static string" /> 

 

Communication between Umbraco and User Control

Communication between Umbraco and User Control is done by creating Public Properties in your control and match them with Macro elements. Umbraco will even create the UI when inserting the Macro.

 

It’s important to note that the Alias of your Macro element matches the Name of your Public Property. Moreover, be aware of case sensitivity.

How to Debug a Macro in Umbraco? 
NET controls are wrapped in Umbraco Macros and suddenly is out of the hands of Visual Studio doesn't mean you cannot use your favorite debugging practices, i.e. you can always utilize the Microsoft Visual Studio "Attach to Process" feature and debug .Net Macro.

For example, if Umbraco is hosted on Microsoft IIS then you will have to attach to "w3wp.exe", and if Umbraco is hosted on Microsoft WebMatrix then you will have to attach to "WebMatrix.exe".

How to Cache Macro result in Umbraco? 
If you are using a User Control or XSLT, and have the Macro set to cache, it will cache the results of the control for the determined time.

That's all for this post, in the next post (Learning Umbraco in a week - Day VI) we will have a look at the Umbraco API.