Document adding new bundles and fields.

docs/development/module/entities.md

@@ -0,0 +1,106 @@
+# Entity types
+
+Assets, logs, plans, taxonomy terms, users, etc are all types of "entities" in
+farmOS/Drupal terminology. Entities can have sub-types called "bundles", which
+represent "bundles of fields". Some fields may be common across all bundles of
+a given entity type, and some fields may be bundle-specific.
+
+## Adding asset, log, and plan types
+
+Asset types, log types, and plan types can be provided by adding two files to a
+module:
+
+1. An entity type config file (YAML), and:
+2. A bundle plugin class (PHP).
+
+For example, the "Activity" log type is provided as follows:
+
+`config/install/log.type.activity.yml`:
+
+```yaml
+langcode: en
+status: true
+dependencies:
+  enforced:
+    module:
+      - farm_activity
+id: activity
+label: Activity
+description: ''
+name_pattern: 'Activity log [log:id]'
+workflow: log_default
+new_revision: true
+```
+
+`src/Plugin/Log/LogType/Activity.php`:
+
+```php
+<?php
+
+namespace Drupal\farm_activity\Plugin\Log\LogType;
+
+use Drupal\farm_log\Plugin\Log\LogType\LogTypeBase;
+
+/**
+ * Provides the activity log type.
+ *
+ * @LogType(
+ *   id = "activity",
+ *   label = @Translation("Activity"),
+ * )
+ */
+class Activity extends LogTypeBase {
+
+}
+```
+
+## Bundle fields
+
+Bundles can declare field definitions in their plugin class via the
+`buildFieldDefinitions()` method.
+
+A `farm_field.factory` helper service is provided to make this easier.
+
+The Equipment asset type does this to add "Manufacturer", "Model", and
+"Serial number" fields:
+
+```php
+  /**
+   * {@inheritdoc}
+   */
+  public function buildFieldDefinitions() {
+    $fields = parent::buildFieldDefinitions();
+    $field_info = [
+      'manufacturer' => [
+        'type' => 'string',
+        'label' => $this->t('Manufacturer'),
+        'weight' => [
+          'form' => -20,
+          'view' => -50,
+        ],
+      ],
+      'model' => [
+        'type' => 'string',
+        'label' => $this->t('Model'),
+        'weight' => [
+          'form' => -15,
+          'view' => -40,
+        ],
+      ],
+      'serial_number' => [
+        'type' => 'string',
+        'label' => $this->t('Serial number'),
+        'weight' => [
+          'form' => -10,
+          'view' => -30,
+        ],
+      ],
+    ];
+    foreach ($field_info as $name => $info) {
+      $fields[$name] = \Drupal::service('farm_field.factory')->bundleFieldDefinition($info);
+    }
+    return $fields;
+  }
+```
+
+For more information, see [Adding fields](/development/module/fields).

docs/development/module/fields.md

@@ -1,5 +1,51 @@
 # Fields
 
+## Adding fields
+
+A module may add additional fields to assets, logs, and other entity types in
+farmOS.
+
+The following documents how to add fields to existing entity types. See
+[Entity types](/development/module/entities) to understand how to create new
+asset, log, and plan types with custom fields on them.
+
+### Base fields
+
+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:
+
+```php
+<?php
+
+use Drupal\Core\Entity\EntityTypeInterface;
+
+/**
+ * Implements hook_entity_base_field_info().
+ */
+function mymodule_entity_base_field_info(EntityTypeInterface $entity_type) {
+  $fields = [];
+
+  // Add a new string field to Log entities.
+  if ($entity_type->id() == 'log') {
+    $options = [
+      'type' => 'string',
+      'label' => t('My new field'),
+      'description' => t('My field description.'),
+      'weight' => [
+        'form' => 10,
+        'view' => 10,
+      ],
+    ];
+    $fields['myfield'] = \Drupal::service('farm_field.factory')->baseFieldDefinition($options);
+  }
+
+  return $fields;
+}
+```
+
 ## Select options
 
 Certain fields on assets and logs include a list of options to select from.
@@ -95,4 +141,5 @@ bundles:
   - animal
 ```
 
-If you want the tag type to apply to all assets, set `bundle: null`.
+If you want the tag type to apply to all assets, set `bundles: null`.
+(or can it just be omitted?)

mkdocs.yml

@@ -7,6 +7,7 @@ nav:
       - Changes: development/api/changes.md
     - Module:
       - Getting started: development/module/index.md
+      - Entities: development/module/entities.md
       - Fields: development/module/fields.md
       - OAuth: development/module/oauth.md
       - Roles: development/module/roles.md