Expression Option Sightly

Options in Sightly expressions can have two different kind of usage:

They can act as instructions that process the output of an expression, like a function would.
When the expression is located in a data-sly-* statement, they allow to provide instructions or parameters to that statement.

Note: to easily try out the examples provided below, you can install the REPL tool on your AEM instance.

On a plain expression (that is not located in a data-sly-* statement), following options are possible:

format: Concatenates strings.
Example: ${'Page {0} of {1}' @ format = [1, 10]}
Displays: Page 1 of 10
i18n: Translates strings. Additionally, locale allows to change the language if something different to the current page language is to be taken, and hint allows to provide help to the translator and to distinguish strings that might be identical but that have different meanings.
Example: ${'Number' @ i18n, locale = 'de', hint = 'Media DPS Folio Number'}
Displays: Nummer
join: Defines the string delimiter to display between items of an array.
Example: ${['foo', 'bar'] @ join = '-'}
Displays: foo-bar
context: Control how the HTML escaping and XSS protection applies.
Example: ${'<p>Hi!</p><script>alert("hack!")</script>' @ context = 'html'}
Displays: <p>Hi!</p>

Following statements allow the expression options as listed above, because these statements are similar to writing the expression without statement:

data-sly-text:
This example: <p data-sly-text="${currentPage.title}">Lorem ipsum</p>
Is equivalent to: <p>${currentPage.title}</p>
(This can be useful if you want to leave placeholders provided by the HTML designer in the markup.)
So this example: <p data-sly-text="${'Page {0} of {1}' @ format = [1, 10]}"></p>
Displays: <p>Page 1 of 10</p>
data-sly-attribute:
This example: <p href="#" data-sly-attribute.href="${currentPage.path}"></p>
Is equivalent to: <p href="${currentPage.path}"></p>
(This can be useful for writing valid HTML as the W3C HTML5 validator verifies that URLs are correctly constructed. Also it allows to leave placeholders provided by the HTML designer in the markup.)
So this example: <p data-sly-attribute.title="${['foo', 'bar'] @ join = '-'}"></p>
Displays: <p title="foo-bar"></p>
Note that data-sly-attribute can also be used to set multiple attributes by providing an iterable key-value object, like in the example below. But this usage of data-sly-attribute doesn't allow to use any options: <div data-sly-attribute="${properties}"></div>

Following statements accept any expression options as they allow to pass named parameters:

data-sly-use:
Example: <p data-sly-use.bar="${'logic.js' @ foo = 'hello'}">${bar}</p>
logic.js: use(function () { return this.foo + " world"; });
Displays: <p>hello world</p>
data-sly-template and data-sly-call:
Example:
<template data-sly-template.tmpl="${@ foo}">${foo} world</template>
<p data-sly-call="${tmpl @ foo = 'hello'}"></p>
Displays: <p>hello world</p>

Following statements allow a custom list of options:

data-sly-include:
Notice that: <div data-sly-include="${ @ path = 'path/to/template.html'}"></div>
Is equivalent to: <div data-sly-include="${'path/to/template.html'}"></div>
Or even to: <div data-sly-include="path/to/template.html"></div>
(I'd always opt for the shorter writing form.)
Options for data-sly-include (other than path) are:
- prependPath: Adds something before the path.
- appendPath: Adds something after the path.
- wcmmode: Changes the WCM mode for the included file.
data-sly-resource:
Here too the short writing form is: <div data-sly-resource="par"></div>
Same as for data-sly-include, but it additionally accepts following options:
- selectors: To replace the selectors.
- addSelectors: To add selectors.
- removeSelectors: To remove selectors.
- resourceType: To define or change the resource type (only needed if not already defined as needed on the content node).
- decorationTagName and cssClassName: For backward compatibility with the way AEM added DIV elements around included components in JSP.

And following statements allow no expression options: