Keith Solomon
51147ef36f
- Introduced a new specification for adding an optional contact email field to events, including front-end output and compatibility testing. - Added a comprehensive design document for multi-day event occurrences, detailing the new occurrence data model, validation, normalization, and calendar architecture. - Created specifications for ACF field-key switching compatibility and local ACF override compatibility to ensure seamless integration with existing themes. - Implemented a desktop calendar view toggle design, allowing users to switch between calendar and list views, with persistent preferences and responsive behavior.
134 lines
4.7 KiB
Markdown
134 lines
4.7 KiB
Markdown
# 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:
|
|
|
|
```php
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```php
|
|
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`:
|
|
|
|
```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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|