Drupal migrations reference: List of subfields per field type

Enviado por dinarcon el Mar, 14/04/2020 - 09:00

In the previous article we explained the syntax used to write Drupal migrations. As part of the field mapping explanation, we talked about how to set subfields. This is a topic we have covered early in the 31 days of Drupal migrations series. On both occasions, we mentioned that finding out which subfields are available for a field type might require some Drupal development knowledge. To make the process easier, in today’s article we are presenting a reference of subfields provided by core and contributed modules.

Example migrations mapping of subfields

For each field type we will present: the module that provides it, its plugin ID and category, the class that defines it, the subfields available, and the default subfield if any. If a field has only one subfield, that will be its default. In some cases, there will be references to articles that cover migrating into those field types specifically.

As a refresher, if you want to find available subfields by yourself, you need to locate the class that provides the `FieldType` plugin and inspect its `schema` method. The latter defines the database columns used by the field to store its data. Because of object oriented practices, sometimes you need to look at the parent class to find all the subfields that are available. When migrating into subfields, you are actually migrating into those particular database columns. Any restriction set by the database schema needs to be respected.

Address field

Module: Address. Plugin ID: `address`. Category: Address.
Class: Drupal\address\Plugin\Field\FieldType\AddressItem
Related article: Migrating addresses into Drupal
Note: This field type does not have a default subfield.

List of subfields:

  1. `langcode`: The language code.
  2. `country_code`: The two-letter country code as defined by the ISO 3166 standard.
  3. `administrative_area`: The top-level administrative subdivision of the country (e.g., state or province).
  4. `locality`: The locality (i.e. city).
  5. `dependent_locality`: The dependent locality (i.e. neighbourhood).
  6. `postal_code`: The postal or ZIP code. It will be validated against `administrative_area` if validation patterns are available for that state or province.
  7. `sorting_code`: The sorting code.
  8. `address_line1`: The first line of the address block.
  9. `address_line2`: The second line of the address block.
  10. `organization`: The organization or company.
  11. `given_name`: The first name.
  12. `additional_name`: The middle name.
  13. `family_name`: The last name.

Country field

Module: Address. Plugin ID: `address_country`. Category: Address.
Class: Drupal\address\Plugin\Field\FieldType\CountryItem
Related article: Migrating addresses into Drupal

Subfield: `value` for the two-letter country code as defined by the ISO 3166 standard.

Zone field

Module: Address. Plugin ID: `address_zone`. Category: Address.
Class: Drupal\address\Plugin\Field\FieldType\ZoneItem
Related article: Migrating addresses into Drupal

Subfield: `value` for serialized version of a Zone object.

Boolean field

Module: Core library. Plugin ID: `boolean`. Category: General.
Class: Drupal\Core\Field\Plugin\Field\FieldType\BooleanItem

Subfield: `value` stores an integer number: 0 for FALSE and 1 for TRUE.

Number integer field

Module: Core library. Plugin ID: `integer`. Category: Number.
Class: Drupal\Core\Field\Plugin\Field\FieldType\IntegerItem

Subfield: `value` for the integer number.

Number float field

Module: Core library. Plugin ID: `float`. Category: Number.
Class: Drupal\Core\Field\Plugin\Field\FieldType\FloatItem

Subfield: `value` for the float number.

Number decimal field

Module: Core library. Plugin ID: `decimal`. Category: Number.
Class: Drupal\Core\Field\Plugin\Field\FieldType\DecimalItem

Subfield: `value` for the decimal number.

List integer field

Module: Options (Drupal core). Plugin ID: `list_integer`. Category: Number.
Class: Drupal\options\Plugin\Field\FieldType\ListIntegerItem

Subfield: `value` for the integer number. It is one of the keys in the “Allowed values list” of the field’s setting.

List float field

Module: Options (Drupal core). Plugin ID: `list_float`. Category: Number.
Class: Drupal\options\Plugin\Field\FieldType\ListFloatItem

Subfield: `value` for the float number. It is one of the keys in the “Allowed values list” of the field’s setting.

Text plain field

Module: Core library. Plugin ID: `string`. Category: Text.
Class: Drupal\Core\Field\Plugin\Field\FieldType\StringItem

Subfield: `value` for a short plain text. The maximum length is 255 characters unless a lower number is set in the field's storage settings.

Text plain, long field

Module: Core library. Plugin ID: `string_long`. Category: Text.
Class: Drupal\Core\Field\Plugin\Field\FieldType\StringLongItem

