Macros in Kentico CMS

Webinar 11/25/2009 Macros in Kentico CMS Martin Hejtmanek (CTO), martinh@kentico.com

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 – {<type><expression><type>} • Type – Single character • $ = Localization • % = Context (data) • ? = QueryString value • @ = Cookie value • # = Custom macro • ^ = Inline control (not covered today) • Optional parameters – {<type><expression>[<parameter>]*<type>} • Parameter – |(<name>)<value>

Localization macros • {$expression$} - ($ as string) • Localization from resources • {$General.Cancel$} ResHelper.GetString(“General.Cancel”) • In-place localization – {$=<default text>[<translation>]*$> • Translation - |<culture>=<text> • {$=Hello|cs-cz=Ahoj|de-de=Hallo$} = switch (currentCulture) { case cs-cz: return “Ahoj”; case de-de: return “Hallo”; default: return Hello;}

Context (data) macros • {%expression%} – (% as data value) • General context macros – [<selector>.]<fieldname> • Available when the given context object is available • {%CurrentDocument.DocumentName%} – Current doc. name • {%IP%} – Client IP address • {%CurrentDateTime%} – Datetime.Now • … • Data context macros – [<selector>.]<fieldname> • Available only for specific modules or actions • {%Path%} – Path property from the web part • {%OrderStatus.StatusDisplayName%} – In the invoice • … • No specific API code – Just get the desired data using API …

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) • {<index>} = Specific part of current document path • 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.

Macros in Kentico CMS