Improve fields documentation #505
This commit is contained in:
commit
271caf0aea
|
@ -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)
|
- [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)
|
- [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)
|
- [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
|
### Fixed
|
||||||
|
|
||||||
|
|
|
@ -15,7 +15,10 @@ 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
|
types), then they should be added as "base fields" via
|
||||||
`hook_entity_base_field_info()`.
|
`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:
|
||||||
|
|
||||||
```php
|
```php
|
||||||
<?php
|
<?php
|
||||||
|
@ -24,12 +27,14 @@ use Drupal\Core\Entity\EntityTypeInterface;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Implements hook_entity_base_field_info().
|
* Implements hook_entity_base_field_info().
|
||||||
|
* NOTE: Replace 'mymodule' with the module name.
|
||||||
*/
|
*/
|
||||||
function mymodule_entity_base_field_info(EntityTypeInterface $entity_type) {
|
function mymodule_entity_base_field_info(EntityTypeInterface $entity_type) {
|
||||||
$fields = [];
|
$fields = [];
|
||||||
|
|
||||||
// Add a new string field to Log entities.
|
// 'log' specifies the entity type to apply to.
|
||||||
if ($entity_type->id() == 'log') {
|
if ($entity_type->id() == 'log') {
|
||||||
|
// Options for the new field. See Field options below.
|
||||||
$options = [
|
$options = [
|
||||||
'type' => 'string',
|
'type' => 'string',
|
||||||
'label' => t('My new field'),
|
'label' => t('My new field'),
|
||||||
|
@ -39,6 +44,7 @@ function mymodule_entity_base_field_info(EntityTypeInterface $entity_type) {
|
||||||
'view' => 10,
|
'view' => 10,
|
||||||
],
|
],
|
||||||
];
|
];
|
||||||
|
// NOTE: Replace 'myfield' with the internal name of the field.
|
||||||
$fields['myfield'] = \Drupal::service('farm_field.factory')->baseFieldDefinition($options);
|
$fields['myfield'] = \Drupal::service('farm_field.factory')->baseFieldDefinition($options);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -56,10 +62,15 @@ then they should be added as "bundle fields" via
|
||||||
deprecated in favor of a core Drupal hook in the future. See core issue:
|
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)
|
[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
|
The format for bundle field definitions is identical to base field definitions
|
||||||
(above), but the `bundleFieldDefinition()` method must be used instead of
|
(above), but the `bundleFieldDefinition()` method must be used instead of
|
||||||
`baseFieldDefinition()`.
|
`baseFieldDefinition()`.
|
||||||
|
|
||||||
|
To get started, place the following in the `[modulename].module` file:
|
||||||
|
|
||||||
```php
|
```php
|
||||||
<?php
|
<?php
|
||||||
|
|
||||||
|
@ -67,12 +78,15 @@ use Drupal\Core\Entity\EntityTypeInterface;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Implements hook_farm_entity_bundle_field_info().
|
* Implements hook_farm_entity_bundle_field_info().
|
||||||
|
* NOTE: Replace 'mymodule' with the module name.
|
||||||
*/
|
*/
|
||||||
function mymodule_farm_entity_bundle_field_info(EntityTypeInterface $entity_type, $bundle) {
|
function mymodule_farm_entity_bundle_field_info(EntityTypeInterface $entity_type, $bundle) {
|
||||||
$fields = [];
|
$fields = [];
|
||||||
|
|
||||||
// Add a new string field to Input Logs.
|
// Add a new string field to Input Logs. 'log' specifies the entity type and
|
||||||
|
// 'input' specifies the bundle.
|
||||||
if ($entity_type->id() == 'log' && $bundle == 'input') {
|
if ($entity_type->id() == 'log' && $bundle == 'input') {
|
||||||
|
// Options for the new field. See Field options below.
|
||||||
$options = [
|
$options = [
|
||||||
'type' => 'string',
|
'type' => 'string',
|
||||||
'label' => t('My new field'),
|
'label' => t('My new field'),
|
||||||
|
@ -82,6 +96,7 @@ function mymodule_farm_entity_bundle_field_info(EntityTypeInterface $entity_type
|
||||||
'view' => 10,
|
'view' => 10,
|
||||||
],
|
],
|
||||||
];
|
];
|
||||||
|
// NOTE: Replace 'myfield' with the internal name of the field.
|
||||||
$fields['myfield'] = \Drupal::service('farm_field.factory')->bundleFieldDefinition($options);
|
$fields['myfield'] = \Drupal::service('farm_field.factory')->bundleFieldDefinition($options);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@ -126,6 +141,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
|
in the active configuration of the site. (**Warning** changing core types runs
|
||||||
the risk of conflicting with future farmOS updates).
|
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:
|
### Examples:
|
||||||
|
|
||||||
#### Flag
|
#### Flag
|
||||||
|
@ -140,11 +159,13 @@ dependencies:
|
||||||
enforced:
|
enforced:
|
||||||
module:
|
module:
|
||||||
- my_module
|
- my_module
|
||||||
id: monitor
|
id: organic
|
||||||
label: Monitor
|
label: Organic
|
||||||
entity_types: null
|
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 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
|
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
|
shown in the select field and other parts of the UI, and `entity_types`, which
|
||||||
|
@ -194,6 +215,8 @@ id: field
|
||||||
label: Field
|
label: Field
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Note that the file name is in the form `farm_land.land_type.[id].yml`.
|
||||||
|
|
||||||
#### Structure type
|
#### Structure type
|
||||||
|
|
||||||
The "Structure" module in farmOS provides a "Building" type like this:
|
The "Structure" module in farmOS provides a "Building" type like this:
|
||||||
|
@ -211,6 +234,8 @@ id: building
|
||||||
label: Building
|
label: Building
|
||||||
```
|
```
|
||||||
|
|
||||||
|
Note that the file name is in the form `farm_structure.structure_type.[id].yml`.
|
||||||
|
|
||||||
#### Lab test type
|
#### Lab test type
|
||||||
|
|
||||||
The "Lab test" module in farmOS provides a "Soil test" type like this:
|
The "Lab test" module in farmOS provides a "Soil test" type like this:
|
||||||
|
@ -228,6 +253,8 @@ id: soil
|
||||||
label: Soil test
|
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 type
|
||||||
|
|
||||||
ID tag types are similar to Flags, in that they have an `id` and `label`. They
|
ID tag types are similar to Flags, in that they have an `id` and `label`. They
|
||||||
|
@ -237,7 +264,7 @@ certain types of assets.
|
||||||
For example, an "Ear tag" type, provided by the "Animal asset" module, only
|
For example, an "Ear tag" type, provided by the "Animal asset" module, only
|
||||||
applies to "Animal" assets:
|
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
|
```yaml
|
||||||
langcode: en
|
langcode: en
|
||||||
|
@ -253,5 +280,7 @@ bundles:
|
||||||
- animal
|
- 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`.
|
If you want the tag type to apply to all assets, set `bundles: null`.
|
||||||
(or can it just be omitted?)
|
(or can it just be omitted?)
|
||||||
|
|
|
@ -74,6 +74,80 @@ $all_inventory = \Drupal::service('asset.inventory')->getInventory($asset);
|
||||||
$gallons_of_fertilizer = \Drupal::service('asset.inventory')->getInventory($asset, 'volume', 'gallons');
|
$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
|
## Group membership service
|
||||||
|
|
||||||
**Service name**: `group.membership`
|
**Service name**: `group.membership`
|
||||||
|
|
Loading…
Reference in New Issue