Skip to content

PLANNING.md

Latest commit

 

History

History
83 lines (66 loc) · 6.77 KB

PLANNING.md

File metadata and controls

83 lines (66 loc) · 6.77 KB

Setlist Player Plugin Implementation Plan

This document outlines the development steps for the Setlist Player WordPress plugin.

Phase 1: Project Scaffolding & Setup

  • 1.1. Initialize Git Repository: Set up the project directory as a Git repository.
  • 1.2. Scaffold Plugin with WP-CLI: Use wp scaffold plugin setlist-player to create the basic plugin structure.
  • 1.3. Initialize NPM: Create a package.json file to manage frontend dependencies and build scripts.
  • 1.4. Install Node Dependencies: Install @wordpress/scripts for block development (which includes React, Webpack, Babel, ESLint, Prettier, and Jest).
  • 1.5. Configure package.json Scripts: Add scripts for start, build, lint, and test.
  • 1.6. Initialize Composer: Create a composer.json file for PHP dependencies.
  • 1.7. Install PHP Dependencies: Install phpcs and the WordPress Coding Standards for linting and formatting PHP.
  • 1.8. Configure composer.json Scripts: Add scripts for lint and format.
  • 1.9. Create .gitignore: Add a comprehensive .gitignore file for WordPress plugin development.

Phase 2: Admin Settings Page & REST API

Technical approach: Use WordPress HTTP API (wp_remote_get()) for YouTube Data API v3 calls. Create separate classes in includes/ directory following WordPress standards. Extend WP_REST_Controller for REST endpoints.

  • 2.1. Create YouTube API Wrapper Class: Build class-setlist-player-youtube-api.php to handle YouTube Data API v3 calls (search, video details, key validation).
  • 2.2. Register Settings Page: Create class-setlist-player-settings.php with settings page under "Settings" menu using add_options_page.
  • 2.3. Implement Settings API: Use WordPress Settings API (register_setting, add_settings_section, add_settings_field) to create the API key input field.
  • 2.4. Implement API Key Validation: On settings save, perform a server-side test call to YouTube Data API v3 using the YouTube API wrapper class.
  • 2.5. Handle Validation Response: Display success or error notices to the admin based on the API call result. Prevent saving an invalid key.
  • 2.6. Create REST Controller: Build class-setlist-player-rest-controller.php extending WP_REST_Controller with endpoints for video search and metadata retrieval.
  • 2.7. Initialize Classes: Update main plugin file to require and initialize all new classes.

Phase 3: Gutenberg Block - Editor Experience

  • 3.1. Scaffold Block: Use @wordpress/create-block to scaffold the block with necessary files (block.json, index.js, edit.js, save.js, style.scss, editor.scss).
  • 3.2. Register Block Type: Register the setlist-player block on the server side with register_block_type.
  • 3.3. Build Editor UI: In the edit.js component, create the sidebar panel using @wordpress/components (e.g., PanelBody, TextControl, Button).
  • 3.4. Manage State with Attributes: Define block attributes in block.json to store the playlist (an array of video objects).
  • 3.5. Implement "Add by URL/ID": Write a function to parse a YouTube URL or ID, fetch video details, and add it to the playlist attribute.
  • 3.6. Implement "Add by Search":
    • 3.6.1. On button click, call the custom REST endpoint created in Step 2.5.
    • 3.6.2. Display the top 5 search results below the search bar.
    • 3.6.3. On result click, add the selected video to the playlist attribute.
  • 3.7. Implement Reordering: Use a library or built-in HTML5 drag-and-drop APIs to allow reordering of videos in the playlist.
  • 3.8. Implement UI Details: Add the dynamic panel title and tooltips for video details on hover.
  • 3.9. Create Editor Placeholder: Design a simple, non-functional placeholder for the block's appearance in the main editor canvas.

Phase 4: Gutenberg Block - Frontend Experience

  • 4.1. Use render.php for Dynamic Rendering: Specify the render property in block.json to point to a render.php file. The block's save.js will return null.
  • 4.2. Enqueue Frontend Scripts: Enqueue the YouTube IFrame Player API and a custom frontend JavaScript file for player interactivity.
  • 4.3. Implement render.php: In the render.php file, use the block's attributes to generate the necessary HTML structure for the player and the playlist on the server side.
  • 4.4. Implement Player Logic: In the frontend JavaScript:
    • 4.4.1. Initialize the YouTube player.
    • 4.4.2. Load the first video without autoplaying.
    • 4.4.3. Implement the "click to play" functionality for the playlist items, including scrolling to the player.
  • 4.5. Implement Custom Controls:
    • 4.5.1. Hook the speed control <select> to the player's setPlaybackRate() method.
    • 4.5.2. Add event listeners for all specified keyboard shortcuts (Spacebar, r, n, p, i, d), plus h for hide video toggle.

Phase 5: Testing & Quality Assurance

  • 5.1. PHPUnit Tests:
    • 5.1.1. Set up the PHPUnit testing environment for WordPress using wp-cli.
    • 5.1.2. Write tests for the API key validation logic.
    • 5.1.3. Write tests for the REST API endpoint.
  • 5.2. Jest Unit Tests:
    • 5.2.1. Write unit tests for utility functions (utils.js).
  • 5.3. Linting and Formatting:
    • 5.3.1. Set up npm run lint and npm run format scripts for JavaScript and CSS files.
    • 5.3.2. Set up composer lint and composer format scripts for PHP files.

Phase 6: Finalization & Documentation

  • 6.1. Review and Refactor: Clean up code and ensure all requirements are met.
  • 6.2. Create readme.txt: Write a comprehensive, WordPress.org-compliant readme.txt file.
  • 6.3. Add Inline Documentation: Ensure functions, classes, and complex code blocks are well-commented.
  • 6.4. Build for Production: Run npm run build to generate minified production assets.
  • 6.5. Create Distribution Package: Implement npm script using @wordpress/scripts plugin-zip to generate a WordPress.org-ready distribution zip file.
  • 6.6. Final Test: Perform a final manual test of the entire plugin workflow.

Future Considerations

These items can be implemented as the plugin matures:

  • React Component Tests: Write unit tests for the edit.js component, mocking @wordpress packages and testing state changes, user interactions (adding/searching for videos), and component rendering.
  • End-to-End (E2E) Tests: Configure @wordpress/e2e-tests-playwright and write E2E tests to simulate adding the block, building a playlist, and verifying the frontend player's functionality.