diff --git a/docs/development/module/fields.md b/docs/development/module/fields.md index df8178fd4..9dbce09ba 100644 --- a/docs/development/module/fields.md +++ b/docs/development/module/fields.md @@ -15,7 +15,8 @@ If the field should be added to all bundles of a given entity type (eg: all log types), then they should be added as "base fields" via `hook_entity_base_field_info()`. -A `farm_field.factory` helper service is provided to make this easier. +A `farm_field.factory` helper service is provided to make this easier. For more +information on how this works, see [Field factory service](/development/module/services/#field-factory-service). To get started, place the following in the `[modulename].module` file: @@ -61,6 +62,9 @@ then they should be added as "bundle fields" via deprecated in favor of a core Drupal hook in the future. See core issue: [https://www.drupal.org/node/2346347](https://www.drupal.org/node/2346347) +A `farm_field.factory` helper service is provided to make this easier. For more +information on how this works, see [Field factory service](/development/module/services/#field-factory-service). + The format for bundle field definitions is identical to base field definitions (above), but the `bundleFieldDefinition()` method must be used instead of `baseFieldDefinition()`. @@ -100,121 +104,6 @@ function mymodule_farm_entity_bundle_field_info(EntityTypeInterface $entity_type } ``` -## Field options - -The following keys are available to use when specifying fields: - -- `label`: What the field should be called when displayed to the user. -- `description`: A description of the field and how to use it. -- `computed`: Whether the field is computed. -- `required`: Specify this to force the user to enter a value into this - field. -- `revisionable`: Make the field revisionable, unless told otherwise. -- `cardinality`: Set cardinality, if specified. If neither `cardinality` - or `multiple` is specified, this defaults to 1. -- `multiple`: If `cardinality` is not specified and `multiple` is, set - the cardinality to unlimited. -- `translatable`: Only makes the field translatable if it is specified. -- `default_value_callback`: Sets the default value callback, if specified. -- `type`: The datatype of the field, represented as a string. Click one of - the following or scroll down for additional options relating to each specific - type: - - [`boolean`](#boolean) - - [`entity_reference`](#entity-reference) - - [`entity_reference_revisions`](#entity-reference-revisions) - - [`file`](#file-and-image) - - [`image`](#file-and-image) - - [`fraction`](#fraction) - - [`geofield`](#geofield) - - [`id_tag`](#id-tag) - - [`inventory`](#inventory) - - [`list_string`](#list-string) - - [`string`](#string) - - [`string_long`](#long-string) - - [`timestamp`](#timestamp) - -- `hidden`: Hide the field in form and view displays, if specified. The - hidden option can either be set to `true`, which will hide it in both form and - view displays, or it can be set to `form` or `view`, which will only hide - it in the form or view display. -- `form_display_options` & `view_display_options`: Override form and - view display options, if specified. -- `weight`: Contains an associative array with the keys `form` and - `view`, giving hints on whereabouts the field should appear (See the - examples). - -### Type specific options - -#### Boolean - -Currently there are no boolean-specific options. - -#### Entity reference - -- `target_type`: Required. What sort of entity the reference should be - targeting. This can be one of: - - `asset` - - `log` - - `taxonomy_term` - - `user` - - `data_stream` -- `target_bundle`: Used when `target_type` is set to `asset` or - `taxonomy_term`. Used to specify the bundle to look for. -- `auto_create`: Used when `target_type` is set to `taxonomy_term`. If - `auto_create` is set, term references will be created automatically if not - already defined. - -#### Entity reference revisions - -- `target_type`: Required. This currently must be `quantity`. - -#### File and image - -- `file_directory`: The directory that the image will be uploaded to in - relation to the private file system path. If not set, this will be - `farm/[date:custom:Y]-[date:custom:m]`. -- For images, the allowed file extensions are `png`, `gif`, `jpg` and `jpeg`. -- For other files, the allowed file extensions are `csv`, `doc`, `docx`, `gz`, - `geojson`, `gpx`, `kml`, `kmz`, `logz`, `mp3`, `odp`, `ods`, `odt`, `ogg`, - `pdf`, `ppt`, `pptx`, `tar`, `tif`, `tiff`, `txt`, `wav`, `xls`, `xlsx` and - `zip`. - -#### Fraction - -Currently there are no fraction-specific options. - -#### Geofield - -Currently there are no geofield-specific options. - -#### ID tag - -Currently there are no ID tag-specific options. - -#### Inventory - -Currently there are no inventory-specific options. - -#### List string - -- `allowed_values`: Optionally specify allowed values. -- `allowed_values_function`: Optionally specify a function that returns - the allowed values. - -#### String - -Maximum length of 255 characters. Currently there are no string-specific -coptions. - -#### Long string - -This is for longer messages than the string type. Currently there are no long -string-specific options. - -#### Timestamp - -Currently there are no long timestamp-specific options. - ## Select options Certain fields on assets and logs include a list of options to select from. diff --git a/docs/development/module/services.md b/docs/development/module/services.md index 58690db6a..c6fffd141 100644 --- a/docs/development/module/services.md +++ b/docs/development/module/services.md @@ -74,6 +74,80 @@ $all_inventory = \Drupal::service('asset.inventory')->getInventory($asset); $gallons_of_fertilizer = \Drupal::service('asset.inventory')->getInventory($asset, 'volume', 'gallons'); ``` +## Field factory service + +**Service name**: `farm_field.factory` + +The field factory service provides two methods to make the process of creating +Drupal entity base and bundle field definitions easier and more consistent in +farmOS. This is used by modules that add [fields](/development/module/fields) +to [entity types](/development/module/entities). + +Base fields are added to *all* bundles of a given entity type (eg: all logs). +Bundle fields are only added to *specific* bundles (eg: only "Input" logs). + +Using this service is optional. It simply generates instances of Drupal core's +`BaseFieldDefinition` class or the Entity API module's `BundleFieldDefinition` +class, with farmOS-specific opinions to help enforce some consistency among +farmOS core and contrib modules. You can create instances of these field +definition classes directly instead of using the farmOS field factory service. +Or you can take the object produced by the service and customize it further +using standard Drupal field definition methods. This service is provided only +as a shortcut. + +For more information on Drupal core's field definition API, see +[Drupal FieldTypes, FieldWidgets and FieldFormatters]([Drupal core field type](https://www.drupal.org/docs/drupal-apis/entity-api/fieldtypes-fieldwidgets-and-fieldformatters)) + +**Methods**: + +`baseFieldDefinition($options)` - Generates a base field definition, given an +array of options (see below). + +`bundleFieldDefinition($options)` - Generates a bundle field definition, given +an array of options (see below). + +**Options**: + +Both methods expect an array of field definition options. These include: + +- `type` (required) - The field data type. Each type may require additional + options. Supported types include: + - `boolean` - True/false checkbox. + - `entity_reference` - Reference other entities. Additional options: + - `target_type` (required) - The entity type to reference (eg: `asset`, + `log`, `plan`) + - `target_bundle` (optional) - The allowed target bundle. For example, + a `target_type` of `asset` and a `target_bundle` of `animal` would + limit references to animal assets. + - `auto_create` (optional) Only used when `target_type` is set to + `taxonomy_term`. If `auto_create` is set, term references will be + created automatically if the term does not exist. + - `file` - File upload. + - `fraction` - High-precision decimal number storage. + - `geofield` - Geometry on a map. + - `image` - Image upload. + - `list_string` - Select list with allowed values. Additional options: + - `allowed_values` - An associative array of allowed values. + - `allowed_values_function` - The name of a function that returns an + associative array of allowed values. + - `string_long` - Unformatted text field of unlimited length. + - `text_long` - Formatted text field of unlimited length. + - `timestamp` - Date and time. +- `label` - The field label. +- `description` - The field description. +- `required` - Whether the field is required. +- `multiple` - Whether the field should allow multiple values. Defaults to + `FALSE`. +- `cardinality` - How many values are allowed (eg: `1` for single value + fields, `-1` for unlimited values). This is an alternative to `multiple`, + and will take precedence if it is set. Defaults to `1`. + +Other options are available for more advanced use-cases. Refer to the +[FarmFieldFactory](https://github.com/farmOS/farmOS/blob/2.x/modules/core/field/src/FarmFieldFactory.php) +class to understand how they work. + +For more information and example code, see [Adding fields](/development/module/fields). + ## Group membership service **Service name**: `group.membership`