136 lines
6.3 KiB
Markdown
136 lines
6.3 KiB
Markdown
# Swiss Football Matchdata
|
|
|
|
Connect to the Swiss Football Association API and display match data, standings, schedules and match elements using flexible shortcodes and Gutenberg blocks.
|
|
|
|
## Description
|
|
|
|
Swiss Football Matchdata provides a small, focused integration with the Swiss Football Association API so you can embed:
|
|
|
|
- Team standings and rankings
|
|
- Upcoming match schedules
|
|
- Detailed match information
|
|
- Individual match elements via shortcodes
|
|
- Gutenberg blocks for visual composition
|
|
|
|
The plugin includes caching, automatic token management, and both shortcodes and Gutenberg blocks for flexibility.
|
|
|
|
## Editor Blocks — Usage Guide
|
|
|
|
This section explains how the plugin's Gutenberg editor blocks are intended to be used in the editor. If a block is unavailable in your editor, ensure the editor script is enqueued and that no console ReferenceErrors appear.
|
|
|
|
### Insertions Methods
|
|
|
|
#### 1. Paragraph Toolbar Shortcode Button (Recommended)
|
|
|
|
- **Purpose**: Quickly insert any Swiss Football shortcode directly into paragraphs or other text blocks.
|
|
- **How to use**:
|
|
1. Click in a paragraph block where you want to insert content.
|
|
2. Look for the **shortcode icon** in the paragraph's formatting toolbar (top of the editor).
|
|
3. Click the button to open the Shortcode insertion modal.
|
|
4. Select the shortcode type (e.g., "Full Match Display", "Score", etc.).
|
|
5. Choose a team and/or match from the dropdowns.
|
|
6. Click "Insert Shortcode" — the shortcode text is inserted at your cursor.
|
|
- **Notes**:
|
|
- This is the fastest way to add shortcodes inline.
|
|
- Works in any paragraph or text-based block.
|
|
- The shortcode generates dynamically at render time on the frontend.
|
|
|
|
#### 2. Team Data Block
|
|
|
|
- **Purpose**: Create and insert shortcodes using a guided block interface.
|
|
- **How to use**:
|
|
1. Insert the `Swiss Football Team Data` block in your post/page.
|
|
2. Open the Inspector Controls (right sidebar).
|
|
3. Select a team from the dropdown.
|
|
4. Choose what to display (Standings or Match).
|
|
5. If you chose Match, select the specific match.
|
|
6. Save the post — the block generates and saves the appropriate shortcode.
|
|
- **Best for**: Users who prefer a visual block interface over toolbars.
|
|
|
|
#### 3. Context Provider Block (for scoped data)
|
|
|
|
- **Purpose**: Provide shared contextual data (season, club/team selection) for child blocks placed inside it. It saves JSON to the frontend as a `data-swi-foot-context` attribute on the provider's wrapper element.
|
|
- **How to use**:
|
|
1. Insert the `SWI Football Context` block at the place in the document that should scope its child blocks (usually near the top of the content where you want the team/season context to apply).
|
|
2. Open the block's Inspector Controls (right sidebar) to set context values such as `Season` or `Team` where supported.
|
|
3. Drop child blocks inside the Context block — these child blocks will inherit the contextual settings.
|
|
4. On save, the provider writes a `data-swi-foot-context` attribute containing a compact JSON string with the configured keys and values. This attribute is used by frontend renderers.
|
|
|
|
#### 4. Specialized Blocks (Standings, Schedule, Roster, Events)
|
|
|
|
- **Swiss Football Standings**
|
|
- Purpose: Display a league standings table for a team.
|
|
- How to use: Insert the block, select a team from Inspector Controls.
|
|
|
|
- **Swiss Football Schedule**
|
|
- Purpose: Display upcoming matches for a team.
|
|
- How to use: Insert the block, select a team and set the match limit.
|
|
|
|
- **Swiss Football Match Roster**
|
|
- Purpose: Show a roster for a specific match. Works best inside a Context Provider.
|
|
- How to use: Insert the block, select a team and match. Optionally configure which side (home/away) and whether to include bench players.
|
|
|
|
- **Swiss Football Match Events**
|
|
- Purpose: Display live events (goals, cards, substitutions) for a match. Works best inside a Context Provider.
|
|
- How to use: Insert the block, select a team and match. Configure auto-refresh interval for live updates.
|
|
|
|
### Deprecated
|
|
|
|
- **Swiss Football Shortcode Inserter block** — This block is deprecated in favor of the paragraph toolbar button above. It has been retained for backwards compatibility with existing posts but is no longer recommended for new content.
|
|
|
|
## Shortcodes
|
|
|
|
Shortcodes provide additional flexibility where blocks are not desirable. Examples:
|
|
|
|
```html
|
|
[swi_foot_match match_id="12345"]
|
|
[swi_foot_match_home_team match_id="12345"]
|
|
[swi_foot_match_date match_id="12345" format="d.m.Y"]
|
|
```
|
|
|
|
Refer to the original `readme.txt` for a complete list of shortcodes and their parameters.
|
|
|
|
## Installation
|
|
|
|
1. Upload the plugin files to `/wp-content/plugins/swiss-football-matchdata/`.
|
|
2. Activate the plugin via Plugins → Installed Plugins.
|
|
3. Go to Settings → Swiss Football and configure your API credentials (base URL, application key, pass, Verein ID, Season ID).
|
|
4. Use the Shortcode helper or Gutenberg blocks in your posts/pages.
|
|
|
|
## Configuration
|
|
|
|
- **API Base URL**: Set the API endpoint for Swiss Football.
|
|
- **API Username / Password**: Application key and password provided by Swiss Football.
|
|
- **Verein ID / Season ID**: used to scope team/season data.
|
|
- **Cache Duration**: how long API responses are cached (default is 30 seconds; configurable).
|
|
|
|
## Developer Notes
|
|
|
|
- Block registrations and editor scripts live in:
|
|
- [includes/class-swi-foot-blocks.php](includes/class-swi-foot-blocks.php)
|
|
- [assets/editor-blocks.js](assets/editor-blocks.js)
|
|
- [assets/build/index.js](assets/build/index.js)
|
|
|
|
- The editor script includes defensive `safeRegisterBlockType` and `safeRegisterFormatType` wrappers to avoid runtime errors when WordPress' editor APIs are not available.
|
|
- Blocks are written to use `apiVersion: 3` and expect modern Gutenberg APIs.
|
|
|
|
## Headless / Automated Checks
|
|
|
|
For quick verification that the built bundle registers the plugin's blocks and formats, a small Node-based test helper exists at `test/register-check.js`.
|
|
|
|
Run it locally with:
|
|
|
|
```bash
|
|
node test/register-check.js
|
|
```
|
|
|
|
This script stubs a minimal `window.wp` environment to confirm that `swi-foot/context` and the inline format are registered by the built bundle.
|
|
|
|
## Support
|
|
|
|
For support or bug reports, open an issue in the project's tracker or contact the plugin author.
|
|
|
|
## License
|
|
|
|
GPL v2 or later — see `readme.txt` for the original header and license URI.
|