README

A powerful and flexible Magento 2 extension that allows you to create and manage image sliders with ease. This extension provides a user-friendly admin interface for managing sliders and displays them on the frontend using the Swiper.js library.

Features

🎨 Easy Slider Management: Create and manage multiple image sliders from the Magento admin panel
🖼️ Multiple Images: Add unlimited images to each slider
🎯 Widget Support: Display sliders anywhere on your store using Magento widgets
🎪 Swiper.js Integration: Modern, touch-enabled slider with smooth animations
📱 Responsive Design: Fully responsive sliders that work on all devices
⚙️ Status Control: Enable/disable sliders individually
🏷️ Alt Tags: Add alt text to images for better SEO
🔍 GraphQL Support: Query sliders via GraphQL API
🎛️ Admin Interface: Intuitive admin panel with image upload functionality

Requirements

Magento 2: 2.4.x or higher
PHP: 8.1, 8.2, or 8.3
Magento Framework: 103.0.*
Browser Support: Modern browsers (Chrome, Firefox, Safari, Edge)

Installation

Via Composer (Recommended)

composer require tharinduhdev/imagegallery

Manual Installation

Download or clone this repository
Copy the extension to app/code/Tharinduhdev/Imagegallery/
Run the following commands:

php bin/magento module:enable Tharinduhdev_Imagegallery
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush

Configuration

Admin Panel Access

After installation, navigate to:

Admin Panel → Content → Image Sliders → Manage Sliders

Creating a Slider

Go to Content → Image Sliders → Manage Sliders
Click Add New Slider
Fill in the following fields:
- Name: Display name for the slider (for admin reference)
- Identifier: Unique identifier (e.g., homepage-banner, product-slider)
- Status: Enable or disable the slider
Upload images using the image gallery
Add alt tags for each image (recommended for SEO)
Click Save or Save and Continue Edit

Permissions

The extension includes ACL (Access Control List) permissions:

Tharinduhdev_Imagegallery::elements - Access to Image Sliders menu
Tharinduhdev_Imagegallery::manage_sliders - Manage sliders
Tharinduhdev_Imagegallery::config_slider - Configuration access

Configure these in System → Permissions → User Roles

Usage

Using the Widget

Go to Content → Widgets
Click Add Widget
Select Image Slider Widget from the widget type dropdown
Configure the widget:
- Widget Title: Title for the widget (optional)
- Slider Identifier: Enter the identifier of the slider you created
Choose where to display the widget:
- Layout Updates → Add Layout Update
- Select the page type (CMS Page, Category, Product, etc.)
- Choose the container (e.g., Main Content Area, Sidebar)
Click Save

Programmatic Usage

You can also use the slider widget block directly in your templates:

<?php
$block = $this->getLayout()->createBlock(\Tharinduhdev\Imagegallery\Block\Widget\Slider::class);
$block->setSliderIdentifier('your-slider-identifier');
echo $block->toHtml();
?>

Or in a layout XML file:

<block class="Tharinduhdev\Imagegallery\Block\Widget\Slider" name="image.slider">
    <arguments>
        <argument name="slider_identifier" xsi:type="string">your-slider-identifier</argument>
    </arguments>
</block>

GraphQL Query

Query sliders using GraphQL:

{
  sliders {
    id
    name
    identifier
    status
    images {
      id
      image_path
      alt_tag
      url
    }
  }
}

Slider Features

The slider includes the following features by default:

Autoplay: Automatically advances slides every 5 seconds
Navigation Arrows: Previous/Next buttons for manual navigation
Pagination Dots: Clickable dots indicating current slide
Loop: Continuous loop through slides
Touch Support: Swipe gestures on mobile devices
Lazy Loading: Images load lazily for better performance

Customizing Slider Settings

To customize slider behavior, edit view/frontend/web/js/swiper-init.js:

var swiper = new Swiper(element, {
    direction: 'horizontal',
    loop: true,
    autoplay: {
        delay: 5000, // Change autoplay delay (milliseconds)
        disableOnInteraction: false,
    },
    speed: 600, // Transition speed
    pagination: {
        el: '.swiper-pagination',
        clickable: true,
    },
    navigation: {
        nextEl: '.swiper-button-next',
        prevEl: '.swiper-button-prev',
    },
    // Add more Swiper options as needed
});

Refer to the Swiper.js documentation for all available options.

File Structure

Tharinduhdev/Imagegallery/
├── Block/
│   ├── Adminhtml/          # Admin block classes
│   └── Widget/             # Frontend widget block
├── Controller/
│   └── Adminhtml/          # Admin controllers
├── etc/
│   ├── adminhtml/          # Admin configuration
│   ├── db_schema.xml       # Database schema
│   ├── module.xml          # Module declaration
│   └── widget.xml          # Widget configuration
├── Helper/                 # Helper classes
├── Model/                  # Model classes
├── view/
│   ├── adminhtml/          # Admin templates and assets
│   └── frontend/           # Frontend templates and assets
└── registration.php        # Module registration

Database Tables

The extension creates two database tables:

tharinduhdev_imagegallery_sliders: Stores slider information
- id: Primary key
- name: Slider name
- identifier: Unique identifier
- status: Enabled/Disabled status
tharinduhdev_imagegallery_slider_images: Stores slider images
- id: Primary key
- slider_id: Foreign key to sliders table
- image_path: Path to the image file
- alt_tag: Alt text for the image

Troubleshooting

Slider Not Displaying

Verify the slider identifier is correct
Check that the slider status is "Enabled"
Ensure images are uploaded to the slider
Clear Magento cache: php bin/magento cache:flush
Deploy static content: php bin/magento setup:static-content:deploy -f

Images Not Loading

Check file permissions on the media directory
Verify images were uploaded successfully in admin
Check browser console for JavaScript errors
Ensure Swiper.js library is loaded correctly

Admin Panel Issues

Verify ACL permissions are set correctly
Check that the module is enabled: php bin/magento module:status
Recompile: php bin/magento setup:di:compile

Support

For issues, questions, or contributions, please contact the extension developer or create an issue in the repository.

License

This extension is licensed under the MIT License. See the license file for details.

Version

Current Version: 1.0.0

Changelog

Version 1.0.0

Initial release
Basic slider functionality
Admin panel integration
Widget support
Swiper.js integration
GraphQL support

Credits

Built with Swiper.js - Modern touch slider
Developed for Magento 2

Note: Always backup your database and files before installing or updating any Magento extension.

tharinduhdev/imagegallery

包简介

README 文档