AA-Events/docs/superpowers/plans/2026-07-02-event-contact-email.md

Event Contact Email Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Add an optional event contact email field and display valid values as protected email links on single-event pages.

Architecture: Register event_contact_email in the built-in ACF group and read the same field name from built-in or admin-created groups. Keep output in the single-event template, sanitizing before conditional rendering and applying WordPress escaping at the attribute and visible-HTML boundaries.

Tech Stack: PHP 7.4+, WordPress template APIs, ACF PRO, existing dependency-free PHP tests

---

Task 1: Register the Contact Email Field

Files:

• Modify: includes/acf-fields.php

• Modify: tests/bootstrap.php

• Modify: tests/test-acf-fields.php

• Step 1: Write the failing registration test

Extend the ACF test double to capture acf_add_local_field_group() arguments. In tests/test-acf-fields.php, clear admin groups, call events_register_acf_fields(), locate the field named event_contact_email, and assert this exact contract:

array(
	'key'      => 'field_aa_events_contact_email',
	'label'    => 'Contact Email',
	'name'     => 'event_contact_email',
	'type'     => 'email',
	'required' => 0,
)

• Step 2: Run the suite and verify RED

Run: php tests/run.php

Expected: FAIL because no field named event_contact_email is registered.

• Step 3: Add the built-in field

Add the optional ACF email field after location/URL/address details in includes/acf-fields.php, using the stable key and contract above plus standard empty wrapper/default/placeholder settings.

• Step 4: Verify GREEN

Run:

php tests/run.php
php -l includes/acf-fields.php

Expected: all tests pass and syntax is valid.

Task 2: Render Contact Email on Single Events

Files:

• Modify: templates/single-event.php

• Modify: tests/bootstrap.php

• Create: tests/test-contact-email.php

• Modify: tests/run.php

• Step 1: Write failing output tests

Add minimal sanitize_email() and antispambot() doubles if absent. Test a focused helper named aa_events_contact_email_markup() with:

aa_events_assert_same( '', aa_events_contact_email_markup( '' ), 'Empty email renders nothing.' );
aa_events_assert_same( '', aa_events_contact_email_markup( 'not an email' ), 'Invalid email renders nothing.' );
$markup = aa_events_contact_email_markup( 'events@example.com' );
aa_events_assert_true( false !== strpos( $markup, 'mailto:' ), 'Valid email has a mailto link.' );
aa_events_assert_true( false !== strpos( $markup, 'events@example.com' ), 'Valid email remains readable.' );

Also assert templates/single-event.php reads event_contact_email, calls the helper, and renders the Contact Email: label only when markup is non-empty.

• Step 2: Run the suite and verify RED

Run: php tests/run.php

Expected: FAIL because aa_events_contact_email_markup() does not exist.

• Step 3: Implement safe markup and template output

Add this focused template helper to includes/template-loader.php:

function aa_events_contact_email_markup( $value ) {
	$email = sanitize_email( (string) $value );
	if ( '' === $email || $email !== trim( (string) $value ) ) {
		return '';
	}
	$protected = antispambot( $email );
	return '<a href="' . esc_attr( 'mailto:' . $protected ) . '">' . wp_kses_post( $protected ) . '</a>';
}

In templates/single-event.php, call the helper with get_field( 'event_contact_email' ). When non-empty, render an .aa-event-contact-email detail row with localized label Contact Email: and output only the helper's already constrained anchor through wp_kses_post().

• Step 4: Run complete verification

Run:

php tests/run.php
php -l includes/template-loader.php
php -l templates/single-event.php
phpcs --standard=WordPress includes/acf-fields.php includes/template-loader.php templates/single-event.php

Expected: tests and syntax pass. Record unrelated pre-existing PHPCS findings separately rather than changing unrelated template code.

Task 3: Documentation and Final Check

Files:

• Modify: README.md

• Step 1: Document the optional field

Add Contact Email to the Event Details list and state that it appears only on single-event pages when valid.

• Step 2: Run final verification

Run:

php tests/run.php
find . -path './.superpowers' -prune -o -name '*.php' -print0 | xargs -0 -n1 php -l

Expected: all tests and PHP syntax checks pass.

The workspace is not a Git repository, so commit steps are unavailable.