DataField Class Reference

Provides access to DataField information. More...

Public Member Functions
void	dispose () throws TFormerException
	Releases the resources allocated by this instance. More...
void	dump (PrintStream s) throws IOException, TFormerException
	Dumps the current instance into a text stream. More...
String	getCaption () throws TFormerException
	Gets the caption of the DataField. More...
String	getComment () throws TFormerException
	Gets the comment of the DataField. More...
boolean	getCriteria () throws TFormerException
	Gets a flag indicating whether this DataField should be used as a criteria for a print-job. More...
int	getCriteriaColumn () throws TFormerException
	Gets the criteria column of the DataField. More...
String	getCriteriaFormat () throws TFormerException
	Gets the criteria format of the DataField. More...
String	getDefaultValue () throws TFormerException
	Gets the default value of the DataField. More...
String	getDescription () throws TFormerException
	Gets the description of the DataField. More...
String	getDisplayOrder () throws TFormerException
	Gets the display order of the DataField. More...
String	getName () throws TFormerException
	Gets the name of the DataField. More...
DataField	getNext () throws TFormerException
	Gets the next DataField defined in the Project. More...
DataFieldType	getType () throws TFormerException
	Gets the type of the DataField. More...
String	getValidationMessage () throws TFormerException
	Gets the validation message of the DataField. More...
String	getValidationRule () throws TFormerException
	Gets the validation rule of the DataField. More...
void	setCaption (String sCaption) throws TFormerException
	Sets the caption of the DataField. More...
void	setComment (String sComment) throws TFormerException
	Sets the comment of the DataField. More...
void	setCriteria (boolean bCriteria) throws TFormerException
	Sets a flag indicating whether this DataField should be used as a criteria for a print-job. More...
void	setCriteriaColumn (int nCriteriaColumn) throws TFormerException
	Sets the criteria column of the DataField. More...
void	setCriteriaFormat (String sCriteriaFormat) throws TFormerException
	Sets the criteria format of the DataField. More...
void	setDefaultValue (String sDefaultValue) throws TFormerException
	Sets the default value of the DataField. More...
void	setDescription (String sDescription) throws TFormerException
	Sets the description of the DataField. More...
void	setDisplayOrder (String sDisplayOrder) throws TFormerException
	Sets the display order of the DataField. More...
void	setName (String sName) throws TFormerException
	Sets the name of the DataField. More...
void	setType (DataFieldType dataFieldType) throws TFormerException
	Sets the type of the DataField. More...
void	setValidationMessage (String sValidationMessage) throws TFormerException
	Sets the validation message of the DataField. More...
void	setValidationRule (String sValidationRule) throws TFormerException
	Sets the validation rule of the DataField. More...
String	toString ()
	Returns a string representation of the instance. 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.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 Project.getDataField or you may iterate through all available DataField objects using Project.getFirstDataField and DataField.getNext. 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.getFirstDataField (); field != null; field = field.getNext ())
  {
    // Query the DataField usage in the given FormLayout
    DataFieldUsage usage = formlayout.getDataFieldUsage (field.getName ());

    // may the DataField value be set (this depends on the usage of the DataField within the FormLayout)
    if (usage == DataFieldUsage.Normal)
    {
      // Do something
    }
  }

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.

Member Function Documentation

void dispose

(

)

throws TFormerException

Releases the resources allocated by this instance.

Call this method in every case (even in case of exceptions) is this instance is not required anymore.

void dump

(

PrintStream

s

)

throws IOException, TFormerException

Dumps the current instance into a text stream.

Parameters

s	Instance of the stream

String getCaption

(

)

throws TFormerException

Gets the caption of the DataField.

Returns

The caption of the DataField

String getComment

(

)

throws TFormerException

Gets the comment of the DataField.

Returns

The comment of the DataField

boolean getCriteria

(

)

throws TFormerException

Gets 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

int getCriteriaColumn

(

)

throws TFormerException

Gets the criteria column of the DataField.

Returns

The criteria column of the DataField

Attention

Internal use only

String getCriteriaFormat

(

)

throws TFormerException

Gets the criteria format of the DataField.

Returns

The criteria format of the DataField

Attention

Internal use only

String getDefaultValue

(

)

throws TFormerException

Gets the default value of the DataField.

Returns

The default value of the DataField

See also

DataField

String getDescription

(

)

throws TFormerException

Gets the description of the DataField.

Returns

The description of the DataField

String getDisplayOrder

(

)

throws TFormerException

Gets the display order of the DataField.

Returns

The display order of the DataField

String getName

(

)

throws TFormerException

Gets the name of the DataField.

Returns

The name of the DataField

See also

DataField

DataField getNext

(

)

throws TFormerException

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.getFirstDataField.

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.getGlobalProject ();

  // Retrieve the first DataField
  DataField datafield = project.getFirstDataField ();
  while (datafield != null)
  {
    // Your code follows
    System.out.println (datafield.getName ());

    // Get the next DataField
    datafield = datafield.getNext ();
  }

DataFieldType getType

(

)

throws TFormerException

Gets the type of the DataField.

Returns

The type of the DataField

See also

DataField

String getValidationMessage

(

)

throws TFormerException

Gets the validation message of the DataField.

Returns

The validation message of the DataField

See also

DataField

String getValidationRule

(

)

throws TFormerException

Gets the validation rule of the DataField.

Returns

The validation rule of the DataField

See also

DataField

void setCaption

(

String

sCaption

)

throws TFormerException

Sets the caption of the DataField.

Parameters

sCaption

The caption of the DataField

void setComment

(

String

sComment

)

throws TFormerException

Sets the comment of the DataField.

Parameters

sComment

The comment of the DataField

void setCriteria

(

boolean

bCriteria

)

throws TFormerException

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

Parameters

bCriteria

true if this DataField should be used as a criteria

Attention

Internal use only

void setCriteriaColumn

(

int

nCriteriaColumn

)

throws TFormerException

Sets the criteria column of the DataField.

Parameters

nCriteriaColumn

The criteria column of the DataField

Attention

Internal use only

void setCriteriaFormat

(

String

sCriteriaFormat

)

throws TFormerException

Sets the criteria format of the DataField.

Parameters

sCriteriaFormat

The criteria format of the DataField

Attention

Internal use only

void setDefaultValue

(

String

sDefaultValue

)

throws TFormerException

Sets the default value of the DataField.

Parameters

sDefaultValue

The default value of the DataField

See also

DataField

void setDescription

(

String

sDescription

)

throws TFormerException

Sets the description of the DataField.

Parameters

sDescription

The description of the DataField

void setDisplayOrder

(

String

sDisplayOrder

)

throws TFormerException

Sets the display order of the DataField.

Parameters

sDisplayOrder

The display order of the DataField

void setName

(

String

sName

)

throws TFormerException

Sets the name of the DataField.

Parameters

sName

The name of the DataField

See also

DataField

void setType

(

DataFieldType

dataFieldType

)

throws TFormerException

Sets the type of the DataField.

Parameters

dataFieldType

The type of the DataField

See also

DataField

void setValidationMessage

(

String

sValidationMessage

)

throws TFormerException

Sets the validation message of the DataField.

Parameters

sValidationMessage

The validation message of the DataField

See also

DataField

void setValidationRule

(

String

sValidationRule

)

throws TFormerException

Sets the validation rule of the DataField.

Parameters

sValidationRule

The validation rule of the DataField

See also

DataField

String toString

(

)

Returns a string representation of the instance.

Returns

A string representation of the instance