upskill-event-manager/docs/automatic-page-creation-plan.md

# Automatic Page Creation Plan

**Date:** 2025-03-28
**Status:** Approved

## 1. Goal

Implement automatic creation of required plugin pages (Login, Registration, Dashboard) upon plugin activation. This ensures a consistent setup across environments, simplifies the user experience, and resolves E2E test failures caused by missing pages (specifically the Community Login page).

## 2. Background

The initial task was to fix failing E2E tests for the Community Login page. Investigation revealed:
*   The tests targeted `/community-login/`, but this page was not guaranteed to exist or contain the `[hvac_community_login]` shortcode in the development environment restored from backup.
*   Searches confirmed the plugin did not include logic (`wp_insert_post`) to automatically create this or other required pages.
*   Manual page creation is possible but less reliable and adds setup steps.
*   The decision was made to add functionality to the plugin to create necessary pages automatically upon activation.

## 3. Required Pages & Shortcodes (Phase 1)

The following pages will be created automatically if they do not already exist with the specified slug:

| Feature              | Title                  | Slug                   | Shortcode / Content                                                     | Notes                                      |
| :------------------- | :--------------------- | :--------------------- | :---------------------------------------------------------------------- | :----------------------------------------- |
| Community Login      | Community Login        | `community-login`      | `<!-- wp:shortcode -->[hvac_community_login]<!-- /wp:shortcode -->`      | Shortcode confirmed.                       |
| Trainer Registration | Trainer Registration   | `trainer-registration` | `<!-- wp:shortcode -->[hvac_trainer_registration]<!-- /wp:shortcode -->` | Shortcode confirmed.                       |
| Trainer Dashboard    | Trainer Dashboard      | `hvac-dashboard`       | *(Empty)*                                                               | Relies on template redirect or assignment. |

*(Phase 2 pages like Email Attendees, Order Summary can be added later once their shortcodes/implementation details are confirmed).*

## 4. Implementation Plan

1.  **Activation Hook:** Use `register_activation_hook` in the main plugin file (`hvac-community-events.php`) to register a callback function that runs only when the plugin is activated.
2.  **Callback Function (`hvac_ce_create_required_pages`):**
    *   Define an array containing the details for the required pages (Title, Slug, Content) as shown in the table above.
    *   Iterate through this array.
    *   For each page definition:
        *   Check if a page with the specified `slug` already exists using `get_page_by_path( $slug, OBJECT, 'page' )`.
        *   **If the page does NOT exist:**
            *   Prepare the post data array for `wp_insert_post()`:
                *   `post_title`: From the page definition array.
                *   `post_name` (slug): From the page definition array key.
                *   `post_content`: From the page definition array (using Gutenberg block format for shortcodes).
                *   `post_status`: `'publish'`.
                *   `post_type`: `'page'`.
                *   `comment_status`: `'closed'`.
                *   `ping_status`: `'closed'`.
            *   Call `wp_insert_post( $post_data )` to create the page.
            *   *(Optional but Recommended):* Store the returned `$page_id` in a WordPress option (e.g., `hvac_community_pages` array) keyed by the feature (e.g., 'login', 'registration') for potential future use (like cleanup on deactivation or easy lookup).
        *   **If the page DOES exist:** Do nothing to avoid duplicates or overwriting user changes.

## 5. Testing Strategy

1.  **Manual Testing:**
    *   Ensure the plugin is deactivated.
    *   Delete any existing pages with the slugs `community-login`, `trainer-registration`, `hvac-dashboard`.
    *   Activate the plugin.
    *   Verify in WP Admin -> Pages that the three pages now exist with the correct titles, slugs, and content (shortcodes or empty).
    *   Verify the pages use the default theme template and are editable with the block editor.
2.  **E2E Testing:**
    *   Run the login test suite: `./bin/run-tests.sh --login`
    *   Confirm the tests now pass as the `/community-login/` page exists and contains the shortcode.
3.  **Unit/Integration Testing (Optional but Recommended):**
    *   Add tests for the `hvac_ce_create_required_pages` function.
    *   Mock `get_page_by_path` and `wp_insert_post`.
    *   Verify `wp_insert_post` is called with the correct data when a page is missing.
    *   Verify `wp_insert_post` is *not* called when `get_page_by_path` finds an existing page.

## 6. Documentation Updates

*   Update `memory-bank/decisionLog.md`: Add decision for automatic page creation.
*   Update `memory-bank/progress.md`: Add task for implementing this feature.
*   Update `wordpress-dev/README.md`: Note that required pages are now created automatically on activation.

## 7. Process Flow Diagram

```mermaid
graph TD
    A[Plugin Activation] --> B{Run Activation Callback};
    B --> C{Loop Through Required Pages (Login, Register, Dashboard...)};
    C --> D{Page Exists? (Check by Slug)};
    D -- No --> E[Prepare Page Data (Title, Slug, Shortcode Block)];
    D -- Yes --> C;
    E --> F[Create Page via wp_insert_post()];
    F --> G{Store Page ID? (Optional)};
    G -- Yes --> H[Update WP Option with Page ID];
    G -- No --> C;
    H --> C;
    C -- All Pages Processed --> I[Activation Complete];

    subgraph "Activation Logic"
        B
        C
        D
        E
        F
        G
        H
    end