DataElement Instance Methods

  • set(property, value)

Set the given property to the given value. This apparently simple method can trigger a variety of side effects, including intelligently converting key attributes to uppercase (which is the default unless turned off with the tabMenu.shouldNotAutoUppercase property). The method returns a boolean indicating whether the setter succeeded; reasons for failure include if the existing value is identical to the current value (this is needed to avoid needlessly marking the data element dirty), and if the mutation capacity would be exceeded.

Further, if the modified attribute represents a key value, the change is propagated recursively through all child data elements by matching the attribute names.

In addition, the original, unmodified, property value is retained for future reference, and can be accessed using the originalValue function.

  • originalValue(property)

Returns the original, unmodified value for the given property name. This is useful for user exit code implementing business rules that depend not only on the new attribute value but also the original value.

  • isNew()

Answers a boolean indicating whether this DataElement instance is new, e.g. created by the user. Persistent instances answer false. The method uses the _​originalIndex attribute to decide.

  • isPersistent()

The logical opposite of isNew(); answers true only for persistent data elements. Useful for avoiding excessive use of logical not (!) operators, thus clarifying the intentions of the code.

  • isDirty()

Answers a boolean indicating whether the message receiver data element or any descendant child data element is marked with the _​isDirty flag.

  • list(listName)

Answers the list (instance of List) corresponding to the given list name.

  • clearDirtyFlag()

Set the receiver's _​isDirty flag to false. Potentially dangerous because it subverts the systems automatic dirty tracking system.

  • canBecomeDirty(property, value)

Answers a boolean indicating whether the receiver can accept the given value for the given property. The method answers false for various reasons, including if the proposed value matches the previous vaule, the receiver is not dirty and its parent list may not become dirty, and the property is not known to the metadata.