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

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