DataField Class Reference

Provides access to DataField information. More...

Public Member Functions
void	Dispose ()
	Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources. More...
string	GetDetails (DataFormat dataFormat)
	Gets the details of the DataField. More...
override string	ToString ()
	Returns a string representation of the instance. More...

Properties
string	Caption [get, set]
	Gets/Sets the caption of the DataField. More...
string	Comment [get, set]
	Gets/Sets the comment of the DataField. More...
bool	Criteria [get, set]
	Gets/Sets a flag indicating whether this DataField should be used as a criteria for a print-job. More...
int	CriteriaColumn [get, set]
	Gets/Sets the criteria column of the DataField. More...
string	CriteriaFormat [get, set]
	Gets/Sets the criteria format of the DataField. More...
string	DefaultValue [get, set]
	Gets/Sets the default value of the DataField. More...
string	Description [get, set]
	Gets/Sets the description of the DataField. More...
string	DisplayOrder [get, set]
	Gets/Sets the display order of the DataField. More...
string	Name [get, set]
	Gets/Sets the name of the DataField. More...
DataField	Next [get]
	Gets the next DataField defined in the Project. More...
DataFieldType	Type [get, set]
	Gets/Sets the type of the DataField. More...
string	ValidationMessage [get, set]
	Gets/Sets the validation message of the DataField. More...
string	ValidationRule [get, set]
	Gets/Sets the validation rule of the DataField. More...

Detailed Description

Provides access to DataField information.

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:

• Text
  A text (string or character). This is the recommended DataFieldType!
• 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).
• 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).
• 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 JobData.ReuseValues).

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 Project.GetDataField or you may iterate through all available DataField objects using Project.FirstDataField and DataField.Next. If you want to know, whether the returned DataField is actually used in the FormLayout use the method FormLayout.GetDataFieldUsage.

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
  for (DataField field = project.FirstDataField; field != null; field = field.Next)
  {
    // Query the DataField usage in the given FormLayout
    DataFieldUsage usage = formlayout.GetDataFieldUsage(field.Name);
    // may the DataField value be set (this depends on the usage of the DataField within the FormLayout)
    if (usage == DataFieldUsage.Normal)
    {
      // Do something
      Console.WriteLine(field.Name);
    }
  }

Attention

The DataField is only valid as long as it is available in the Project. If it is removed from the Project all instances of the DataField immediately become invalid.

Note

Thread-safety: A single instance of this class must not be used by different threads.

Member Function Documentation

Dispose()

void Dispose

(

)

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

GetDetails()

string GetDetails

(

DataFormat

dataFormat

)

Gets the details of the DataField.

Returns

The details of the DataField.

Parameters

dataFormat

Specifies the format of the data to be returned

ToString()

override string ToString

(

)

Returns a string representation of the instance.

Returns

A string representation of the instance

Property Documentation

Caption

string Caption

getset

Gets/Sets the caption of the DataField.

Returns

The caption of the DataField.

Comment

string Comment

getset

Gets/Sets the comment of the DataField.

Returns

The comment of the DataField.

Criteria

bool Criteria

getset

Gets/Sets a flag indicating whether this DataField should be used as a criteria for a print-job.

Returns

true if this DataField is used as a criteria

Attention

Internal use only

CriteriaColumn

int CriteriaColumn

getset

Gets/Sets the criteria column of the DataField.

Returns

The criteria column of the DataField.

Attention

Internal use only

CriteriaFormat

string CriteriaFormat

getset

Gets/Sets the criteria format of the DataField.

Returns

The criteria format of the DataField.

Attention

Internal use only

DefaultValue

string DefaultValue

getset

Gets/Sets the default value of the DataField.

Returns

The default value of the DataField.

See also

DataField

Description

string Description

getset

Gets/Sets the description of the DataField.

Returns

The description of the DataField.

DisplayOrder

string DisplayOrder

getset

Gets/Sets the display order of the DataField.

Returns

The display order of the DataField.

Name

string Name

getset

Gets/Sets the name of the DataField.

Returns

The name of the DataField.

See also

DataField

Next

DataField Next

get

Gets the next DataField defined in the Project.

A Project stores a list of DataField objects. You can use this method to iterate through the list. To retrieve the first DataField in the Project see Project.FirstDataField

Returns

The next DataField object in the list or null

Sample: Iterate DataFields in a Stand-Alone FormLayout

  // Retrieve the global Project 
  // A stand-alone FormLayout contains only the global Project, the global Project holds all DataField definitions
  Project project = repository.GlobalProject;
 
  // Retrieve the first DataField
  DataField datafield = project.FirstDataField;
  while (datafield != null)
  {
    // Your code follows
    Console.WriteLine (datafield.Name);    
 
    // Get the next DataField
    datafield = datafield.Next;
  }

Type

DataFieldType Type

getset

Gets/Sets the type of the DataField.

Returns

The type of the DataField.

See also

DataField

ValidationMessage

string ValidationMessage

getset

Gets/Sets the validation message of the DataField.

Returns

The validation message of the DataField.

See also

DataField

ValidationRule

string ValidationRule

getset

Gets/Sets the validation rule of the DataField.

Returns

The validation rule of the DataField.

See also

DataField