|
|
Types of macros |
|
|
|
|
|
Types of macros |
|
|
|
|
|
|
Types of macros |
|
|
|
|
|
Types of macros |
|
|
|
|
|
|
||
The macro type is determined by the character at the beginning and end of the macro. Macros look like:
{<type character><expression><parameters><type character>}
Where the type character can be one of:
Macros of the same type can be nested using the "index parentheses" syntax, e.g. {(1)%FullName|(default){(2)%Username%(2)}%(1)}. Click particular macro types in the listing above to get redirected to their detailed explanation.
This type of macros evaluates data based on current context. These macros can be used for example to parametrize web parts' parameters with current document or user values. These macros can be used in combination with the K# language. For more information on its syntax and possibilities, please refer to the K# syntax and Available macro methods topics.
The format of the macro is {%ColumnName%} and the value is replaced with the appropriate value of the column based on current context. You can use all column names from current site data, current user data and current document data.
Example: “Welcome {%FullName%}” will be resolved as “Welcome Global administrator” when administrator is the current user.
There are also data macros with selectors to precisely identify the source of the data, these macros look like {%CurrentDocument.DocumentName%} and can be used for accurate determination of the data source. Availability of the selectors depends on the context where the macros are evaluated.
These macros are usually used on multilingual websites to help localize system strings. There are two types of locatization macros:
Basic localization macros are entered in the {$string.key$} format. The system uses the ResHelper.GetString(“string.key”) method and replaces the macro with the appropriate resource string.
Example: "The weather is {$General.OK$}" will be resolved as "The weather is OK".
The string and its localized equivalents are included within the entered macro. The macro is entered in the {$=Default string|cs-cz=Czech string|de-de=German string$}. It uses a localized string in case it is available or the default (first) string if it is not.
Example: “The weather is {$=OK|cs-cz=dobre|de-de=gut$}” will be resolved into “The weather is dobre” in Czech culture, “The weather is gut” in German culture and “The weather is OK” in any other culture.
These macros evaluate querystring parameters information. These macros can be used for example to dynamically parameterize the controls by the querystring parameters.
The macros are entered in the {?querystring_key?} format. Alternatively, you can also enter them as data macros like the following: {%QueryString.querystring_key%}. The macro is replaced by the querystring parameter value.
Example: “Current node ID: {?nodeid?}” will be resolved as “Current node ID: 10” for a URL like “default.aspx?nodeid=10”
These macros evaluate the cookie values. These macros can be used for example to parametrize the web parts with client-based persistent values like styles or user options.
The macro is entered in the {@cookie_name@} format. Alternatively, you can also enter them as data macros like the following: {%Cookies.cookie_name%}. The macro is replaced by the cookie value.
Example: “Current style: {@StyleCookie@}” will be resolved as “Current style: Red” if StyleCookie value is set to “Red”
These macros are resolved into inline controls, which can be used to place dynamic content into editable text regions. The macros are specified in format {^BizFormControl^} and can (usually must) contain parameters for the control using standard parameterized macro syntax, such as {^BizFormControl|(FormName)ContactForm^}. The parameters will be used to initialize the control when the macro is resolved.
These macros are entered in the {&path&} format. Alternatively, you can also enter them as data macros like the following: {%Path.path%}. They can be used to resolve current document Alias path the same way as the Path property of controls. The macro is replaced by the resolved path.
Example: WhereCondition: NodeAliasPath LIKE {&../%&}. In this case, the macro will be resolved as parent document path and will result in selecting all siblings of the current document and their child documents. This macro is intended mostly for including the document structure context into the controls WHERE condition, but can be used for many more purposes.
See Appendix A - Path expressions for more details on how paths can be entered.
These macros can be used to define your own macro. The macro is in the {#Expression#} format. Alternatively, you can also enter them as data macros like the following: {%Custom.Expression%}.
When such a macro needs to be resolved, methods registered in the MacroResolver.OnResolveCustomMacro handler are called. These methods ensure resolving of individual expressions into their result equivalents. An example of registration of such a method can be found in the App_Code/Samples/Modules/SampleMacroModule.cs class. The class extends the CMSModuleLoader partial class.
In the class, the following method is implemented. This method ensures that the {#someexpression#} macro gets resolved into the "Resolved expression" string.
/// <summary> /// Resolves the custom macro /// </summary> /// <param name="sender">Sender</param> /// <param name="e">Event arguments</param> private void MacroResolver_OnResolveCustomMacro(object sender, MacroEventArgs e) { if (!e.Match) { // Add your custom macro evaluation switch (e.Expression.ToLower()) { case "someexpression": e.Match = true; e.Result = "Resolved expression"; break; } } } |
In the Init() method, which is executed on each application start, you can find the following code which ensures registration of the method in the MacroResolver.OnResolveCustomMacro handler (the code is commented by default).
/// <summary> /// Registers module methods. /// </summary> public override void Init() { // -- Custom macro methods //CustomMacroMethods.RegisterMethods();
// -- Custom output substitution resolving //OutputFilter.OnResolveSubstitution += OutputFilter_OnResolveSubstitution; } |
Your custom macros can be defined the same way, either by adding other cases into the switch statement within the MacroResolver_OnResolveCustomMacro method in this class, or by implementing your custom classes extending the CMSModuleLoader partial class which would contain your custom macro resolving methods and their registration in the MacroResolver.OnResolveCustomMacro handler.
Substitution macros are entered in the {~expression~} format. They are similar to the Custom macros described above. The difference is that these macros are resolved in page output code, i.e. the page's final code before it is sent to the browser for rendering. The main advantage of this type of macro is that these macros are resolved on each request, even on pages that use full-page caching.
When such a macro needs to be resolved, methods registered in the OutputFilter.OnResolveSubstitution handler are called. These methods should ensure resolving of individual expressions into their result equivalents. An example of registration of such a method can be found in the App_Code/Samples/Modules/SampleMacroModule.cs class. The class extends the CMSModuleLoader partial class.
In the class, the following method is implemented. This method ensures that the {~somesubstitution~} macro gets resolved into the "Resolved substitution" string.
/// <summary> /// Resolves the output substitution /// </summary> /// <param name="sender">Sender</param> /// <param name="e">Event arguments</param> private void OutputFilter_OnResolveSubstitution(object sender, CMS.OutputFilter.SubstitutionEventArgs e) { if (!e.Match) { // Add your custom macro evaluation switch (e.Expression.ToLower()) { case "somesubstitution": e.Match = true; e.Result = "Resolved substitution"; break; } } } |
In the Init() method, which is executed on each application start, you can find the following code which ensures registration of the method in the OutputFilter.OnResolveSubstitution handler (the code is commented by default).
/// <summary> /// Registers module methods. /// </summary> public override void Init() { // -- Custom macro methods //CustomMacroMethods.RegisterMethods();
// -- Custom macro resolving //MacroResolver.OnResolveCustomMacro += MacroResolver_OnResolveCustomMacro;
} |
Your custom substitutions can be defined the same way, either by adding other cases into the switch statement within the MacroResolver_OnResolveSubstitution method in this class, or by implementing your custom classes extending the CMSModuleLoader partial class which would contain your custom substitution resolving methods and their registration in the MacroResolver.OnResolveSubstitution handler.