
package com.smartgwt.client.docs;

/**
 * <h3>Dynamic Templates</h3>
 * Dynamic templates let Smart GWT property values include &#123;expr&#125; expression
 *  delimiters that are re-evaluated when their inputs change. The expression
 *  <code>&#123;Customer.name&#125;</code> inside a property value resolves the path
 *  <code>Customer.name</code> 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.
 *  <P>
 *  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.
 *  <P>
 *  <h3>&#123;expr&#125; syntax</h3>
 *  Expressions are wrapped in braces:
 *  <pre>
 *    isc.Button.create({ title: "Save &#123;Customer.name&#125;'s data" });
 *    isc.Layout.create({ layoutStartMargin: isc.dynamic("form.values.margin + 10") });
 *  </pre>
 *  To include a literal brace in the output, double it: <code>&#123;&#123;</code> produces
 *  <code>&#123;</code> and <code>&#125;&#125;</code> produces <code>&#125;</code>.
 *  <P>
 *  Brace delimiters were chosen over JavaScript's template literal
 *  <code>&#36;&#123;&#125;</code> 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.
 *  <P>
 *  <h3>Where templates can appear</h3>
 * Properties typed {@link com.smartgwt.client.docs.DynString} or {@link
 * com.smartgwt.client.docs.DynHTMLString} accept
 *  &#123;expr&#125; templates directly &mdash; no wrapper required. Examples include
 * {@link com.smartgwt.client.widgets.Button#getTitle Button.title}, {@link
 * com.smartgwt.client.widgets.grid.ListGridField#getCellTemplate ListGridField.cellTemplate}, and
 * {@link com.smartgwt.client.widgets.Canvas#getContents Canvas.contents}. On
 *  any other property, wrap the value with one of the marker functions to opt in:
 *  <ul>
 * <li>{@link com.smartgwt.client.util.isc#dyn isc.dyn()} &mdash; string template producing a
 * reactive string</li>
 * <li>{@link com.smartgwt.client.util.isc#dynamic isc.dynamic()} &mdash; inline expression
 * returning a typed value
 *  (number, boolean, etc.)</li>
 * <li>{@link com.smartgwt.client.util.isc#dynRestricted isc.dynRestricted()} &mdash; string
 * template compiled in restricted
 *  mode (see security)</li>
 * <li>{@link com.smartgwt.client.util.isc#dynOnce isc.dynOnce()} &mdash; evaluated once at
 * create() time, no reactive
 *  listener</li>
 *  </ul>
 *  <P>
 *  <h3>Security: full vs. restricted mode</h3>
 *  Templates compile to JavaScript via <code>new Function()</code>, 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 {@link
 * com.smartgwt.client.util.isc#dynRestricted isc.dynRestricted()}, or set
 *   dynRestricted:true on the instance to compile in restricted
 *  mode &mdash; only dot expressions, ternaries, and literal values are permitted.
 *  Function calls, assignment, bracket access, and similar constructs are rejected with a
 *  development-mode warning.
 *  <P>
 *  <h3>Disabling detection</h3>
 *  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:
 *  <ul>
 *  <li><code>isc.dynamicTemplates = false</code> &mdash; system-wide; the
 *  detection loop is skipped entirely</li>
 *  <li> Class.useDynamicTemplates = false
 *  &mdash; per class, applies to all instances</li>
 *  <li><code>useDynamicTemplates: false</code> on  create()
 *  &mdash; per instance</li>
 *  </ul>
 *  <P>
 *  <h3>See also</h3>
 * {@link com.smartgwt.client.docs.ReactJSXIntegration} &mdash; the same &#123;expr&#125; syntax
 * in JSX string
 *  props binds to React state instead of ruleScope, so application markup is portable
 *  between React and non-React builds.
 */
public interface DynamicTemplates {
}
