Package com.smartgwt.client.docs

Interface DynamicTemplates

public interface DynamicTemplates

Dynamic Templates

Dynamic templates let Smart GWT property values include {expr} expression delimiters that are re-evaluated when their inputs change. The expression {Customer.name} inside a property value resolves the path Customer.name against the rules engine's ruleScope and substitutes its current value into the surrounding string. When the underlying ruleScope value changes, the property is re-evaluated and the widget's setter is called with the new value.

Dynamic templates are syntactic sugar over the existing Class.dynamicProperties mechanism: each template compiles to a DynamicProperty whose formula is the template expression. No new reactive runtime is introduced.

{expr} syntax

Expressions are wrapped in braces: 
    isc.Button.create({ title: "Save {Customer.name}'s data" });
    isc.Layout.create({ layoutStartMargin: isc.dynamic("form.values.margin + 10") });
To include a literal brace in the output, double it: {{ produces { and }} produces }.

Brace delimiters were chosen over JavaScript's template literal ${} form to avoid a false expectation of lexical scope capture, and to align with React JSX expression syntax so documentation and samples are inter-convertible between React and non-React environments.

Where templates can appear

Properties typed DynString or DynHTMLString accept {expr} templates directly — no wrapper required. Examples include Button.title, ListGridField.cellTemplate, and Canvas.contents. On any other property, wrap the value with one of the marker functions to opt in:
  • isc.dyn() — string template producing a reactive string
  • isc.dynamic() — inline expression returning a typed value (number, boolean, etc.)
  • isc.dynRestricted() — string template compiled in restricted mode (see security)
  • isc.dynOnce() — evaluated once at create() time, no reactive listener

Security: full vs. restricted mode

Templates compile to JavaScript via new Function(), so the trust level of the template source matters. For developer-authored templates that appear directly in source code, full expression mode is the default and any JavaScript expression is allowed. For templates that originate from untrusted sources (end-user preferences, database-stored configuration, external feeds), use isc.dynRestricted(), or set dynRestricted:true on the instance to compile in restricted mode — only dot expressions, ternaries, and literal values are permitted. Function calls, assignment, bracket access, and similar constructs are rejected with a development-mode warning.

Disabling detection

Detection runs once per property value at create() time and is cheap, but for projects that prefer the verbose Class.dynamicProperties syntax or need backward compatibility during incremental adoption, detection can be turned off at three levels:
  • isc.dynamicTemplates = false — system-wide; the detection loop is skipped entirely
  • Class.useDynamicTemplates = false — per class, applies to all instances
  • useDynamicTemplates: false on create() — per instance

See also

ReactJSXIntegration — the same {expr} syntax in JSX string props binds to React state instead of ruleScope, so application markup is portable between React and non-React builds.