Property field are intended for use in document forms as described in Section 7.3.2, “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.