From e08ee2f46712793fdaf42e6b7390e616d8a469ac Mon Sep 17 00:00:00 2001 From: jgOhYeah <33143109+jgOhYeah@users.noreply.github.com> Date: Sat, 19 Feb 2022 16:56:02 +1100 Subject: [PATCH 1/7] Fixed organic flag field example code Appeared to be a copy / paste and not modified at one point. Fixed it after reading https://farmos.discourse.group/t/custom-module-help/1149. --- docs/development/module/fields.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/development/module/fields.md b/docs/development/module/fields.md index ce87e9524..68f0cbc90 100644 --- a/docs/development/module/fields.md +++ b/docs/development/module/fields.md @@ -140,8 +140,8 @@ dependencies: enforced: module: - my_module -id: monitor -label: Monitor +id: organic +label: Organic entity_types: null ``` From e1b7d418937fadbfe79e7bbe361eeb5bc8eb25d2 Mon Sep 17 00:00:00 2001 From: jgOhYeah <33143109+jgOhYeah@users.noreply.github.com> Date: Mon, 28 Feb 2022 16:51:48 -0500 Subject: [PATCH 2/7] Fixed ear tag type example code --- docs/development/module/fields.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/development/module/fields.md b/docs/development/module/fields.md index 68f0cbc90..8b1cb34b2 100644 --- a/docs/development/module/fields.md +++ b/docs/development/module/fields.md @@ -237,7 +237,7 @@ certain types of assets. For example, an "Ear tag" type, provided by the "Animal asset" module, only applies to "Animal" assets: -`animal/config/install/farm_flag.flag.ear_tag.yml` +`animal/config/install/farm_id_tag.id_tag.ear_tag.yml` ```yaml langcode: en From 9c2affa744c07bcc6ffa02a15aebe8f345efb3d7 Mon Sep 17 00:00:00 2001 From: jgOhYeah <33143109+jgOhYeah@users.noreply.github.com> Date: Sat, 19 Feb 2022 10:02:19 +1100 Subject: [PATCH 3/7] Added comments showing what to change in examples. --- docs/development/module/fields.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/docs/development/module/fields.md b/docs/development/module/fields.md index 8b1cb34b2..01c57da1d 100644 --- a/docs/development/module/fields.md +++ b/docs/development/module/fields.md @@ -15,7 +15,9 @@ 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. + +To get started, place the following in the `[modulename].module` file: ```php id() == 'log') { + // Options for the new field. See Field options below. $options = [ 'type' => 'string', 'label' => t('My new field'), @@ -39,6 +43,7 @@ function mymodule_entity_base_field_info(EntityTypeInterface $entity_type) { 'view' => 10, ], ]; + // NOTE: Replace 'myfield' with the internal name of the field. $fields['myfield'] = \Drupal::service('farm_field.factory')->baseFieldDefinition($options); } @@ -60,6 +65,8 @@ The format for bundle field definitions is identical to base field definitions (above), but the `bundleFieldDefinition()` method must be used instead of `baseFieldDefinition()`. +To get started, place the following in the `[modulename].module` file: + ```php id() == 'log' && $bundle == 'input') { + // Options for the new field. See Field options below. $options = [ 'type' => 'string', 'label' => t('My new field'), @@ -82,6 +92,7 @@ function mymodule_farm_entity_bundle_field_info(EntityTypeInterface $entity_type 'view' => 10, ], ]; + // NOTE: Replace 'myfield' with the internal name of the field. $fields['myfield'] = \Drupal::service('farm_field.factory')->bundleFieldDefinition($options); } From c3f7d79ebddfec1ed2747d707188a57b2af8efc5 Mon Sep 17 00:00:00 2001 From: jgOhYeah <33143109+jgOhYeah@users.noreply.github.com> Date: Sat, 19 Feb 2022 21:49:07 +1100 Subject: [PATCH 4/7] Added notes on file naming for select options --- docs/development/module/fields.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/development/module/fields.md b/docs/development/module/fields.md index 01c57da1d..1c2485109 100644 --- a/docs/development/module/fields.md +++ b/docs/development/module/fields.md @@ -137,6 +137,10 @@ Existing options can be overridden or removed by editing/deleting the entities in the active configuration of the site. (**Warning** changing core types runs the risk of conflicting with future farmOS updates). +Note that the file name is important and must follow a specific pattern. This +is generally in the form `[select_module_name].[select_field].[id].yml`. See +the examples for more info. + ### Examples: #### Flag @@ -156,6 +160,8 @@ label: Organic entity_types: null ``` +Note that the file name is in the form `farm_flag.flag.[id].yml`. + The most important parts are the `id`, which is a unique machine name for the flag, `label`, which is the human readable/translatable label that will be shown in the select field and other parts of the UI, and `entity_types`, which @@ -205,6 +211,8 @@ id: field label: Field ``` +Note that the file name is in the form `farm_land.land_type.[id].yml`. + #### Structure type The "Structure" module in farmOS provides a "Building" type like this: @@ -222,6 +230,8 @@ id: building label: Building ``` +Note that the file name is in the form `farm_structure.structure_type.[id].yml`. + #### Lab test type The "Lab test" module in farmOS provides a "Soil test" type like this: @@ -239,6 +249,8 @@ id: soil label: Soil test ``` +Note that the file name is in the form `farm_lab_test.lab_test_type.[id].yml`. + #### ID tag type ID tag types are similar to Flags, in that they have an `id` and `label`. They @@ -264,5 +276,7 @@ bundles: - animal ``` +Note that the file name is in the form `farm_flag.flag.ear_tag.[id].yml`. + If you want the tag type to apply to all assets, set `bundles: null`. (or can it just be omitted?) From 918bfa85180f6e0179e81bd87806227ac249937b Mon Sep 17 00:00:00 2001 From: jgOhYeah <33143109+jgOhYeah@users.noreply.github.com> Date: Fri, 18 Feb 2022 23:11:48 +1100 Subject: [PATCH 5/7] Added documentation on field options --- docs/development/module/fields.md | 115 ++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) diff --git a/docs/development/module/fields.md b/docs/development/module/fields.md index 1c2485109..df8178fd4 100644 --- a/docs/development/module/fields.md +++ b/docs/development/module/fields.md @@ -100,6 +100,121 @@ 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. From 1a6689dd5aef665534fb7f0ef7f4159e9afabb0f Mon Sep 17 00:00:00 2001 From: Michael Stenta Date: Wed, 13 Apr 2022 10:57:44 -0400 Subject: [PATCH 6/7] Document farm_field.factory service and move field type options info from fields.md. --- docs/development/module/fields.md | 121 ++-------------------------- docs/development/module/services.md | 74 +++++++++++++++++ 2 files changed, 79 insertions(+), 116 deletions(-) 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` From 622f6e33a06bbddbd227bc9b5d69931c8f73ff7e Mon Sep 17 00:00:00 2001 From: Michael Stenta Date: Wed, 13 Apr 2022 11:10:53 -0400 Subject: [PATCH 7/7] Add changelog for PR #505. --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index c1be95e3e..69f9874e4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - [Issue #3270561: Upgrade to gin beta](https://www.drupal.org/project/farm/issues/3270561) - [Separate Docker image build from testing jobs in run-test.yml workflow #522](https://github.com/farmOS/farmOS/pull/522) - [Merge test and release workflows into a unified delivery workflow #523](https://github.com/farmOS/farmOS/pull/523) +- [Improve fields documentation #505](https://github.com/farmOS/farmOS/pull/505) ### Fixed