Using Graffiti CMS Macros

Generally speaking, macros are a short piece of code that help you to easily change the appearance and layout of your site.  Technically speaking, macros are Chalk Extensions exposed in the Graffiti core that you can use to build or customize a theme.  While it is true that any of the standard public Chalk items  (ie. $post.Body) can be considered "macros", the tips discussed below are focused specifically on the functionality provided by the $macros class.  The $macros class contains helper methods and properties that are available on every page request.  Here are a few of the most common $macros that you will want to get familiar with:

• $macros.NavigationLinks() - This macro will return a list of navigation items that can be used to display parent and sub category navigation links.  (usage: #foreach($link in $macros.NavigationLinks()) ... #end)
• $macros.IsNull() and $macros.IsNotNull() - These macros allow you to determine if an exposed Chalk variable is null or not null respectively.  These two functions are very handy for displaying content that is only displayed if a specific condition is met. (usage:  #if($macros.IsNotNull($post)) ... #end)
• $macros.LeftSideBar() and $macros.RightSideBar() - These macros are used to render left and right sidebar widgets.  If your theme is going to support widgets from the control panel you will need to include one or both of these macros in your theme (usage: $macros.RightSideBar("%{beforeWidget='<li class=\"widget\">', afterWidget='</li>', beforeTitle='<h2>', afterTitle='</h2>'}"))
• $macros.ThemeFile() - The ThemeFile macro allows you to reference the directory of your theme.  This is extremely helpful when you need to reference files or images that support your theme through a view. (usage: $macros.ThemeFile("images/email.png"))
• $macros.Style() - This macro like the ThemeFile macro allows you to reference the directory of your theme.  However, this macro is used specifically to reference the css file(s) that are used in the theme.  (usage: $macros.Style("style.css","screen"))  

Learning and using these macros will give you the tools you need to quickly develop new themes.  The most common question that is asked regarding macros is, "How do you know what macros are available?".   Many of the macros can be found from the Macros Overview page with descriptions and here is a full list (without descriptions) from version 1.0.1.

If you commonly use a macro that isn't listed here, feel free to leave a comment and be sure to include an example of how it can be used.