Document farm_field.factory service and move field type options info from fields.md.
This commit is contained in:
Michael Stenta
parent
918bfa8518
commit
1a6689dd5a
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
|
|
|
|||
Loading…
Reference in New Issue