wp-plugin-swiss-football-matchdata/readme.txt

=== Swiss Football Matchdata ===
Contributors: David Reindl
Tags: football, soccer, swiss football, sports, matches, standings, schedules, shortcodes, gutenberg
Requires at least: 5.0
Tested up to: 6.4
Stable tag: 1.0.0
Requires PHP: 7.4
License: GPL v2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Connect to Swiss Football Association API to display match data, standings, and schedules with flexible shortcodes and Gutenberg blocks.

== Description ==

Swiss Football Matchdata plugin allows you to integrate with the Swiss Football Association API to display:

* Current team standings/rankings
* Upcoming match schedules  
* Detailed match information
* Individual match elements via shortcodes
* Easy Gutenberg block integration

The plugin features smart caching (configurable duration), automatic token management, and provides both Gutenberg blocks and shortcodes for maximum flexibility.

= Key Features =

* **Flexible Shortcodes**: Insert individual match elements anywhere in your content
* **Smart Caching**: Configurable cache duration for optimal performance (10-300 seconds)
* **Gutenberg Integration**: Easy-to-use blocks and shortcode inserter for the block editor
* **API Management**: Built-in token refresh and error handling
* **Responsive Design**: Mobile-friendly display of all data
* **Configurable Base URL**: Set your own API endpoint
* **Team Management**: Automatic team list fetching and caching

= Available Shortcodes =

**Full Match Display:**
* `[swi_foot_match match_id="12345"]` - Complete match information
* `[swi_foot_match team_id="67" show_next="true"]` - Next match for team

**Individual Match Elements:**
* `[swi_foot_match_home_team match_id="12345"]` - Home team name
* `[swi_foot_match_away_team match_id="12345"]` - Away team name  
* `[swi_foot_match_date match_id="12345" format="d.m.Y"]` - Match date
* `[swi_foot_match_time match_id="12345" format="H:i"]` - Match time
* `[swi_foot_match_venue match_id="12345"]` - Match venue
* `[swi_foot_match_score match_id="12345" separator=":"]` - Current score
* `[swi_foot_match_status match_id="12345"]` - Match status
* `[swi_foot_match_league match_id="12345"]` - League name
* `[swi_foot_match_round match_id="12345"]` - Round number

= Gutenberg Blocks =

* **Swiss Football Context** - Set shared context (team, season) for child blocks
* **Swiss Football Standings** - Display team rankings and standings
* **Swiss Football Schedule** - Show upcoming matches for a team
* **Swiss Football Match Roster** - Display player rosters for a match
* **Swiss Football Match Events** - Show match events (goals, cards, substitutions) with live updates
* **Swiss Football Match Referees** - Display referee information
* **Swiss Football Shortcode** - Insert custom shortcodes with visual interface (deprecated, use paragraph toolbar instead)

= Usage Examples =

**Simple Match Display:**
`[swi_foot_match match_id="12345"]`

**Next Match for Team:**
`[swi_foot_match team_id="67" show_next="true"]`

**Individual Elements in Text:**
`The match between [swi_foot_match_home_team match_id="12345"] and [swi_foot_match_away_team match_id="12345"] will be played on [swi_foot_match_date match_id="12345" format="F j, Y"] at [swi_foot_match_time match_id="12345" format="g:i A"] in [swi_foot_match_venue match_id="12345"].
Current score: [swi_foot_match_score match_id="12345"]`


== Installation ==

1. Upload the plugin files to `/wp-content/plugins/swiss-football-matchdata/`
2. Activate the plugin through the 'Plugins' screen in WordPress
3. Go to Settings → Swiss Football to configure your API credentials
4. Enter your API base URL, username (application key), password (application pass), Verein ID, and Season ID
5. Test the connection and refresh your teams list
6. Start using the shortcodes and blocks in your content

== Configuration ==

After activation, configure these settings in Settings → Swiss Football:

**API Configuration:**
* **API Base URL**: The Swiss Football API endpoint (default: https://stg-club-api-services.football.ch)
* **API Username**: Your application key from Swiss Football
* **API Password**: Your application password from Swiss Football  
* **Verein ID**: Your club's unique identifier
* **Season ID**: Current season (usually the year)

**Cache Settings:**
* **Match Data Cache Duration**: How long to cache match data (10-300 seconds, default: 30)

== Frequently Asked Questions ==

= How do I get API credentials? =

Contact the Swiss Football Association to obtain your application key, application password, and Verein ID.

= How often is data updated? =

Match data is cached according to your configured cache duration (default 30 seconds). The cache is automatically refreshed when pages with shortcodes are loaded.

= Can I customize the display styling? =

Yes, the plugin includes CSS classes you can target:
* `.swi-foot-match-container` - Full match displays
* `.swi-foot-standings` - Standings tables
* `.swi-foot-schedule` - Schedule lists
* `.swi-foot-inline` - Individual shortcode elements
* `.swi-foot-error` - Error messages

= What happens if the API is unavailable? =

The plugin will display cached data if available, or show appropriate error messages. It includes robust error handling and logging.

= How do I use shortcodes in the Gutenberg editor? =

Click the shortcode icon in any paragraph's toolbar to quickly insert shortcodes. You can also use the "Swiss Football Shortcode" block (now deprecated) for backwards compatibility.

= Can I display data for multiple teams? =

Yes, you can use different team IDs in different shortcodes and blocks throughout your site.

= How do I find my team's ID? =

After configuring your API credentials, go to Settings → Swiss Football and click "Refresh Teams List". This will display all available teams with their IDs.

= Can I use custom date/time formats? =

Yes, use the `format` parameter in date and time shortcodes with PHP date format strings (e.g., `format="d.m.Y"` for European date format).

= Does the plugin work with caching plugins? =

Yes, the plugin's internal caching system works alongside WordPress caching plugins. The 30-second cache ensures fresh data while minimizing API calls.

== Screenshots ==

1. Admin settings page with API configuration and team management
2. Shortcode helper meta box in post editor with click-to-copy functionality
3. Gutenberg shortcode inserter block with visual interface
4. Example standings table display on frontend
5. Example match schedule display with upcoming games
6. Individual shortcode elements integrated in post content
7. Cache management and connection testing interface

== Changelog ==

= 1.0.0 =
* Initial release
* Swiss Football API integration with automatic token management
* Comprehensive shortcode system for individual match elements
* Configurable caching system (10-300 seconds)
* Gutenberg blocks for standings, schedules, rosters, and events
* Context provider block for scoped data
* Admin interface for configuration and team management
* Responsive design and error handling
* Support for configurable API base URL
* Click-to-copy shortcode functionality in admin
* Smart cache updates on page load
* Paragraph toolbar shortcode insertion

== Upgrade Notice ==

= 1.0.0 =
Initial release of Swiss Football Matchdata plugin with comprehensive API integration and flexible shortcode system.

== Support ==

For support, feature requests, or bug reports, please contact the plugin author or visit the plugin's support forum.

== Privacy ==

This plugin connects to the Swiss Football Association API to retrieve match data. No personal data from your website visitors is sent to external services. The plugin only sends:
* API credentials (application key/password) for authentication
* Club/team identifiers to retrieve relevant match data

All data is cached locally on your WordPress installation according to your configured cache duration.