david.reindl/wp-plugin-swiss-football-matchdata

Reindl David (IT-PTR-CEN2-SL10) 6b9c3fefa1 various improvements to make release 1 complete

2026-03-27 13:59:28 +01:00

17 KiB

Raw Permalink Blame History

Swiss Football Matchdata — Developer Setup Guide

This guide explains how to set up the development environment after checking out the project from Git and how to generate a distribution-ready package.

Prerequisites

Before starting, ensure you have the following installed on your system:

Node.js (LTS 18.x or newer) - download
npm (comes with Node.js)
Git (for cloning and version control)
PHP 7.4+ (for running WordPress locally, if developing)
WordPress (local development installation recommended)

Verify installations:

node --version
npm --version
php --version

Initial Setup After Git Checkout

1. Clone the Repository

git clone <repository-url> swiss-football-matchdata
cd swiss-football-matchdata

2. Install Dependencies

Install all npm dependencies required for building the Gutenberg editor blocks:

npm install

This reads package.json and installs:

@wordpress/scripts — WordPress build tooling (webpack, babel, eslint)

3. Build the Editor Bundle

Create the compiled editor JavaScript bundle that the plugin requires:

npm run build

This command:

Runs wp-scripts build --output-path=assets/build
Uses the custom webpack.config.js to ensure output is named editor-blocks.js
Generates additional asset files in assets/build/
Result: assets/build/editor-blocks.js is now ready for use

4. Verify the Build

Check that the compiled bundle exists:

ls -lh assets/build/editor-blocks.js

You should see a JavaScript file (typically 50-150 KB depending on dependencies).

Development Workflow

Live Development with Hot Reload

For active development with automatic recompilation and browser refresh:

npm run start

This starts the WordPress development server with:

File watching: Changes to src/editor-blocks.js trigger rebuilds
Hot module reload: Changes appear in the editor without full page refresh
Source maps: Easier debugging in browser DevTools

Press Ctrl+C to stop the server.

Project Structure

swiss-football-matchdata/
├── src/
│   ├── editor-blocks.js         # Main editor block components
│   ├── format-shortcode.js       # Shortcode formatting toolbar
│   ├── index.js                  # Package entry point
│   └── [other source files]
├── blocks/                       # Block definitions (metadata)
│   ├── context/
│   ├── match-events/
│   ├── match-bench/
│   ├── match-referees/
│   ├── match-roster/
│   ├── schedule/
│   ├── standings/
│   └── shortcode-inserter/
├── assets/
│   ├── build/
│   │   ├── editor-blocks.js     # Compiled output (generated)
│   │   ├── editor-blocks.asset.php  # Asset dependencies (generated)
│   │   └── [other generated assets]
│   ├── admin.js / admin.css      # Admin-only frontend code
│   ├── blocks.js / blocks.css    # Public frontend code
│   └── [other assets]
├── includes/                     # PHP backend
│   ├── class-swi-foot-admin.php
│   ├── class-swi-foot-api.php
│   ├── class-swi-foot-blocks.php
│   ├── class-swi-foot-rest.php
│   └── class-swi-foot-shortcodes.php
├── languages/                    # Translation files (i18n)
├── tests/                        # Test files
├── webpack.config.js             # Custom webpack configuration
├── package.json                  # npm dependencies and scripts
├── README.md                      # User documentation
├── DEV-README.md                 # Legacy build notes
└── README-DEV.md                 # This file

Editing WordPress Blocks

Block Files

Each block is defined in its own directory under blocks/:

block.json — Block metadata (name, icon, attributes, supports)
The React component code lives in src/editor-blocks.js

Example Workflow

Edit block in editor (src/editor-blocks.js):
- Add UI elements (SelectControl, TextControl, etc.)
- Implement save logic that generates shortcodes
- Update attribute definitions
Test with hot reload:
```
npm run start
```

Hard-refresh your WordPress editor page
Make changes in src/editor-blocks.js
The browser auto-updates (HMR)

Verify output:
- Insert/edit the block in WordPress
- Check browser DevTools → Network → look for editor-blocks.js
- Look at page source to verify shortcode is generated correctly
Build for production:
```
npm run build
```

Code Quality

Linting and Formatting

The @wordpress/scripts package includes eslint configuration. WordPress code standards are automatically enforced on .js files in the project.

To fix common issues automatically:

npx eslint src/ --fix

PHP Code

