Property field are intended for use in document forms as described in Section 7.3.3, “Customizing Document Forms”. To ensure the most convenient usage, custom property fields should adhere to the standard name for config options.
The option propertyName should define the name of the property to show and
edit in the property field. While you can use a different name for this option,
your document form definition become more readable when you use the
propertyName option uniformly.
Further conventions arise, because a document form forwards a number of configuration option to all included components, that is, to all included property fields. By using the standard option names, you avoid repetitions and accidental omissions.
The option bindTo is a value expression that evaluates
to the object that defines the property.
If possible, the field should not assume that this object implements the
Content interface, but rather that it is a bean with a property
properties that stores another bean that contains the
property given as propertyName.
That will eventually make it possible to reuse the field for workflow forms.
For the same reason, a property field
should not access built-in properties like creationDate
and others. It should also refrain from performing other operations like
checkIn on the returned bean.
This is no significant limitation, because property fields are typically
reading and writing schema-defined properties, only.
When property fields are used in the left half of the version comparison view,
they are bound to an object that does implement the Content interface,
but that is actually wrapping a version.
In this case, the built-in properties of Content are present,
but might not always return the value you expect.
It always claims to be checked in and it returns the properties
of the historic version, even though it reports the id of the
versioned content.
When accessing only the schema-defined properties,
property field will behave as expected.
If the value expression provided through the option
forceReadOnlyValueExpression evaluates to true,
the property field should switch to a read-only mode.
In this mode it should be possible to view property values
and preferably to copy them,
but it should be impossible to make updates.
The value expression is set to true when a document form
is used on the left side of a master side-by-side view or
a version comparison view.
The property field itself must take other reasons into account
that might make the field read-only.
To this end, the utility methods isReadOnly and
createReadOnlyValueExpression in the class
PropertyEditorUtil support you in making a property field read-only.
The class PropertyEditorUtil also contains methods
for localizing property names, types, and so on.
 |  |  |
 |