Apostrophe 3 Documentation

# array

An array field has its own field schema and allows the user to add one or more entries that use the fields in that schema. The overall field is stored in the database as an array of an object for each entry.

This is useful for collections of structured data that clearly belong to a parent document but won't have relationships to other documents, such as multiple sets of contact information for business locations or tabs in a widget.

See the relationship field if you exclusively, or primarily, need to indentify a series of other pieces or pages.

# Module field definition

// Configuring the `contactInfo` array field in a module's `fields.add` subsection:
contactInfo: {
  label: 'Contact information',
  type: 'array',
  titleField: 'city',
  fields: {
    add: {
      city: {
        type: 'string',
        label: 'City'
      },
      email: {
        type: 'email',
        label: 'Email address'
      }
    }
  }
}

# Settings

# Required

Property Type Default Description
label String n/a Sets the visible label for the field in the UI
type String n/a Specifies the field type (array for this type)
fields Object n/a The field schema for the array items. See below.

# Optional

Property Type Default Description
def Array n/a The default value for the field. It must comply with the array fields schema.
help String n/a Help text for the content editor
htmlHelp String n/a Help text with support for HTML markup
if Object {} Conditions to meet before the field is active. See the guide for details.
inline Boolean false If true, array fields are edited inline with others, not in a separate dialog box.
style String n/a Only if inline is true. If set to table, the schema will be displayed as an HTML table
min Integer n/a The minimum number of entries required in the array
max Integer n/a The maximum number of entries allowed in the array
required Boolean false If true, the field is mandatory
readOnly Boolean false If true, prevents the user from editing the field value
titleField String n/a The name of one of the array schema fields. If provided, the user interface will use the value of that field as a label for the array tabs.
draggable Boolean true If false, array items cannot be reordered using drag and drop feature.
whenEmpty Object n/a Displays a label and icon if no array items have been added

NOTE

  • If there is no titleField value, the items are numbered.
  • Setting titleField is recommended to improve clarity for content editors.
  • titleField can access relationship sub-field documents by using dot notation (e.g., _team[0].mascot).

# inline

Set inline: true on an array field to edit the array inline with the rest of the fields, rather than in a separate dialog box. This works best with a small number of fields in the array.

You can also control whether each item has a toggle to expand it, or is always displayed in fully expanded form.

By default, if inline: true is set and there are fewer than three fields, each item is fully expanded. You can change this by explicitly setting the inline option to inline: { alwaysExpand: false } or inline: { alwaysExpand: true }.

# whenEmpty

If no array items have been added and the array has inline: true, the whenEmpty setting supplies an object consisting of a label and icon that are displayed to the editor until items are added. The label property takes a localizable string, while the icon property takes an icon that has already been registered (opens new window) or is registered through a module icons property (opens new window).

{
  whenEmpty: {
    label: 'apostrophe:whemEmpty',
    icon: 'file-document-icon'
  }
}

# Configuring the array field schema

Array field schemas are generally configured the same way as the module's overall field schema is configured. The module's schema is configured in its fields section's add subsection. Similarly, array field schema are configured in a fields property, using its add subproperty to configure the actual fields. Both use the field names as keys in the add object. Both can contain all field types, including nested array fields.

Array schema configuration differs from module schema configuration in that array schemas do not use group or remove settings.

# Use in templates

Nunjucks provides the {% for %} template tag (opens new window) to loop over arrays. This is the most common way to traverse the array field data and sub-fields.

<ul>
{% for contact in data.piece.contactInfo %}
  <li>{{ contact.city }}: {{ contact.email }}</li>
{% endfor %}
</ul>

← attachment →