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

Reindl David (IT-PTR-CEN2-SL10) fbd595aa36 initial state

2026-03-18 19:58:24 +01:00

13 KiB

Raw 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-roster/
│   ├── schedule/
│   ├── standings/
│   ├── team-data/
│   └── 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:

__('Text to translate', 'swi_foot_matchdata')
_e('Text to display', 'swi_foot_matchdata')

Extract strings to the .pot template file:
```
wp i18n make-pot . languages/swi_foot_matchdata.pot
```
(Requires WP-CLI installed)
Update existing .po translation files from the new template (done by translators in PoEdit or similar)
Generate binary .mo files:
```
wp i18n make-mo languages/
```

Commit both .po and .mo files to git:

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

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.

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

Method A: Manual Packaging (Recommended)

# 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' \
  --exclude='package-lock.json' \
  --exclude='.gitignore' \
  --exclude='README-DEV.md' \
  --exclude='.DS_Store' \
  --exclude='*.swp' \
  --exclude='.idea/' \
  . 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"

Method B: Using Git Archive (Cleaner)

If your .gitignore is properly configured to exclude development files:

git archive --output=dist/swiss-football-matchdata.zip HEAD \
  --prefix=swiss-football-matchdata/

This creates the distribution package from committed files only (respecting .gitignore).

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)
# ✗ .git (git history)
# ✗ src/ (source code — users don't need it)

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