Subfield: `value` for a long plain text.

List text field

Module: Options (Drupal core). Plugin ID: `list_string`. Category: Text.
Class: Drupal\options\Plugin\Field\FieldType\ListStringItem

Subfield: `value` for the text. It is one of the keys in the “Allowed values list” of the field’s setting. The maximum length for a key is 255 characters.

Text formatted field

Module: Text (Drupal core). Plugin ID: `text`. Category: Text.
Class: Drupal\text\Plugin\Field\FieldType\TextItem
Default subfield: `value`

List of subfields:

  1. `value`: A short text. It can include markup. The maximum length is 255 characters unless a lower number is set in the field's storage settings.
  2. `format`: A string containing the machine name of the text format to use. For example: `plain_text`, `full_html`, `restricted_html`, and `basic_html`.

Text formatted, long field

Module: Text (Drupal core). Plugin ID: `text_long`. Category: Text.
Class: Drupal\text\Plugin\Field\FieldType\TextLongItem
Default subfield: `value`

List of subfields:

  1. `value`: The text. It can include markup.
  2. `format`: A string containing the machine name of the text format to use. For example: `plain_text`, `full_html`, `restricted_html`, and `basic_html`.

Text formatted, long with summary field

Module: Text (Drupal core). Plugin ID: `text_with_summary`. Category: Text.
Class: Drupal\text\Plugin\Field\FieldType\TextWithSummaryItem
Related article: Migrating formatted text
Default subfield: `value`

List of subfields:

  1. `value`: The full text. It can include markup.
  2. `summary`: The summary text. It can include markup.
  3. `format`: A string containing the machine name of the text format to use. For example: `plain_text`, `full_html`, `restricted_html`, and `basic_html`.

Comments field

Module: Comment (Drupal core). Plugin ID: `comment`. Category: General.
Class: Drupal\comment\Plugin\Field\FieldType\CommentItem

Subfield: `status` stores an integer number that indicates whether comments are allowed on the entity: 0 = no, 1 = closed (read only), 2 = open (read/write).

Datetime field

Module: Datetime (Drupal core). Plugin ID: `datetime`. Category: General.
Class: Drupal\datetime\Plugin\Field\FieldType\DateTimeItem
Related article: Migrating dates into Drupal

Subfield: `value` for the datetime value. It is a string similar to `2020-01-15T07:03:21`.

If you decide to only store the date, the string will be similar to `2020-01-15`.

Datetime range field

Module: Datetime Range (Drupal core). Plugin ID: `daterange`. Category: General.
Class: Drupal\datetime_range\Plugin\Field\FieldType\DateRangeItem
Related article: Migrating dates into Drupal
Default subfield: `value`

List of subfields:

  1. `value` The start datetime value. It is a string similar to `2020-01-15T07:03:21`.
  2. `end`: The end datetime value. It is a string similar to `2020-01-15T07:03:21`.

If you decide to only store the date, the string for both subfields will be similar to `2020-01-15`. If you decide to store all day, the `value` string will be similar to `2020-01-15T05:00:00` and the `end` string to `2020-01-17T04:59:59`.

Email field

Module: Core library. Plugin ID: `email`. Category: General.
Class: Drupal\Core\Field\Plugin\Field\FieldType\EmailItem

Subfield: `value` for the email address.

Module: Link (Drupal core). Plugin ID: `link`. Category: General.
Class: Drupal\link\Plugin\Field\FieldType\LinkItem
Related article: Understanding the syntax of Drupal migrations
Default subfield: `uri`

List of subfields:

  1. `uri`: A string for the link’s URI.
  2. `title`: A string for the link’s title.
  3. `options`: A serialized array of options for the link.

Telephone number field

Module: Telephone (Drupal core). Plugin ID: `telephone`. Category: Number.
Class: Drupal\telephone\Plugin\Field\FieldType\TelephoneItem

Subfield: `value` for the telephone number. It is a string of 256 characters maximum. For example: `+1 (508) 283-3557` or `1800-DRUPAL`.

Timestamp field

Module: Core library. Plugin ID: `timestamp`. Category: General.
Class: Drupal\Core\Field\Plugin\Field\FieldType\TimestampItem

Subfield: `value` for a UNIX timestamp value. It stores an integer in the range [-2147483648, 2147483648]. For example: 280299600. Note that the value can be negative.

Entity reference field including nodes, users, taxonomy terms, and media entities

