Package com.smartgwt.client.widgets

# Class UserFormula

java.lang.Object
com.smartgwt.client.core.JsObject
com.smartgwt.client.core.DataClass
com.smartgwt.client.widgets.UserFormula

All Implemented Interfaces:
  `HasHandlers`

public class UserFormula extends DataClass
An object representing a user-created formula.

Note that the current implementation of formulas simply executes the `text` as a JavaScript string after making special variables and methods available to the formula. It is safe to allow users to define formulas for themselves (since an end user can always execute whatever JavaScript they want via the browser's built-in developer tools), and is safe to allow formulas to be shared between trusted users. However it would not be safe to allow an untrusted user to create formulas that are shared to other users.

Also, while the current implementation would allow creation of a formula that calls JavaScript functions which are not part of the standard or custom `MathFunctions`, this behavior should not be relied upon, as future versions of the formula engine may prohibit such calls.

`ListGrid`s additionally allow the formula to be user-modifiable, with the formula created and edited with a FormulaBuilder, either directly or via the `ListGrid.canAddFormulaFields` behavior.

See Also:
  - `FieldGeneration overview and related methods`

- ## Field Summary

  ### Fields inherited from class com.smartgwt.client.core.DataClass

  `factoryCreated, factoryProperties`

  ### Fields inherited from class com.smartgwt.client.core.JsObject

  `jsObj`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `UserFormula()`
  `UserFormula(JavaScriptObject jsObj)`
  `UserFormula(String text)`
  `UserFormula(String text, Map formulaVars)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Map`
  `getFormulaVars()`
  Object mapping from variable names to field names.
  `static UserFormula`
  `getOrCreateRef(JavaScriptObject jsObj)`
  `String`
  `getText()`
  Formula to be evaluated.
  `UserFormula`
  `setFormulaVars(Map formulaVars)`
  Object mapping from variable names to field names.
  `UserFormula`
  `setText(String text)`
  Formula to be evaluated.

  ### Methods inherited from class com.smartgwt.client.core.DataClass

  `applyFactoryProperties, doAddHandler, fireEvent, getAttribute, getAttributeAsBoolean, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsDoubleArray, getAttributeAsElement, getAttributeAsFloat, getAttributeAsInt, getAttributeAsIntArray, getAttributeAsJavaScriptObject, getAttributeAsLong, getAttributeAsMap, getAttributeAsObject, getAttributeAsRecord, getAttributeAsString, getAttributeAsStringArray, getAttributes, getHandlerCount, isFactoryCreated, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttributeAsJavaObject, setFactoryCreated`

  ### Methods inherited from class com.smartgwt.client.core.JsObject

  `equals, getJsObj, hashCode, isCreated, setJavaScriptObject, setJsObj`

  ### Methods inherited from class java.lang.Object

  `clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### UserFormula

    public UserFormula()

  - ### UserFormula

    public UserFormula(JavaScriptObject jsObj)

  - ### UserFormula

    public UserFormula(String text)

  - ### UserFormula

    public UserFormula(String text, Map formulaVars)

- ## Method Details

  - ### getOrCreateRef

    public static UserFormula getOrCreateRef(JavaScriptObject jsObj)

  - ### setFormulaVars

    public UserFormula setFormulaVars(Map formulaVars)
    Object mapping from variable names to field names. All variable names must be single capital letters (e.g. A). For example, for a formula that should divide the field "population" over the field "area", the formula might be "E/L" and formula vars would be:

            Map vars = new HashMap();
            vars.put("E", "population");
            vars.put("L", "area");

    When used in the context of grid or detail viewer fields, field names are evaluated against the record.

    When used in the context of forms and editing, this property is not used for formula mapping. Instead, field names are evaluated directly against the current `rule context`.

    Formulas built by a FormulaBuilder for a `ListGrid` will normally not define this property and the field names will be used directly, unless useSingleLetterKey is `true`. However, the Builder may add mapping keys to avoid collisions with registered math functions. When directly using field names in a formula, any mapping keys you add to avoid collisions should contain the string "Field" so that the Smart GWT Framework can detect when single-letter keys are not in use.

    So, for example, if your grid contains a field "max" and you want to use it in a formula, your userFormula might look something like:

          {
              text: "max(maxField, 1000)",
              formulaVars: {
                  maxField: "max"
              }
          }

    .. where the formula also uses the built-in `math function` max().
    Parameters:
      `formulaVars` - New formulaVars value. Default value is null
    Returns:
      `UserFormula` instance, for chaining setter calls

  - ### getFormulaVars

    public Map getFormulaVars()
    Object mapping from variable names to field names. All variable names must be single capital letters (e.g. A). For example, for a formula that should divide the field "population" over the field "area", the formula might be "E/L" and formula vars would be:

            Map vars = new HashMap();
            vars.put("E", "population");
            vars.put("L", "area");

    When used in the context of grid or detail viewer fields, field names are evaluated against the record.

    When used in the context of forms and editing, this property is not used for formula mapping. Instead, field names are evaluated directly against the current `rule context`.

    Formulas built by a FormulaBuilder for a `ListGrid` will normally not define this property and the field names will be used directly, unless useSingleLetterKey is `true`. However, the Builder may add mapping keys to avoid collisions with registered math functions. When directly using field names in a formula, any mapping keys you add to avoid collisions should contain the string "Field" so that the Smart GWT Framework can detect when single-letter keys are not in use.

    So, for example, if your grid contains a field "max" and you want to use it in a formula, your userFormula might look something like:

          {
              text: "max(maxField, 1000)",
              formulaVars: {
                  maxField: "max"
              }
          }

    .. where the formula also uses the built-in `math function` max().
    Returns:
      Current formulaVars value. Default value is null

  - ### setText

    public UserFormula setText(String text)
    Formula to be evaluated.

    There are two contexts where a `UserFormula` is used: `ListGridField.userFormula` / `DetailViewerField.userFormula` and `FormItem.formula` or `ListGridField.editorFormula`. For the grid/detail viewer field formula, all variables used by the formula must be single capital letters (e.g. A). These are derived from field values for the record in question - see `formulaVars`.

    In addition to these variables, the keyword `record` may be used to refer directly to the record for which the formula is being evaluated.

    In the context of forms and editing, variables are dot-separated (.) names representing the nested hierarchy path to the desired value within the `rule context`. No mapping with `formulaVars` is needed.

    The formula text must be valid JavaScript code and may only call either the built-in `math functions` or custom functions.

    This attribute is writable only in `ListGrid`s. Applications must call either `ListGrid.setUserFormula()` or `ListGrid.setUserFormulaText()` to re-evaluate the formula.

    Parameters:
      `text` - New text value. Default value is null
    Returns:
      `UserFormula` instance, for chaining setter calls

  - ### getText

    public String getText()
    Formula to be evaluated.

    There are two contexts where a `UserFormula` is used: `ListGridField.userFormula` / `DetailViewerField.userFormula` and `FormItem.formula` or `ListGridField.editorFormula`. For the grid/detail viewer field formula, all variables used by the formula must be single capital letters (e.g. A). These are derived from field values for the record in question - see `formulaVars`.

    In addition to these variables, the keyword `record` may be used to refer directly to the record for which the formula is being evaluated.

    In the context of forms and editing, variables are dot-separated (.) names representing the nested hierarchy path to the desired value within the `rule context`. No mapping with `formulaVars` is needed.

    The formula text must be valid JavaScript code and may only call either the built-in `math functions` or custom functions.

    This attribute is writable only in `ListGrid`s. Applications must call either `ListGrid.setUserFormula()` or `ListGrid.setUserFormulaText()` to re-evaluate the formula.

    Returns:
      Current text value. Default value is null