DataField

Overview

A DataField is a place-holder for dynamic content in a FormLayout. One FormLayout can use an arbitrary number of DataFields (0..n). TFORMer Designer requires that a DataField is defined before it can be used. This definition takes place directly in the FormLayout (in the case of a stand-alone FormLayout) or in a user-defined Project (or the GlobalProject ) of a Repository.

A DataField can be printed as text, as bar-code or may be used to provide the filename for image elements in the FormLayout. Besides this, a DataField can be used in element expressions and printing conditions.

Data Type

The type of a DataField influences its use in expressions within a FormLayout and the conversion method when reading a DataField from a JobData. 3 different data types are supported:

• eVarType_Text
  A text (string or character). This is the recommended TFormer_ProjectVarItGetType!
• eVarType_Long
  An integer number. When reading a DataField of this type from a JobData it is converted automatically to an integer. In case of conversion errors the result is 0 (no error or exception will be raised).
• eVarType_Float
  A floating point number. When reading a DataField of this type from a JobData it is converted automatically to a floating point number. In case of conversion errors the result is 0 (no error or exception will be raised).
• eVarType_Invalid
  Invalid, internal use only.

Naming Conventions

The name of a DataField must comply with JavaScript rules for valid identifiers (see Naming Rules). In short a name must begin with a letter or an underscore. Within the name letters, underscores and digits are allowed. Special characters (e.g. white spaces, tabs, hyphens, German Umlauts, ...) are invalid.

Usually DataField names are not suitable for representing them to end-users. Refer to additional properties like Caption, Description, Comment and DisplayOrder for such purposes.

Data Field Values

For printing a FormLayout it is required to provide the DataField values via JobData. When a JobData is used to pass data to TFORMer SDK and a DataField is not set by this JobData the value of the DataField will be an empty string ("") or 0 (see also TFormer_SetReuseValues).

Data Field Default Values

The DefaultValue is the standard value of a DataField. The DefaultValue is only used by TFORMer Designer.

Validating DataFields

Use ValidationRules for validating values for DataField objects.

ValidationRules are expressions which are used to check if the value of a DataField meets a certain criteria. Whenever a DataField value violates the assigned ValidationRule an error message is displayed (in TFORMer Designer) or an exception is raised (TFORMer SDK).

DataField Enumeration

In order to programmatically access the DataFields in a FormLayout you may either use the method TFormer_GetFirstProjectVarIt or you may iterate through all available DataField objects using TFormer_GetFirstProjectVarIt and TFormer_GetNextProjectVarIt. If you want to know, whether the returned DataField is actually used in the FormLayout use the method TFormer_ProjectVarItGetUsage.

To determine if a specific DataField is used in a FormLayout iterate all data-fields of the Project and query the usage:

  // Enumerate all DataFields in the Project
  HPROJECTVAR_ITERATOR  it                = TFormer_GetFirstProjectVarIt (hTForm, pszProjectName, &eCode);
  BOOL                  bProjectVarValid  = (it != NULL);
  LPCSTR                pszDataFieldName  = NULL;

  // TYPE_E_ELEMENTNOTFOUND should not be treated as error
  if (eCode == TYPE_E_ELEMENTNOTFOUND)
    eCode = ErrOk;  

  // iterate all DataFields  
  while (bProjectVarValid && (eCode == ErrOk))
  {
    // Query the DataField usage in the given FormLayout
    EVarUsage eVarUsage = TFormer_ProjectVarItGetUsage (hTForm, it, &eCode);      
    if ((eVarUsage == eVarUsage_Normal) && (eCode == ErrOk))
    {
      pszDataFieldName = TFormer_ProjectVarItGetName (it, &eCode);
      if (pszDataFieldName != NULL && eCode == ErrOk)
        printf ("  %s\n", pszDataFieldName);
    }

    // get next DataField
    bProjectVarValid = (TFormer_GetNextProjectVarIt (it) == ErrOk);
  }
  // release iterator
  TFormer_FreeProjectVarIt (it);