add Note as an afformEntity

[briennekordis]

Overview

In continuing to expand FormBuilder's use cases, this PR is in response to a feature request to add the Note entity on afforms, so that users can have a place to enter text without having to create a custom field.

Before

The Note entity is not currently available to add to an afform.

After

Note Fields are now available for the Contact entity.

Comments

This PR only allows for Notes to be added to a Contact. This PR's approach could be used to also make the Note entity available for other "higher level" entities, such as Contributions.

[civibot]

Thank you for contributing to CiviCRM! ❤️ We will need to test and review the PR. 👷

Introduction for new contributors

• If this is your first PR, an admin will greenlight automated testing with the command ok to test or add to whitelist.
• A series of tests will automatically run. You can see the results at the bottom of this page (if there are any problems, it will include a link to see what went wrong).
• A demo site will be built where anyone can try out a version of CiviCRM that includes your changes.
• If this process needs to be repeated, an admin will issue the command test this please to rerun tests and build a new demo site.
• Before this PR can be merged, it needs to be reviewed. Please keep in mind that reviewers are volunteers, and their response time can vary from a few hours to a few weeks depending on their availability and their knowledge of this particular part of CiviCRM.
• A great way to speed up this process is to "trade reviews" with someone - find an open PR that you feel able to review, and leave a comment like "I'm reviewing this now, could you please review mine?" (include a link to yours). You don't have to wait for a response to get started (and you don't have to stop at one!) the more you review, the faster this process goes for everyone 😄
• To ensure that you are credited properly in the final release notes, please add yourself to contributor-key.yml
• For more information about contributing, see CONTRIBUTING.md.

Quick links for reviewers

• ➡️ Demo site for this PR
• 📖 Review standards
• 🗒️ Review template (brief or verbose)

[colemanw]

Looks very good @briennekordis.
This can be merged, and as a follow-up, consider switching from physical .aff.* files to using an event subscriber that loops through the option values for Note.entity_table and provides an afform for each one. Here's an example:

civicrm-core/ext/afform/core/Civi/Api4/Action/Afform/Get.php

Lines 111 to 179 in 05a37a7

	/**
	* Generates afform blocks from custom field sets.
	*
	* @param \Civi\Core\Event\GenericHookEvent $event
	* @throws \CRM_Core_Exception
	*/
	public static function getCustomGroupBlocks($event) {
	// Early return if blocks are not requested
	if ($event->getTypes && !in_array('block', $event->getTypes, TRUE)) {
	return;
	}
	$getNames = $event->getNames;
	$getLayout = $event->getLayout;
	$groupNames = [];
	$afforms =& $event->afforms;
	foreach ($getNames['name'] ?? [] as $name) {
	if (strpos($name, 'afblockCustom_') === 0 && strlen($name) > 13) {
	$groupNames[] = substr($name, 14);
	}
	}
	// Early return if this api call is fetching afforms by name and those names are not custom-related
	if ((!empty($getNames['name']) && !$groupNames)
	|| (!empty($getNames['module_name']) && !strstr(implode(' ', $getNames['module_name']), 'afblockCustom'))
	|| (!empty($getNames['directive_name']) && !strstr(implode(' ', $getNames['directive_name']), 'afblock-custom'))
	) {
	return;
	}
	$customApi = CustomGroup::get(FALSE)
	->addSelect('name', 'title', 'help_pre', 'help_post', 'extends', 'max_multiple')
	->addWhere('is_multiple', '=', 1)
	->addWhere('is_active', '=', 1);
	if ($groupNames) {
	$customApi->addWhere('name', 'IN', $groupNames);
	}
	if ($getLayout) {
	$customApi->addSelect('help_pre', 'help_post');
	$customApi->addChain('fields', CustomField::get(FALSE)
	->addSelect('name')
	->addWhere('custom_group_id', '=', '$id')
	->addWhere('is_active', '=', 1)
	->addOrderBy('weight', 'ASC')
	);
	}
	foreach ($customApi->execute() as $custom) {
	$name = 'afblockCustom_' . $custom['name'];
	$item = [
	'name' => $name,
	'type' => 'block',
	'requires' => [],
	'title' => E::ts('%1 block', [1 => $custom['title']]),
	'description' => '',
	'is_dashlet' => FALSE,
	'is_public' => FALSE,
	'is_token' => FALSE,
	'permission' => 'access CiviCRM',
	'join_entity' => 'Custom_' . $custom['name'],
	'entity_type' => $custom['extends'],
	];
	if ($getLayout) {
	$item['layout'] = ($custom['help_pre'] ? '<div class="af-markup">' . $custom['help_pre'] . "</div>\n" : '');
	foreach ($custom['fields'] as $field) {
	$item['layout'] .= "<af-field name=\"{$field['name']}\" />\n";
	}
	$item['layout'] .= ($custom['help_post'] ? '<div class="af-markup">' . $custom['help_post'] . "</div>\n" : '');
	}
	$afforms[$name] = $item;
	}
	}