Module: Core library. Plugin ID: `entity_reference`. Category: Reference.
Class: Drupal\Core\Field\Plugin\Field\FieldType\EntityReferenceItem

Subfield: `target_id` stores an integer representing the ID of the target entity: `nid`, `uid`, `tid`, `mid`, etc.

Entity reference file field

Module: File (Drupal core). Plugin ID: `file`. Category: Reference.
Class: Drupal\file\Plugin\Field\FieldType\FileItem
Related article: Migrating files and images into Drupal
Default subfield: `target_id`

List of subfields:

  1. `target_id`: An integer representing the ID of the target entity.
  2. `display`: An flag to control whether this file should be displayed when viewing content. Possible values are 0 and 1.
  3. `description`: A description of the file.

Entity reference image field

Module: Image (Drupal core). Plugin ID: `image`. Category: Reference.
Class: Drupal\image\Plugin\Field\FieldType\ImageItem
Related articles: Migrating files and images into Drupal, Migrating images using the image_import plugin, and Migrating images using the image_import plugin
Default subfield: `target_id`

List of subfields:

  1. `target_id`: An integer representing the ID of the target entity.
  2. `alt`: Alternative image text, for the image's 'alt' attribute.
  3. `title`: Image title text, for the image's 'title' attribute.
  4. `width`: The width of the image in pixels.
  5. `height`: The height of the image in pixels.

Entity reference revisions field including paragraphs

Module: Entity Reference Revisions. Plugin ID: `entity_reference_revisions`. Category: Reference revisions.
Class: Drupal\entity_reference_revisions\Plugin\Field\FieldType\EntityReferenceRevisionsItem
Related article: Introduction to paragraphs migrations in Drupal
Default subfield: `target_id`

List of subfields:

  1. `target_id`: An integer representing the ID of the target entity: `nid`, `uid`, `tid`, `fid`, etc.
  2. `target_revision_id`: An integer representing the revision ID of the target entity.

Fields hidden from the user interface

Drupal core includes more field types that are hidden from the user interface. That is, it is not possible to add them from a content type’s “Manage fields” tab. For brevity, their subfields will not be listed. Instead, each will have a link to its definition class. There you can inspect the `schema` method to obtain the list of subfields. As of this writing, the hidden fields are:

  1. `changed` provided by Drupal\Core\Field\Plugin\Field\FieldType\ChangedItem
  2. `created` provided by Drupal\Core\Field\Plugin\Field\FieldType\CreatedItem
  3. `file_uri` provided by Drupal\file\Plugin\Field\FieldType\FileUriItem
  4. `language` provided by Drupal\Core\Field\Plugin\Field\FieldType\LanguageItem
  5. `map` provided by Drupal\Core\Field\Plugin\Field\FieldType\MapItem
  6. `password` provided by Drupal\Core\Field\Plugin\Field\FieldType\PasswordItem
  7. `path` provided by Drupal\path\Plugin\Field\FieldType\PathItem
  8. `uri` provided by Drupal\Core\Field\Plugin\Field\FieldType\UriItem
  9. `uuid` provided by Drupal\Core\Field\Plugin\Field\FieldType\UuidItem

Subfields for other contributed modules

There are hundreds of modules that provide new field types. It would be impractical to list all of them here. As mentioned before, you need to find a field type’s definition class to know which subfields are available. Contributed modules would have these classes in their `/src/Plugin/Field/FieldType/` directory. The class itself will have the `@FieldType` annotation. For reference, below is a list of some contributed field types:

  1. Color Field module provides ColorFieldType.
  2. Geofield module provides GeofieldItem.
  3. Google Map Field module provides GoogleMapFieldType.
  4. Name Field module provides NameItem.
  5. Office Hours module provides OfficeHoursItem.
  6. Physical Fields module provides DimensionsItem and MeasurementItem.
  7. Viewfield module provides ViewfieldItem.

What did you learn in today’s article? Did you know that there were so many field types in Drupal core? Were you aware that some core field types are hidden from the user interface? Did you know how to find subfields for field types from contributed modules? Please share your answers in the comments. Also, we would be grateful if you shared this article with your friends and colleagues.

Etiquetas

Añadir nuevo comentario

Texto sin formato

  • No se permiten etiquetas HTML.
  • Saltos automáticos de líneas y de párrafos.
  • Las direcciones de correos electrónicos y páginas web se convierten en enlaces automáticamente.