Merge branch 'ayduns-master-patch-86637' into 'master'

Update docs/api/v4/fields.md

See merge request documentation/docs/dev!1044

docs/api/v4/fields.md

@@ -8,15 +8,53 @@ In most cases the `values` refer to the database fields by the database field na
 
 ## Calculated Fields
 
-Calculated fields are not retrieved unless specifically requested as in some cases they are expensive.
+Calculated Fields are fields that are determined from other data. A few important things to remember:
+- they are a feature of APIv4 and so are not present in APIv3 or via BAO's.  
+- they are not retrieved unless specifically requested as they can be expensive.  
+- they are also available as tokens, for example when sending email.
 
-Adding calculated fields involves [creating a SpecProvider](https://github.com/civicrm/civicrm-core/pull/24992/files#diff-dced99ed6aa2dcd2a809d83dc354cb410e98c3f8f8e89813cba2623d5fc3b083)
-and once created they are also available as tokens (e.g when sending emails).
+Calculated fields can be based on:
+- a single field: `Contact.age` is calculated from the `Contact.birth_date` field and the current date.
+- multiple fields from the same record: `Contribution.tax_exclusive_amount` is the difference of `Contribution.total_amount` and `Contribution.tax_amount`.
+- a sub-query or join using other tables: `Contribution.balance_amount` is calculated by a query on other financial tables.
 
-As of writing calculated fields that ship with CiviCRM include 
+Calculated Fields are specified in `GetSpecProvider` files.  Look at the existing ones for examples in `<civi_root>/Civi/Api4/Service/Spec/Provider/*GetSpecProvider.php`
+
+The SpecProvider has 3 main parts: 
+- the field definition - creating a `FieldSpec` object.
+- the `applies()` function - limiting which entities and actions this applies to.
+- the SQL string - defining how to calculate the new field (but see below for Entity Refs).
+
+!!! tip "Hint"
+  When developing these Calculated Fields, use the debug feature of API4 Explorer to see the generated SQL.
+
+### Entity Refs
+
+One powerful feature of Calculated Fields is the ability to use them as Entity References.  All of the referenced entity's fields can be accessed without further definition of those fields.
+So for example, the Calculated Field `Contact.address_primary` links to the Contact's primary address (determined by joining to the `civicrm_address` table) which then provides access to `Contact.address_primary.city`.
+
+The SQL string defining the join for a reference like this moves to a file in `<civi_root>/Civi/Api4/Event/Subscriber/*SchemaMapSubscriber.php`
+
+For an example, study the implementation of `Contact.address_primary` in `ContactGetSpecProvider.php` and `ContactSchemaMapSubscriber.php` 
+
+!!! tip "Reminder"
+  Note that a cache clear is needed after making changes to the `*SchemaMapSubscriber.php` files.
+
+### Core Calculated Fields
+
+This section contains a listing of Calculated Fields in core.  Use them as inspiration!
+
+- `Activity.case_id` - provides the case that an activity is linked to
+- `Activity.source_contact_id`, `Activity.target_contact_id`, `Activity.assignee_contact_id` - contacts related to the activity
+- `Address.proximity` - (filter) determines whether an address is within a given distance of a location (see [example](https://github.com/civicrm/civicrm-core/pull/23597))
+- `Contact.age_years`- age of a contact (based on `birth_date`) in years
+- `Contact.groups` - (filter) determines whether a contact belongs to any of the specified groups
+- `Contact.address_primary, address_billing, email_primary, email_billing, phone_primary, phone_billing, im_primary, im_billing` - addresses associated with a contact 
+- `Contribution.balance_amount` - balance
+- `Contribution.paid_amount` - amount paid
+- `Contribution.tax_exclusive_amount` - total amount less the tax amount
+- `Domain.is_active` - is this the current active domain
+- `MessageTemplate.master_id` - the original version of a MessageTemplate if it has been modified
+
+Fields marked as '(filter)' can only be used to filter results.
 
-Contact.age
-Contribution.paid_amount
-Contribution.balance_amount
-Contribution.tax_exclusive_amount
-MessageTemplate.master_id