163 lines
7.1 KiB
Markdown
163 lines
7.1 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. 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.
|
|
|
|
#### 3. 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.
|
|
|
|
### Context Inheritance
|
|
|
|
Most shortcodes listed below support **context inheritance** from a parent `[swi_foot_context]` block. When a `match_id` or `team_id` is not explicitly provided as a parameter, the shortcode will attempt to use values from the current block context.
|
|
|
|
**Example with context:**
|
|
```html
|
|
[swi_foot_context match_id="12345"]
|
|
[swi_foot_events] <!-- Automatically uses match_id from context -->
|
|
[swi_foot_roster side="home"] <!-- Automatically uses match_id from context -->
|
|
[/swi_foot_context]
|
|
```
|
|
|
|
**Example without context (explicit parameters required):**
|
|
```html
|
|
[swi_foot_events match_id="12345"]
|
|
[swi_foot_roster match_id="12345" side="home"]
|
|
```
|
|
|
|
### Match Display & Elements
|
|
|
|
```html
|
|
[swi_foot_match match_id="12345"]
|
|
[swi_foot_match_home_team match_id="12345"]
|
|
[swi_foot_match_away_team match_id="12345"]
|
|
[swi_foot_match_date match_id="12345" format="d.m.Y"]
|
|
[swi_foot_match_time match_id="12345"]
|
|
[swi_foot_match_venue match_id="12345"]
|
|
[swi_foot_match_score match_id="12345"]
|
|
[swi_foot_match_status match_id="12345"]
|
|
[swi_foot_match_league match_id="12345"]
|
|
[swi_foot_match_round match_id="12345"]
|
|
```
|
|
|
|
### Team & Standings
|
|
|
|
```html
|
|
[swi_foot_standings team_id="42"]
|
|
```
|
|
|
|
### Match Roster & Bench
|
|
|
|
```html
|
|
[swi_foot_roster match_id="12345" side="home|away" starting_squad="true|false" bench="true|false"]
|
|
[swi_foot_bench match_id="12345"]
|
|
```
|
|
|
|
- `[swi_foot_roster]` — Display players for a match.
|
|
- `side="home"` or `side="away"` — Show only one team (defaults to "home").
|
|
- `starting_squad="true|false"` — Include starting squad (defaults to true).
|
|
- `bench="true|false"` — Include bench/substitutes (defaults to false).
|
|
- Players are distinguished by `assignmentRoleId`: 0 = starting squad, non-zero = bench.
|
|
- When both are shown, lists are separated by a horizontal rule.
|
|
|
|
- `[swi_foot_bench]` — Display team staff and substitutes.
|
|
- Automatically shows both home and away team staff.
|
|
- `match_id` required; will auto-populate from context if in a context provider.
|
|
|
|
### Match Events & Referees
|
|
|
|
```html
|
|
[swi_foot_events match_id="12345" event_order="dynamic|newest_first|oldest_first"]
|
|
[swi_foot_referees match_id="12345"]
|
|
```
|
|
|
|
- `[swi_foot_events]` — Show match events (goals, cards, substitutions, etc.) with configurable sort order.
|
|
- `[swi_foot_referees]` — Display match referees with their roles formatted as "Role: Firstname Name" (name in bold).
|
|
|
|
Refer to the original `readme.txt` for additional shortcode details and 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).
|
|
|
|
## 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.
|