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:
    com.google.gwt.event.shared.HasHandlers

      public class UserFormula
      extends DataClass

  An object representing a user-created and user-modifiable formula, which can be created and edited with a FormulaBuilder either directly or via the `ListGrid.canAddFormulaFields` behavior.

  Note that the current implementation of UserFormula simply executes `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 that are not part of the standard or custom MathFunctions, this should not be relied upon, as future versions of the formula engine may prohibit such calls.

- - ### 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 and Description
    `UserFormula()`
    `UserFormula(com.google.gwt.core.client.JavaScriptObject jsObj)`
    `UserFormula(java.lang.String text)`
    `UserFormula(java.lang.String text, java.util.Map formulaVars)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.util.Map` | `getFormulaVars()` Object mapping from variable names to fieldNames.
    `static UserFormula` | `getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)`
    `java.lang.String` | `getText()` Formula to be evaluated.
    `UserFormula` | `setFormulaVars(java.util.Map formulaVars)` Object mapping from variable names to fieldNames.
    `UserFormula` | `setText(java.lang.String text)` Formula to be evaluated.

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

      `applyFactoryProperties, doAddHandler, fireEvent, getAttribute, getAttributeAsBoolean, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsDoubleArray, 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 Detail

    - #### UserFormula

          public UserFormula()

    - #### UserFormula

          public UserFormula(com.google.gwt.core.client.JavaScriptObject jsObj)

    - #### UserFormula

          public UserFormula(java.lang.String text)

    - #### UserFormula

          public UserFormula(java.lang.String text,
                             java.util.Map formulaVars)

  - ### Method Detail

    - #### getOrCreateRef

          public static UserFormula getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)

    - #### setFormulaVars

          public UserFormula setFormulaVars(java.util.Map formulaVars)

      Object mapping from variable names to fieldNames. All variable names must be single-letter capital characters (eg 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 `ListGridField.userFormula` context, field names are evaluated against the grid record.

      When used in `FormItem.formula` or `ListGridField.editorFormula` this property is not used for formula mapping. Instead, field names are evaluated directly against the current `rule context`.

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

    - #### getFormulaVars

          public java.util.Map getFormulaVars()

      Object mapping from variable names to fieldNames. All variable names must be single-letter capital characters (eg 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 `ListGridField.userFormula` context, field names are evaluated against the grid record.

      When used in `FormItem.formula` or `ListGridField.editorFormula` this property is not used for formula mapping. Instead, field names are evaluated directly against the current `rule context`.

      Returns:
        Current formulaVars value. Default value is null

    - #### setText

          public UserFormula setText(java.lang.String text)

      Formula to be evaluated.

      There are two contexts where a UserFormula is used: `ListGridField.userFormula` and `FormItem.formula` or `ListGridField.editorFormula`. For the grid field formula all variables used by the formula must be single-letter capital characters (eg 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 displayed.

      In the second usage context 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 MathFunctions or a custom\n function.

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

    - #### getText

          public java.lang.String getText()

      Formula to be evaluated.

      There are two contexts where a UserFormula is used: `ListGridField.userFormula` and `FormItem.formula` or `ListGridField.editorFormula`. For the grid field formula all variables used by the formula must be single-letter capital characters (eg 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 displayed.

      In the second usage context 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 MathFunctions or a custom\n function.

      Returns:
        Current text value. Default value is null