.png?width=667&height=667&ext=.png)
Help! My Kentico Macro Is Not Working
Introduction
As a long time Kentico developer and enthusiast, I have used and written many Kentico macros over the years. It’s actually one of my favorite parts of the platform. When executed correctly macros are great. However, when they don’t work, the situation can be more frustrating than just about anything I’ve encountered with Kentico. Because of my experience with macros, my colleagues at BizStream frequently come to me with the statement of: Help! My Kentico macro is not working. This common issue inspired me to create a flow chart / troubleshooting guide for what to do when a Kentico macro does not function as expected.
Don’t Know What a Kentico Macro is ?
The Kentico documentation describes a macro as a text expression that the Kentico system evaluates and converts into values. While that definition seems straightforward and to the point it seems to undervalue the whole macro concept. In reality Kentico macros are the glue that holds the whole system together. Properly used macros can automate web part properties, field values, settings, content, and the list goes on and on
One other nice thing about Kentico macros is that since the whole K# macro syntax is based off of C# there is not much of a learning curve when it comes to using them. At its core a Kentico macro is simply a shortcut of text. There are a few types of macros, but the most common one is the expression macro. It is expressed by wrapping text with a curly bracket and percent sign character.
{% ... %}
There are many built in functions you can call inside a macro expression. But really the most common uses are either a macro to use for a field that is on the current page that is being generated, or for generating paths to URLs or Images. For instance if you have a page that displays a product in an e-commerce website. You could use the first macro below to get at the product price, the second to get the current URL of the page.
{% SKUPrice %}
{% GetDocumentUrl() %}
What if you know what a macro is, enter in that macro, and your page still spits out a nice blank area where you expect it show that price or URL? Keep reading to see how I would approach this type of debugging in Kentico.
Kentico Macro Troubleshooting Guide
Remember there is more than one way to do this. However, this method has worked well for me which is why I thought I would share it. You can click on the image below to get a full sized version of the guide.
Click here to download the image or PDF version for future reference. I am going to finish off the blog post with a few details about each green step in the guide.
Custom Macro Registration
If you have written a custom macro and it does not execute, the first place to check is if it is registered correctly. I have snippet of code to check out if you are having issues with registering custom classes in Kentico 8 that may help here.
Kentico Macro Debug
The built-in debugger works very well to show you what exactly is going on with the execution of every macro that runs. As the guide illustrates it is the main place to start when something is not working correctly. Make sure you un-check the Disable debug setting and check the Enable Macro Debug setting to get the debug log to show up. From there you can find it under System -> Macros -> Debug. Do not forget to turn this off in a production scenario!
Kentico Macro Console
The Kentico Macro Console is one reason developers love Kentico 8. The console is a new feature to Kentico 8 that really makes using macros much easier than before. When the guide mentions using the macro console it means that you can try executing your exact macro right in this part of the Kentico admin screen. Simply navigate to System -> Macros -> Console to start using it.
Macro Signatures
Remember when I said debugging macros can be frustrating ? Well this is one area where that is very true. If you see a message that says. Again Kentico 8 made it easy to see if there are problems with macro signatures by giving global administrators a report to see if anything is going wrong. You can access it at System -> Macros -> Report to start using it. The best way to use it is to check the Report problems checkbox to see only errors. Beware though, if you run this tool on a live site for every macro in the system there is a noticeable hit because it could be a huge query to go through every single object and every single property in your site. This is especially true if you have a large amount of Online Marketing data or Web Analytic data.
Conclusion
Well there you have it. If your Kentico macro is not working hopefully this guide shows you how you can access the situation and correct the issue. Like I mentioned at the top of the post though, this is just the way I do it, if you have another step you take when debugging Kentico macros please share it in the comments on this blog post. Thanks!
