Understanding Field Values

Knowing a bit more about how field values are represented in JavaScript could make a difference in how you write script.  Today I’ll give an overview of how field values are processed.   For starters, here is a sample form that will illustrate some of the points I make below.

But first, we need to be mindful that picture clauses (patterns) impact our field values.  A brief recap of the various picture clauses (patterns) we use:

  • format pattern: Used to format field data for display
  • edit pattern: Used to format field data when the user has set focus in a field and is about to edit a value.
  • data pattern: Used to format field data when it is saved to XML.
  • validation patten: Used for field validation — does not impact field value

With that background, let’s look at the properties available:

field.rawValue: the field value in its raw form. i.e. a format that has no patterns applied and a format that is consistent across locales and is suitable for calculations.

field.editValue: The field value when formatted with the edit pattern. If there is no edit pattern you will get a reasonable default — usually the rawValue, except in the case of a date field where you’ll get some locale-sensitive short date format.  If a field value cannot be formatted using the edit pattern, then field.editValue will revert to be the same as field.rawValue.

field.formattedValue: Same as field.editValue except using the display pattern.

Some miscellaneous facts about field values:

  • field.editValue and field.formattedValue always return a string. If the field is null, these will return an empty string
  • rawValue returns a JavaScript type corresponding to the kind of field.  e.g. A text field is a string, a numeric/decimal field is a number
  • when a field is empty, rawValue will always be null
  • rawValue is what will be stored in the XML by default (assuming no data pattern has been specified)
  • There are two ways to check for a null value:
    • field.rawValue === null
    • field.isNull
  • The rawValue of a date field does not have a type date.  We chose to represent dates as a string — in the form that they will be saved.  The format used for the string is YYYY-MM-DD.
  • If you use JavaScript typeof to determine what kind of a value a field has, be aware that typeof(null) returns “object”

Knowing all this, there are some implications for the code you write:

  • If you need a JavaScript Date from a date field, you can use this function:
    function ConvertDate(sDate) {
       if (sDate === null) {
          return null;
       }
       var parts = sDate.split("-");
       // Convert strings to numbers by putting them in math expressions
       // Convert month to a zero-based number
       return new Date(parts[0] * 1, parts[1] - 1, parts[2] * 1);
    };
                
  • You should never code: field.rawValue.toString()
    This will result in a JavaScript error when the field is null.
  • If you want an expression that always returns a string, never null, use field.editValue or field.formattedValue
  • I often see code in the form:
    if (field.rawValue == null || field.rawValue == “”) { … }
    This is unnecessary.  Use one of the following:
    if (field.isNull) { … }
    if (field.rawValue === null) { … }
  • If you prefer not to use a validation pattern, you can validate a field using the display picture.  Use this validation script:
    this.formattedValue !== this.rawValue;

5 Responses to Understanding Field Values

  1. Hi John,

    I’m having trouble getting your Javascript date conversion expression to work on the server. It works fine when the calc is set to run at client, but fails when the calc is set to run at server. I get “Invalid Date”.

    Could it be because the version of Javascript running on the server is different than the one running in Acrobat/Reader?

    Rob

    • Rob:
      Sigh. You’re right. I suspect the JavaScript authors would love to have a “do over” when it comes to the Date implementation. There’s incredible variation between browser implementations — and as it turns out between our own client and server.
      Unfortunately, a more portable expression is much more verbose. If you still want a one-liner, you can use:
      dateField.rawValue ? (function(a) {return new Date(a[0]*1, a[1]-1, a[2]*1);})(dateField.rawValue.split(“-“)) : null;

      Doesn’t exactly roll off the fingertips.

      If you want something less cryptic, you could write a function:
      function ConvertDate(sDate) {
        if (sDate === null) {
          return null;
        }
        var parts = sDate.split(“-“);
        return new Date(parts[0] * 1, parts[1] – 1, parts[2] * 1);
      }

  2. Dave says:

    Hi John,

    I’ve been trying to find out the allowable ranges for numeric and decimal fields, which seems harder than I expected as it doesn’t seem to be documented anywhere I have looked. But I have noticed that strange things start to happen in my forms after users enter values greater than 999,999,999,999,999. How are these values handled internally.

    Thanks

    Dave

  3. Pingback: How to validate a date in a validation script | free icons download