Mehr-Schulferien WordPress Plugin

A WordPress plugin that displays German school vacations and holidays from the mehr-schulferien.de API.

Description

This plugin integrates with the mehr-schulferien.de API to display school vacation data for German federal states, cities, and individual schools. It's perfect for educational institutions, parent associations, travel agencies, and any website that needs to display German school vacation information.

Features

• Multiple Display Formats: Table, list, and calendar views
• Flexible Location Support: Federal states, cities, and individual schools
• Smart Caching: Reduces API calls and improves performance
• Widget Support: Display upcoming vacations in sidebars
• Responsive Design: Works on all devices
• Customizable: Add your own CSS styling
• Translation Ready: Prepared for German localization

Installation

Method 1: Download from GitHub (Recommended)

1. Visit the GitHub repository
2. Click the green "Code" button
3. Select "Download ZIP"
4. Save the file to your computer
5. In WordPress admin, go to Plugins > Add New > Upload Plugin
6. Choose the downloaded ZIP file and click "Install Now"
7. Activate the plugin after installation
8. Configure settings under Settings > School Vacations

Method 2: Manual Installation

1. Download the repository as described above
2. Extract the ZIP file
3. Rename the extracted folder to mehr-schulferien
4. Upload the entire mehr-schulferien folder to your /wp-content/plugins/ directory via FTP
5. Activate the plugin through the WordPress admin panel
6. Configure settings under Settings > School Vacations

Method 3: Direct Clone (for Developers)

cd /path/to/wordpress/wp-content/plugins/
git clone https://github.com/mehr-schulferien-de/mehr-schulferien-wordpress-plugin.git mehr-schulferien

Required Files

The plugin package should contain these essential files and folders:

• mehr-schulferien.php - Main plugin file
• includes/ - PHP class files
• templates/ - Display templates
• assets/ - CSS and JavaScript files
• languages/ - Translation files
• readme.txt - WordPress readme
• LICENSE - MIT license file

Quick Start

After installation and activation:

1. Test the plugin: Create a new page or post and add the shortcode:

   [schulferien location_type="federal_state" location="berlin"]
   

2. Configure settings: Go to Settings > School Vacations to:

   • Adjust cache duration
   • Set default display format
   • Add custom CSS if needed

3. Add widget: Go to Appearance > Widgets and add the "School Vacations" widget to your sidebar

Usage

Shortcode

Use the [schulferien] shortcode to display vacation data:

[schulferien location_type="federal_state" location="berlin" year="2024" display="table"]

Parameters

• location_type - Type of location (federal_state, city, or school)
• location - Location slug (e.g., "berlin", "hamburg")
• year - Year to display (optional, defaults to current year)
• display - Display format: table, list, or calendar (optional)

Examples

// Show Bavaria vacations in a table
[schulferien location_type="federal_state" location="bayern"]

// Display Munich vacations as a list
[schulferien location_type="city" location="muenchen" display="list"]

// Show school vacations in calendar format
[schulferien location_type="school" location="gymnasium-example" year="2025" display="calendar"]

Widget

Add the "School Vacations" widget to any sidebar to display upcoming vacations.

API Information

This plugin uses the mehr-schulferien.de API v2.1:

• Base URL: https://www.mehr-schulferien.de/api/v2.1/
• No authentication required
• Free to use

API documentation: https://github.com/mehr-schulferien-de/www.mehr-schulferien.de

Development

Directory Structure

mehr-schulferien-wordpress-plugin/
├── mehr-schulferien.php          # Main plugin file
├── includes/
│   ├── class-api-client.php      # API communication
│   ├── class-cache.php           # Caching with transients
│   ├── class-shortcode.php       # Shortcode handler
│   ├── class-widget.php          # Widget implementation
│   └── class-admin.php           # Admin settings
├── templates/
│   ├── vacation-table.php        # Table display template
│   ├── vacation-list.php         # List display template
│   └── vacation-calendar.php     # Calendar display template
├── assets/
│   ├── css/
│   │   └── frontend.css          # Frontend styles
│   └── js/
│       └── admin.js              # Admin JavaScript
├── languages/
│   └── mehr-schulferien.pot      # Translation template
├── readme.txt                    # WordPress.org readme
└── README.md                     # This file

Hooks and Filters

The plugin provides several hooks for developers:

// Modify API response before caching
apply_filters('mehr_schulferien_api_response', $response, $endpoint);

// Customize period formatting
apply_filters('mehr_schulferien_format_period', $formatted_period, $raw_period);

// Modify shortcode output
apply_filters('mehr_schulferien_shortcode_output', $output, $atts);

Requirements

• WordPress 5.0 or higher
• PHP 7.2 or higher
• Active internet connection for API calls

License

This plugin is licensed under the MIT License. See the LICENSE file for details.

Support

Bug Reports

If you encounter any bugs or issues with the plugin, please report them by creating an issue on GitHub:

1. Go to the Issues page
2. Click "New Issue"
3. Provide a clear title and description of the bug
4. Include steps to reproduce the issue
5. Add any relevant error messages or screenshots
6. Mention your WordPress version and PHP version

Feature Requests

For feature requests, please also create an issue on GitHub and label it as "enhancement".

General Support

• Visit mehr-schulferien.de for more information about the vacation data
• For urgent matters or if you cannot use GitHub, you can contact Stefan Wintermeyer directly by e-mail at sw@wintermeyer-consulting.de

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Credits

• API provided by mehr-schulferien.de
• Created by Stefan Wintermeyer

Changelog

1.0.0

• Initial release
• Three display formats (table, list, calendar)
• Support for federal states, cities, and schools
• Widget functionality
• Caching system
• Admin settings page