mirror of
https://github.com/farmOS/farmOS.git
synced 2024-02-23 11:37:38 +01:00
Document farm_field.factory service and move field type options info from fields.md.
This commit is contained in:
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
|
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:
|
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:
|
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()`.
|
||||||
|
@ -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
|
## Select options
|
||||||
|
|
||||||
Certain fields on assets and logs include a list of options to select from.
|
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');
|
$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 a new issue