A recent series of blog posts that my teammate,
Chris Hamm, has been working on has helped me out as a developer time after time. Check out his latest post in the series,
Kentico 101: The Dashboard. After working on a client’s site recently, I found a topic that doesn’t have as much documentation/visibility as I would like, so I thought it would make a great addition to Chris' Kentico 101 series. So, here we go!
One of Kentico’s most powerful built-in tools is perhaps one of the least used by us as the consumers: the macro console. The macro console gives both developers and marketers the ability to see an extensive amount of information about their site at any given moment, from basic user information to a more in-depth Ecommerce context. Per the spirit of the aforementioned 101 series, the purpose of this blog post is not to give an exhaustive look at Kentico’s macro console. Instead, this blog post will give a high-level overview of how to access and use the macro console with a few examples that I used while working on a client’s site recently. If you are interested in a deeper dive into the macro console, leave a comment on this blog letting me know.
Kentico Macro Console
While the macro console is beneficial for both the developer and the marketer, it is more geared towards developers, or more specifically those with the familiarity of the naming of the inner workings of the Kentico CMS itself. Nevertheless, both the developer and marketer can glean information from this tutorial on inspecting the current objects from the macro console, so let's get into it.
How to Find the Kentico Macro Console
The easiest way to find the macro console is to
navigate to the 'System' application from the main menu in the top left (the Kentico star symbol); then click on the 'Macros' section, then the 'Console' as shown below.
A few notes here
First off, the macro console uses the various objects, macros, and data that are being used and manipulated as the site runs/as users interact with it. That being said, all of that data is represented within different CMSDataContext’s such as 'EcommerceContext', which we will touch on in the second example.
Second, there are two ways to view/manipulate the data from the macro console: by entering an expression, or by clicking on an item in the tree of objects under each CMSDataContext. From there, the entered/selected data will be displayed in the 'Output' window below the 'Results' section at the bottom of the page. The easiest way to view real data in realtime is to
click on the 'Real data with displayed values' radio button as shown below.
Let’s go over a few examples that should help to get you started on what the macro console is capable of.
Example 1: Basic User Information
From the macro console page (and with the 'Real data with displayed values' selected),
open up the 'CMS.DocumentEngine.CMSDataContext' and click on the 'CurrentUser' object. This will give you information on the user account that you are using, such as the name, ID, Memberships, and many more data points about the user account.
Note that when you clicked on the 'CurrentUser' object, the Expression window reflected that additional object, displaying 'CMSContext.Current.CurrentUser'. Also note that if you
expand the CurrentUser with the small blue '+', you can view all of the data stored within the 'CurrentUser' context in realtime.
Example 2: ECommerceContext
You can apply this same process to see any of the data stored in realtime within a context, such as the 'ECommerceContext'. This was especially helpful for me as I debugged a client’s website in which we added basic online shopping. I constantly utilized the macro console to see exactly what was being stored within the shopping cart throughout each step of the consumer’s online shopping experience.
I went ahead and added several items to the cart, as shown below.
Let’s
jump back to the macro console and see how those items are represented.
If we
open the ECommerceContext -> CurrentShoppingCart ->CartProducts and select the first item (ID of 'f4f1786c-351b-4ebd-b352-f1be118ed2c5' in our example ), we can see the SKU information of that cart item such as the name, price, and weight of the item; in our case, the 'Guatemala Finca El Injerto (16 oz)' coffee. Having the ability to see the items in the shopping cart is very beneficial to debugging the Ecommerce process, as I mentioned earlier. It was especially helpful for me when I was writing custom logic around the price of the items compared to their weight and quantity.
Conclusion
The two examples that are given only scratch the surface of what the macro console can do in the context of inspecting the current objects/context. Kentico has done a phenomenal job at giving developers and marketers alike visibility into how and where data is stored and manipulated.
Furthermore, the macro console also has the ability to execute actual expressions so that you can test code and see how the data is coming through- For example, entering ‘“word”.ToUpper()’ into the Expression window will transform it to ‘WORD’ upon execution. That example and others like it go beyond the scope of this 101 blog, but
here is a link to Kentico’s documentation about macro syntax. Perhaps I will cover more advanced examples in a later blog.
I would highly encourage you to utilize this powerful built-in tool on your next project or current website. If you would like to know more, don’t hesitate to reach out to the BizStream team and partner with us on your next project!