Transcript Kentico CMS for ASP.NET
Webinar 11/25/2009
Macros in Kentico CMS
Martin Hejtmanek (CTO), [email protected]
Topics
Macro types and syntax Localization macros Context (data) macros QueryString macros Cookie macros Custom macros Path macros Path expressions Macro parameters Macros as the web part properties When to use and not use macros and why
Macro types and syntax
Syntax – {
Localization macros
{$expression$} - ($ as string)
Localization from resources
{$General.Cancel$} ResHelper.GetString(“General.Cancel”) In-place localization – {$=
Context (data) macros
{%expression%} – (% as data value) General context macros – [
… Data context macros – [
QueryString macros
{?expression?} – (? as query)
Available within the page request {?param1?}
Request.QueryString[“param1”]
Cookie macros
{@expression@} – (@ as internet / cookie)
Available within the page request {@CMSPreferredCulture@}
CookieHelper.GetValue(“CMSPreferredCulture”)
Custom macros
{#expression#} - (# as C# or code)
Not processed by engine, processed by YOUR CODE!
{#TimeToEndOfTheWorld#} ~/App_Code/Global/CMS/CMSCustom.cs
CMSCustom.ResolveCustomMacro(resolver, “TimeToEndOfTheWorld”, out bool match) public static string ResolveCustomMacro(MacroResolver sender, string expression, out bool match) { if (expression.ToLower() == "timetoendoftheworld“) { match = true; } return (new DateTime(2012,12,21).Subtract(DateTime.Now)).ToString(); } else { match = false; return expression; }
Path macros
{&expression&} – (& as path)
Resolves AliasPath – See previous webinar
{&./Teaser&} – Document named Teaser under current document {&/{1}/{3}&} – First and third level of current document path CMSContext.ResolveCurrentPath(“./Teaser”)
Path expressions for macros
. = Current document path (only on beginning) .. = Parent document path (if on beginning, starts from current) {
How to read the path expressions
./Teaser – “Teaser document under current document ../Teaser – “Teaser document under the parent document /Products/{1}/{2} – Document in products section matching the first two levels of current path /Accessories/{1}/% - All accessories within the same main section as current product
Macro parameters
|(name)value
Culture, Format, Default, Encode, ToLower, ToBool, Equals, …
Full list in the documentation – Appendix A
{?param1|(default)N/A?}
QueryString value of param1 or N/A if not available
{%CurrentDocument.DocumentName|(encode)false%}
Current document name, never HTML encoded
{%CurrentDocument.DocumentName|(encode)true%}
Current document name, always HTML encoded
Macros in web part properties
All web part properties are resolved unless it is disabled
Some of them may be excluded
CMSAbstractWebPart.mNotResolveProperties = “;yourproperty1;yourproperty2;”;
Some of them may automatically escape SQL injection
CMSAbstractWebPart.mSQLProperties = “;wherecondition;orderby;yourproperty;”;
Web part property can use data macro to use another property
Text = Container title is {%ContainerTitle%}
If you need to do some web part setting dynamic, use custom macro
When to use and not use macros
Use macros in:
Web part properties (even non-text ones) E-mails and other templates Anywhere where it is recommended in the documentation In places where you need to set up something dynamically, it is easier to use macro than Copy – Paste – Change the web part
Don’t use macros for:
ASPX page templates Transformations Layouts In places where you have direct access to the API, it is more efficient to query the objects directly
Q&A
Now is the time for your questions The webinar recording will be available on our new Partner portal and later on the DevNet.