DYS Events for BandsInTown

A WordPress plugin that integrates with the BandsInTown API to display concert events for artists. Supports both shortcode and Gutenberg block functionality with caching, security validation, and full internationalization support.

Tested up to: 6.48 License: GPL v2 or later Stable tag: 1.0.2

Features

• Dual Integration: Use either shortcode or Gutenberg block
• Flexible Display: List or grid view options
• Advanced Period Modes: Smart mode (automatic), upcoming only, past only, or all events
• Event Filtering: Include/exclude past events with smart logic
• Sorting Options: Sort events by date (newest/oldest first) with period-specific logic
• Customizable Styling: Primary color picker for block customization
• Caching: Built-in transient caching for improved performance (1-hour expiration)
• Security: Comprehensive input validation and sanitization
• Accessibility: ARIA labels, semantic HTML, and keyboard navigation
• Localization: Full internationalization support with POT files
• RTL Support: Right-to-left language support
• Responsive Design: Mobile-friendly layouts
• Error Handling: Graceful error handling with user-friendly messages
• REST API Integration: Server-side rendering with REST API preview

Requirements

• WordPress 5.0 or higher
• PHP 7.4 or higher
• Composer (for PHP dependency management)
• Node.js and npm (for building JavaScript/CSS assets)
• Guzzle HTTP library (installed via Composer)

Installation

Manual Installation

1. Download the plugin zip file
2. Extract the contents to wp-content/plugins/dys-events-for-bandsintown/
3. Activate the plugin through the WordPress admin dashboard
4. Install PHP dependencies: composer install
5. Install Node.js dependencies: npm install
6. Build production assets: npm run build

Composer Installation

composer require dys/bandsintown

WordPress.org Installation

1. Go to Plugins > Add New in your WordPress admin
2. Search for "DYS Events for BandsInTown"
3. Click Install Now and activate

Configuration

Getting a BandsInTown API Key

1. Visit BandsInTown
2. Create an account or log in
3. Go to your account settings
4. Generate an API key in the developer section

Usage

Shortcode

Add the following shortcode to any post, page, or widget:

[dys_bandsintown artiste="Artist Name" apikey="your_api_key"]

Shortcode Parameters

• artiste (required): The artist name as it appears on BandsInTown
• apikey (required): Your BandsInTown API key
• numShows (optional): Number of events to display (1-50, default: 10)
• displayMode (optional): Display format - 'list' or 'grid' (default: 'list')
• sortByDate (optional): Sort order - 'desc' or 'asc' (default: 'desc') - only applies when periodMode is 'all'
• periodMode (optional): Period mode - 'smart', 'upcoming', 'past', or 'all' (default: 'smart')
• primaryColor (optional): Primary color for styling (hex color, default: '#007cba')

Examples

// Basic usage
[dys_bandsintown artiste="Desybes" apikey="your_api_key"]

// Advanced usage with all options
[dys_bandsintown artiste="Desybes" apikey="your_api_key" numShows="20" displayMode="grid" periodMode="all" sortByDate="asc" primaryColor="#ff0000"]

Gutenberg Block

1. In the WordPress editor, click the "+" button to add a new block
2. Search for "DYS Events for BandsInTown"
3. Configure the settings in the block sidebar:
   • Artist Name: Enter the artist name as it appears on BandsInTown
   • API Key: Enter your BandsInTown API key
   • Number of Shows: Set maximum events to display (1-50)
   • Display Mode: Choose between list or grid view
   • Period Mode: Choose smart (automatic), upcoming only, past only, or all events
   • Sort by Date: Choose newest or oldest first (only shown when Period Mode is "All")
   • Primary Color: Choose the primary color for the block elements

API Documentation

Classes

DYS_Bandsintown

Main class for handling BandsInTown integration.

Methods:

• __construct($artiste, $apikey, $numShows, $displayMode, $sortByDate, $periodMode): Initialize the class
• getEvents($events_periode): Fetch events from API for specified period
• getArtiste(): Fetch artist information from API
• render(): Render the complete events HTML with error handling
• renderEvent($event, $mode): Render individual event HTML
• render_error_state($message): Render error state HTML
• log_error($message): Log error messages for debugging

DYS_Bandsintown_API_Handler

Handles API communication with Guzzle HTTP client, caching, and error handling.

Methods:

• __construct($artist, $api_key): Initialize API handler with validation
• get_artist(): Fetch and cache artist data from BandsInTown API
• get_events($period): Fetch and cache events data for specified period
• decode_json($json_string): Safely decode JSON responses
• log_error($message): Log error messages for debugging

DYS_Bandsintown_Security_Validator

Provides comprehensive input validation and sanitization for security.

Static Methods:

• validate_artist($artist): Validate and sanitize artist name
• validate_api_key($api_key): Validate and sanitize API key
• validate_num_shows($num_shows): Validate number of shows (1-50)
• validate_display_mode($display_mode): Validate display mode ('list' or 'grid')
• validate_sort_by_date($sort_by_date): Validate sort order ('asc' or 'desc')
• validate_period_mode($period_mode): Validate period mode ('smart', 'upcoming', 'past', 'all')
• validate_primary_color($primary_color): Validate hex color format
• validate_block_attributes($attributes): Validate all block attributes
• sanitize_html_output($html): Sanitize HTML output for security

DYS_Bandsintown_Localization

Handles internationalization and localization with WordPress standards.

Static Methods:

• init(): Initialize localization system
• load_textdomain(): Load plugin text domain
• set_locale($locale): Set locale for date/time formatting
• format_date($date_string, $format): Format dates with localization
• format_time($date_string, $format): Format times with localization
• get_period_label($period): Get localized period labels
• get_no_events_message($period): Get localized no-events messages
• is_rtl(): Check if current locale is RTL
• get_rtl_class(): Get RTL-aware CSS class

Hooks and Filters

Actions

• dys_bandsintown_load_textdomain: Fired when loading text domain
• plugins_loaded: Standard WordPress hook for plugin initialization
• init: WordPress hook for registering block types
• rest_api_init: WordPress hook for registering REST API routes
• enqueue_block_editor_assets: WordPress hook for block editor assets
• wp_enqueue_scripts: WordPress hook for frontend styles

Filters

• dys_bandsintown_locale: Filter for modifying locale
• locale: WordPress core filter for locale modification

JavaScript API

The Gutenberg block provides the following JavaScript components:

• Edit: Block editor component with live preview and settings panel
• Save: Block save component (server-side rendering)
• index.js: Main block registration file
• edit.js: Editor component with React hooks and API integration
• save.js: Save component for server-side rendering

Block Attributes

• artiste: Artist name (string)
• apikey: API key (string)
• numShows: Number of events (number, 1-50)
• displayMode: Display format ('list' or 'grid')
• sortByDate: Sort order ('asc' or 'desc')
• periodMode: Period mode ('smart', 'upcoming', 'past', 'all')
• primaryColor: Primary color (hex string)

Styling

The plugin includes responsive CSS with support for:

• Light/dark themes
• RTL languages
• Mobile devices
• Accessibility features

CSS Classes

• .dysbit_container: Main container with responsive design
• .dysbit_event: Individual event item
• .dysbit_infos: Event information wrapper
• .dysbit_date: Event date and time section
• .dysbit_title: Event venue and location section
• .dysbit_link: Event action link
• .dysbit_events_container: Events list container
• .dysbit_page_link: Footer link to BandsInTown
• .dysbit_error: Error message container
• .dysbit_no_events: No events message
• .dysbit_grid: Grid layout modifier
• .dysbit_rtl: RTL layout modifier

CSS Custom Properties

• --dys-bit-primary-color: Primary color for theming (default: #007cba)

Development

Setup Development Environment

1. Clone the repository: git clone https://github.com/Igecode/dys-events-for-bandsintown.git
2. Install PHP dependencies: composer install
3. Install Node.js dependencies: npm install
4. Build production assets: npm run build
5. Start development mode with hot reloading: npm run start

Available Scripts

• npm run build: Build production assets for distribution
• npm run start: Start development mode with hot reloading and file watching
• npm run test: Run JavaScript unit tests with Jest
• npm run lint:js: Lint JavaScript files with ESLint
• npm run lint:css: Lint CSS/SCSS files with Stylelint
• npm run format: Format code with Prettier

Testing

Run PHP unit tests with PHPUnit:

composer test

Run JavaScript unit tests with Jest:

npm run test

Run integration tests:

composer integration-test

Code Standards

This plugin follows WordPress coding standards. Run PHP code sniffing:

composer run phpcs

Fix PHP coding standard issues automatically:

composer run phpcbf

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Changelog

Version 1.0.0

• Complete rewrite with modern architecture
• Advanced period modes (smart, upcoming, past, all)
• Enhanced Gutenberg block with live preview
• REST API integration for block preview
• Comprehensive security validation
• Improved caching system (1-hour transients)
• Full internationalization with POT files
• RTL language support
• Customizable primary colors
• Responsive design improvements
• Extensive error handling
• Unit and integration tests
• WordPress coding standards compliance

Version 0.1.0

• Initial release
• Basic shortcode functionality
• Simple Gutenberg block support
• Basic caching and security features
• Localization support

License

This plugin is licensed under the GPL v2 or later.

Copyright (C) 2024 Silvère Oriat

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

Support

For support, please:

1. Check this documentation
2. Open an issue on GitHub
3. Contact the author

Credits

• Author: Silvère Oriat
• Best metal band: Desybes
• API: BandsInTown (https://www.bandsintown.com/)
• Built with: WordPress, React, PHP, Guzzle HTTP
• Testing: PHPUnit, Jest, Testing Library
• Development Tools: WordPress Scripts, ESLint, Stylelint, Prettier

Disclaimer

This plugin is not officially affiliated with BandsInTown. Please refer to BandsInTown's terms of service for API usage guidelines.