PHP files follow standard WordPress coding standards. Check syntax:

php -l includes/class-swi-foot-blocks.php

(or any other PHP file)

Managing Translations

Translation files include:

.po files — Human-editable source translations (one per language)
.pot file — Translation template (extraction from source code)
.mo files — Compiled binary translations (generated from .po files)

Workflow when adding new translatable strings:

Add translation strings to PHP or JavaScript with proper functions and translator comments:
```
/* translators: %s is the API error message */
__('Error loading data: %s', 'swi_foot_matchdata')

_e('Text to display', 'swi_foot_matchdata')
```
Important: Always add /* translators: ... */ comments above i18n functions with placeholders to clarify their meaning for translators.
Extract strings and update translation files using the i18n management script:
```
./dev-scripts/i18n-manage.sh extract
```
This extracts all strings to languages/swi_foot_matchdata.pot.
Generate .po files for translation:
```
./dev-scripts/i18n-manage.sh translate
```
Creates/updates .po files for: German (de_DE), French (fr_FR), Italian (it_IT), English (en_US)
Provide .po files to translators:
- Translators edit languages/swi_foot_matchdata-de_DE.po, -fr_FR.po, -it_IT.po
- They can use PoEdit, Crowdin, or any PO file editor
- Translator comments help clarify placeholder meanings
After translations are complete, compile .mo files:
```
./dev-scripts/i18n-manage.sh build
```
Generates binary .mo files from .po files.

Commit both .po and .mo files to git:

git add languages/*.po languages/*.mo
git commit -m "Update translations for [feature/language]"

(Optional) Clean up regional variants:
```
./dev-scripts/i18n-manage.sh clean
```
Removes regional variants (de_AT, de_CH) to keep only core languages.

Note: Editor backup files (.po~) are not committed (ignored by .gitignore).

The .mo files are essential for distribution — they're included in both git commits and distribution packages so installations work immediately without requiring a build step.

Complete i18n Workflow with Script

The i18n-manage.sh script automates the entire translation pipeline:

# Run complete workflow (extract → translate → build → clean)
./dev-scripts/i18n-manage.sh all

This is equivalent to running:

./dev-scripts/i18n-manage.sh extract     # Extract strings to .pot
./dev-scripts/i18n-manage.sh translate   # Generate .po files for each language
./dev-scripts/i18n-manage.sh build       # Compile .po to .mo files
./dev-scripts/i18n-manage.sh clean       # Remove regional variants

Supported Languages (by default):

de_DE — German
fr_FR — French
it_IT — Italian
en_US — English

Script Configuration:

Edit dev-scripts/i18n-manage.sh lines 39-60 to customize:

WP_CLI_CMD — WordPress CLI command (for Docker or local)
LANGUAGES — Supported language codes
REGIONAL_VARIANTS — Variants to remove during cleanup

Best Practices:

Always add translator comments for strings with placeholders
Use ordered placeholder syntax: %1$d, %2$s (not just %d, %s)
Keep strings complete and translatable (don't break into fragments)
Commit .po and .mo files to git along with source changes

For detailed documentation, see:

dev-docs/I18N_QUICK_REFERENCE.md — Quick start guide
dev-docs/I18N_OPTIMIZATIONS.md — Best practices and examples

Testing in Development

Local WordPress Installation

For testing the complete plugin:

Place the plugin in WordPress:

# Assuming WordPress is at /path/to/wordpress
cp -r . /path/to/wordpress/wp-content/plugins/swiss-football-matchdata

Activate the plugin:
- Go to WordPress Admin → Plugins
- Find "Swiss Football Matchdata"
- Click "Activate"
Test blocks:
- Create a new post/page
- Insert blocks using the editor
- Verify blocks are available and functional
- Hard-refresh browser to clear cache after rebuilds

Browser DevTools Checklist

Console: Watch for JavaScript errors
Network: Verify editor-blocks.js loads correctly
Sources: Use source maps to debug original .js files
Application → Storage: Clear LocalStorage/IndexedDB if blocks misbehave

Building for Distribution

1. Ensure Clean Build

# Remove old build artifacts (optional)
rm -rf assets/build

# Install fresh dependencies
npm ci  # (instead of npm install - more reproducible)

# Build
npm run build

2. Verify Build Output

# All required files should exist
test -f assets/build/editor-blocks.js && echo "✓ Editor bundle present"
test -f assets/build/editor-blocks.asset.php && echo "✓ Asset manifest present"

3. Create Distribution Package

Using the Build Script (Recommended)

A convenience bash script is included to automate distribution packaging:

./dev-scripts/build-distribution.sh

This script:

Creates a clean working directory
Excludes all development files and dependencies
Includes only files needed for distribution
Generates a ZIP archive
Displays summary information

Excluded from the distribution:

node_modules/ (development dependencies)
src/ (source code for building)
test/ (test files)
package.json / package-lock.json
webpack.config.js (build config)
dev-scripts/ (development scripts)
README-DEV.md (developer guide)
.git, .gitignore, .DS_Store, and other system files

Manual Packaging (Alternative)

If you prefer to create the distribution manually:

# Create a clean directory for the distribution
mkdir -p dist
PLUGIN_NAME="swiss-football-matchdata"

# Copy all plugin files (excluding development files)
rsync -av --exclude='.git' \
  --exclude='node_modules' \
  --exclude='.npm-cache' \
  --exclude='package-lock.json' \
  --exclude='.gitignore' \
  --exclude='README-DEV.md' \
  --exclude='.DS_Store' \
  --exclude='*.swp' \
  --exclude='.idea/' \
  --exclude='test/' \
  --exclude='src/' \
  --exclude='webpack.config.js' \
  . dist/$PLUGIN_NAME/

# Create ZIP archive
cd dist
zip -r "$PLUGIN_NAME.zip" $PLUGIN_NAME/
cd ..

# Result: dist/swiss-football-matchdata.zip
echo "Distribution package created: dist/$PLUGIN_NAME.zip"

4. Verify Distribution Package

# What's in the ZIP?
unzip -l dist/swiss-football-matchdata.zip | head -30

# Should include:
# ✓ swiss-football-matchdata.php (main plugin file)
# ✓ assets/build/editor-blocks.js (compiled bundle)
# ✓ includes/*.php (backend code)
# ✓ README.md (user documentation)

# Should NOT include:
# ✗ node_modules/ (development dependencies)
# ✗ package.json / package-lock.json
# ✗ README-DEV.md (developer guide)
# ✗ src/ (source code — users don't need it)
# ✗ test/ (test files)
# ✗ webpack.config.js (build configuration)
# ✗ .git (git history)

5. Size Check

The distribution ZIP should be reasonable in size:

With assets/build/editor-blocks.js: ~150–300 KB
Typical unzipped size: ~800 KB–2 MB

If significantly larger, check for unwanted files:

unzip -l dist/swiss-football-matchdata.zip | sort -k4 -rn | head -20

Deployment / Installation

For Site Administrators (Users)

Users install the distribution ZIP file normally:

Go to WordPress Admin → Plugins → Add New → Upload Plugin
Select the .zip file
Activate

Important: The plugin expects assets/build/editor-blocks.js to be present. Always run npm run build before packaging.

For Developers on Target Site

If deploying to a site where you're also developing:

# Copy the plugin to WordPress
cp -r . /path/to/wordpress/wp-content/plugins/swiss-football-matchdata

# Navigate to plugin directory
cd /path/to/wordpress/wp-content/plugins/swiss-football-matchdata

# Ensure build is present (if needed)
npm ci && npm run build

Continuous Integration (Optional)

GitHub Actions Example

Add to .github/workflows/build.yml:

name: Build and Verify

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Build editor bundle
        run: npm run build
      
      - name: Verify build output
        run: |
          test -f assets/build/editor-blocks.js || exit 1
          test -f assets/build/editor-blocks.asset.php || exit 1          
      
      - name: PHP Syntax Check
        run: |
          find includes -name "*.php" -exec php -l {} \;

This ensures:

Every push/PR has a valid build
Missing build artifacts fail visibly
PHP code is syntactically correct

Troubleshooting

Build Fails with Module Not Found

Problem: npm run build fails with "module not found"

Solution:

rm package-lock.json
npm install
npm run build

Changes Don't Appear in Editor

Problem: Edited src/editor-blocks.js but changes don't show in WordPress

Solutions:

Hard-refresh browser: Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows/Linux)
Clear WordPress cache (if caching plugin is active)
Verify assets/build/editor-blocks.js was updated: ls -l assets/build/editor-blocks.js
Check browser console for JavaScript errors

`npm start` Doesn't Work

Problem: Development server won't start