[colemanw]

retest this please

[briennekordis]

Looks very good @briennekordis. This can be merged, and as a follow-up, consider switching from physical .aff.* files to using an event subscriber that loops through the option values for Note.entity_table and provides an afform for each one. Here's an example:

civicrm-core/ext/afform/core/Civi/Api4/Action/Afform/Get.php

Lines 111 to 179 in 05a37a7

	/**
	* Generates afform blocks from custom field sets.
	*
	* @param \Civi\Core\Event\GenericHookEvent $event
	* @throws \CRM_Core_Exception
	*/
	public static function getCustomGroupBlocks($event) {
	// Early return if blocks are not requested
	if ($event->getTypes && !in_array('block', $event->getTypes, TRUE)) {
	return;
	}
	$getNames = $event->getNames;
	$getLayout = $event->getLayout;
	$groupNames = [];
	$afforms =& $event->afforms;
	foreach ($getNames['name'] ?? [] as $name) {
	if (strpos($name, 'afblockCustom_') === 0 && strlen($name) > 13) {
	$groupNames[] = substr($name, 14);
	}
	}
	// Early return if this api call is fetching afforms by name and those names are not custom-related
	if ((!empty($getNames['name']) && !$groupNames)
	|| (!empty($getNames['module_name']) && !strstr(implode(' ', $getNames['module_name']), 'afblockCustom'))
	|| (!empty($getNames['directive_name']) && !strstr(implode(' ', $getNames['directive_name']), 'afblock-custom'))
	) {
	return;
	}
	$customApi = CustomGroup::get(FALSE)
	->addSelect('name', 'title', 'help_pre', 'help_post', 'extends', 'max_multiple')
	->addWhere('is_multiple', '=', 1)
	->addWhere('is_active', '=', 1);
	if ($groupNames) {
	$customApi->addWhere('name', 'IN', $groupNames);
	}
	if ($getLayout) {
	$customApi->addSelect('help_pre', 'help_post');
	$customApi->addChain('fields', CustomField::get(FALSE)
	->addSelect('name')
	->addWhere('custom_group_id', '=', '$id')
	->addWhere('is_active', '=', 1)
	->addOrderBy('weight', 'ASC')
	);
	}
	foreach ($customApi->execute() as $custom) {
	$name = 'afblockCustom_' . $custom['name'];
	$item = [
	'name' => $name,
	'type' => 'block',
	'requires' => [],
	'title' => E::ts('%1 block', [1 => $custom['title']]),
	'description' => '',
	'is_dashlet' => FALSE,
	'is_public' => FALSE,
	'is_token' => FALSE,
	'permission' => 'access CiviCRM',
	'join_entity' => 'Custom_' . $custom['name'],
	'entity_type' => $custom['extends'],
	];
	if ($getLayout) {
	$item['layout'] = ($custom['help_pre'] ? '<div class="af-markup">' . $custom['help_pre'] . "</div>\n" : '');
	foreach ($custom['fields'] as $field) {
	$item['layout'] .= "<af-field name=\"{$field['name']}\" />\n";
	}
	$item['layout'] .= ($custom['help_post'] ? '<div class="af-markup">' . $custom['help_post'] . "</div>\n" : '');
	}
	$afforms[$name] = $item;
	}
	}

Ah, thank you, that's good to know about!