WP Plugin - Image Comparison Elo (ICE)

A WordPress plugin that allows users to compare images pairwise using an Elo rating system and view rankings based on user preferences.

Description

The Image Comparison Elo plugin enables users to compare images within a specified category using a simple "Choose" interface. It calculates Elo ratings based on user selections and displays a ranked list of images with star ratings (1-5 stars). The plugin is designed for performance, accessibility, and user engagement, with features like clickable thumbnails and keyboard navigation.

Features

• Pairwise Image Comparison: Users compare two images at a time and select their preferred option.
• Elo Rating System: Automatically calculates ratings based on user choices using the Elo algorithm.
• Rankings Table: Displays a paginated list of ranked images with star ratings (1-5) and titles.
• Performance Optimization: Uses thumbnail size for rankings and medium size for comparisons, with fallback to full-size images.
• Accessibility: Includes ARIA roles, keyboard navigation, and screen reader support.
• Clickable Thumbnails: Thumbnails link to full-size images in a new tab.

Requirements

• WordPress 5.0 or higher
• PHP 7.0 or higher
• jQuery (included with WordPress)

Installation

1. Download the Plugin:

   • Clone this repository or download the ZIP file:

     git clone https://gitlab.com/engza/wp-plugin-ice.git

2. Upload to WordPress:

   • Upload the image-comparison-elo folder to the /wp-content/plugins/ directory on your WordPress installation.

3. Activate the Plugin:

   • Log in to your WordPress admin panel.
   • Navigate to Plugins > Installed Plugins.
   • Find Image Comparison Elo and click Activate.

4. Set Up Categories:

   • Upload images to the WordPress Media Library and assign them to categories (custom taxonomy or media categories plugin required).

Usage

Shortcodes

1. Image Comparison ([image_compare]):

   • Display two random images from a category for comparison.
   • Example:

     [image_compare category="phones"]

   • Users can click "Choose" to vote for their preferred image or "Skip" to load new images.

2. Image Rankings ([image_rankings]):

   • Display a ranked list of images based on Elo ratings.
   • Examples:

     [image_rankings category="phones" per_page="15"]

     [image_rankings category="phones"]

   • Attributes:
     • category: The category slug (required).
     • per_page: Number of images per page (optional, default: 10).

Example Output

• Comparison:

  [Medium Image: iPhone 12]   [Medium Image: Galaxy S21] 
           Choose                       Choose
                           Skip

  • Clicking an image opens the full-size version in a new tab.

• Rankings:

  Rank | Image          | Rating
  1    | [Thumbnail]    | ★★★★★ (1200)
       | iPhone 12      |
  2    | [Thumbnail]    | ★★★★☆ (1100)
       | Galaxy S21     |

  • Thumbnails link to full-size images.

Configuration

• Image Sizes:

  • Adjust sizes in Settings > Media:
    • thumbnail: Used in rankings (default: 150x150).
    • medium: Used in comparisons (default: 300x300).
  • Regenerate thumbnails after changes using a plugin like Regenerate Thumbnails.

• Custom Sizes (Optional):

  • Add to your theme’s functions.php or the plugin’s main file:

    add_action('after_setup_theme', function() {
        add_image_size('ice-compare', 400, 300, false); // Custom size for comparisons
    });

  • Update compare_shortcode to use 'ice-compare' instead of 'medium'.

Development

File Structure

image-comparison-elo/
├── assets
│   ├── css
│   │   └── frontend.css
│   └── js
│       └── frontend.js
├── includes
│   ├── class-ajax.php
│   ├── class-elo-rating.php
│   ├── class-media-category.php
│   ├── class-settings.php
│   └── class-shortcodes.php
├── image-comparison-elo.php
└── README.md

Key Classes

• ICE_Shortcodes (includes/class-shortcodes.php):

  • Handles shortcode logic for [image_compare] and [image_rankings].
  • Includes helper functions for star ratings and image URL fallbacks.

• ICE_Elo_Rating (assumed in the plugin):

  • Manages Elo rating calculations and database interactions.

Contributing

1. Fork this repository on GitLab.
2. Create a new branch:

   git checkout -b feature/your-feature-name

3. Commit your changes:

   git commit -m "Add your feature description"

4. Push to your fork:

   git push origin feature/your-feature-name

5. Open a Merge Request on GitLab.

Issues

Report bugs or suggest features via the GitLab Issues page.

License

This plugin is licensed under the GPLv2 or later, compatible with WordPress.

Credits

Developed by Zach Engstrom. Inspired by Elo rating systems used in competitive rankings.