Field

The Field class represents a property that a record may have. It is analogous to a table column, or—in Salesforce—an object field.

We refer to Fields when we are inspecting the Schema, or shape, of records for a particular table or object. You will encounter this Valence class if you are implementing the SchemaAdapter interface.

Fields are constructed using a builder pattern that uses a fluent interface to make it simple to construct Field instances with varying degrees of complexity.

You get a FieldBuilder by calling Field.create() and passing the API name of the Field you are constructing. This is the only required property, but it’s an important one. This string value is expected to match exactly to what is used on the records that will be retrieved from, and given to, your Adapter.

Simple Field Example

valence.Field firstNameField = valence.Field.create('firstName').withLabel('First Name').build();

More Complex Field Example

valence.Field startDateField = valence.Field.create('startDate')
    .withLabel('Start Date')
    .withDescription('What day this subscription was first activated')
    .withType('string')
    .withFormat('yyyy-MM-dd')
    .withExampleValue('2017-01-24')
    .build();

Nested Data Shapes

Sometimes you will need to work with more complex schema involving collections and nested data structures.

For this you will take advantage of setMap(), setList(), and addChild().

Let’s look at the code for describing the following data shape:

{
        "Name" : "Acme",
        "Type" : "Financial",
        "Website" : "acme.com",
        "Employees" : [
                {
                        "FirstName" : "Julie",
                        "LastName" : "Smith"
                },
                {
                        "FirstName" : "Thomas",
                        "LastName" : "Lincoln"
                }
        ],
        "Address" : {
                "Street" : "123 Main St",
                "City" : "Urbanville"
        }
}

Field.create('Employees').withDescription('Workers at this company').setList(true, false)
    .addChild(Field.create('FirstName').withLabel('First Name').withDescription('First name of the person').withExampleValue('Julie').withType('String').build())
    .addChild(Field.create('LastName').withLabel('Last Name').withDescription('Last name of the person').withExampleValue('Smith').withType('String').build())
    .build()

{
        "Name" : "Acme",
        "Type" : "Financial",
        "Website" : "acme.com",
        "Employees" : [
                {
                        "FirstName" : "Julie",
                        "LastName" : "Smith"
                },
                {
                        "FirstName" : "Thomas",
                        "LastName" : "Lincoln"
                }
        ],
        "Address" : {
                "Street" : "123 Main St",
                "City" : "Urbanville"
        }
}

Field.create('Address').setMap(true, false)
    .addChild(Field.create('Street').withExampleValue('123 Main St').withType('String').build())
    .addChild(Field.create('City').withExampleValue('Urbanville').withType('String').build())
    .build()

Tip

setMap() and setList() take an additional parameter to indicate if the field is “lazy”. A lazy field has more structure beneath it, but you are not adding it right now with addChild(). This is intended to be paired with LazyLoadSchemaAdapter so Valence users can drill down into your data structure as they need do.

Properties

Data Type	Class Property	Builder Method	Description
String	name		Required. Expected to match actual record field names.
String	label	withLabel(String label)	User-friendly label for this field.
String	description	withDescription(String description)	Description of the field’s purpose.
String	exampleValue	withExampleValue(String exampleValue)	An example value to help give a user context. Truncates to 20 characters.
String	defaultValue	withDefaultValue(String defaultValue)	The default value that will be used if this field is left blank. Truncates to 20 characters.
String	type	withType(String type)	The data type of the field. Truncates to 20 characters.
String	format	withFormat(String format)	The format of the value, if applicable. Truncates to 20 characters.
Boolean	isRequired	setRequired(Boolean isRequired)	True if this field must be present on every record.
Boolean	isCreateable	setCreateable(Boolean isCreateable)	True if this field can be set on record creation.
Boolean	isUpdateable	setEditable(Boolean isEditable)	True if this field can be set on record update.
Boolean	isEditable	setEditable(Boolean isEditable)	True if either isCreateable or isUpdateable have been set. Can also be set independently.
Boolean	isMap	setMap(Boolean isMap, Boolean isLazy)	True if this Field in the schema is a Map of other Fields (so, keyed)
Boolean	isList	setList(Boolean isList, Boolean isLazy)	True if this Field is a List of other Fields (no keys)
Boolean	isLazy		True if this List/Map is not going to have children set right now, but could have them lazily loaded later
		addChild(Field child)	Use this to nest fields under other fields in a hierarchy.