Kentico CMS 7.0 Developer's Guide

Entering macro expressions

Entering macro expressions

Previous topic Next topic Mail us feedback on this topic!  

Entering macro expressions

Previous topic Next topic JavaScript is required for the print function Mail us feedback on this topic!  

This topic provides a summary of features that facilitate entering of macro expressions in various parts of the system. These features include:


Macro autocompletion

Macro selection control

Insert macro WYSIWYG editor dialog

Edit value dialog in web part properties

Macro condition editor


Click the feature name in the list above learn more about it.


Macro autocompletion


Automatic completion of macro expressions is available when writing macro expressions in all dedicated macro editors, as well as the following places:


E-mail templates

Macro-based transformations


This feature is similar to IntelliSense in Visual Studio — as you type, a box with methods or properties that begin with the letters you wrote is displayed above or below the cursor. Only those methods and properties that are relevant in the current context are displayed in the box. The methods and properties are listed in alphabetical order and you can navigate through them using the up and down arrows or the mouse. Once you select the appropriate one, press the Enter, space or dot key to insert it into the text.




The box with available methods and properties is also displayed when adding further parts of expressions using the dot‑suffix notation.




If a macro method is selected from the drop-down list, its description and signature (containing the return type and parameter types) is displayed in a tooltip next to the drop-down list. As some methods are overloaded, i.e. they can accept different numbers of parameters, parameters present in all overloads are displayed in standard letters (as "String text" in the screenshot below), while additional parameters present only in certain overloads are displayed in italics (as String charsToTrim in the screenshot below).




If the macro is being added within a particular type of context, for example an e-mail template belonging to a specific module, the related objects and properties will be prioritized. This means that the most frequently needed items can be accessed at the top of the autocompletion box, separated by a horizontal line.




Macro selection control


Another feature that makes entering of macro expressions easier is the macro selection control.




It is present in the following locations:


E-commerce invoice templates

E-mail templates

Web part properties


The control can be used in two different ways. The first one is simply typing the macro text into the text box, where macro autocompletion is available.




The other option is to select the required macro by clicking the Show/hide macro object tree (Macro_tree) button. After doing so, an object tree is opened above the text box, letting you choose objects or their properties from the current context. Like with the autocompletion feature, certain objects may be prioritized and offered in a separate tree at the top (Context specific objects). Clicking an object or its property automatically enters the corresponding macro expression into the text box.




When you have the required expression in the text box, click the Insert button to paste it into the current position in the edited text. The expression will be pasted, enclosed within the {%%} data macro parentheses.




Insert macro WYSIWYG editor dialog


Macros may also be easily added into any content areas where the WYSIWYG editor is provided, such as when editing documents in CMS Desk on the Page tab or writing the content of newsletters. In this case, macro functionality can be accessed by clicking the Insert macro (ckeInsertMacro) button on the editor's toolbar.




This opens a dialog with an object tree that works the same way as described above for the Macro selection control. Clicking on an item in the tree inserts the appropriate macro at the current position of the cursor in the edited area.




If you wish to write the macro expression directly (with autocompletion support), you can do so by switching to the Code tab of the dialog and clicking the Insert macro button when done.


Edit value dialog in web part properties


Macro expressions can be used in the values of web part properties. You may enter any required macros directly into the content of properties that allow you to specify text values. Additionally, all properties provide the EditValuebutton highlighted in the screenshot below.




If clicked, the Edit value dialog pops up and lets you enter a macro that will determine the value of the property dynamically. In the dialog, you can use both macro autocompletion and the macro selection control described above. This option allows you to use macros even for properties that do not otherwise allow text input, such as checkboxes or lists of options.




For example, the {% CurrentUser.UserIsGlobalAdministrator %} macro shown above returns a true or false value depending on if the current user is a global administrator. When added into the Visible property, this ensures that the given web part is only displayed to global administrators.





SQL injection protection in web part properties


Some web part properties are secured against SQL injection attacks, which may affect how macros are resolved in specific cases. By default, this is applied to macros entered into the WhereCondition and OrderBy web part properties.


If the macro returns a string value that contains single quote characters ('), they will be escaped and replaced by two single quotes (''). This may cause an SQL syntax error if you are using the macro to dynamically insert a part of a query, such as a WHERE clause.


It is possible to disable single quote escaping for a specific macro expression by adding the handlesqlinjection parameter and setting its value to false:


{% ... |(handlesqlinjection)false %}


To disable SQL escaping globally for all properties of a specific type of web part, edit its code behind file (e.g. ~/CMSWebParts/Viewers/Documents/cmsrepeater.ascx.cs for the Repeater web part) and add the following line of code into the SetupControl() method:




this.SQLProperties = "";


The SQLProperties property is inherited from the CMSAbstractWebPart base class by all web parts, but you can override its value to set which properties should be protected.


If you wish to enable SQL escaping for additional web part properties, you can enter their names into the value separated by semicolons, for example:


this.SQLProperties = "wherecondition;orderby;sqlquery";


Please note that disabling SQL protection may create a security vulnerability if the macro resolves its value according to data that can be modified by the website's users, such as in the case of QueryString macros.