README

`mhinspeya/inspeya-hyva-kampagnen`

A Magento 2 module for displaying and managing campaigns with advanced filtering, pagination, and Hyva compatibility.

• Features
• Installation
• Configuration
• Usage
• API Integration
• Frontend Integration
• Technical Details

Features

Core Functionality

• Campaign Display: Show marketing campaigns with images, titles, and descriptions
• Advanced Filtering: Filter campaigns by search text, campaign type, and date ranges
• Pagination: Efficient pagination with customizable items per page
• Responsive Design: Mobile-friendly layout with grid/list view toggle
• AJAX Loading: Dynamic content loading without page refresh
• Error Handling: Robust exception handling prevents frontend breaks

Technical Features

• Hyva Compatible: Optimized for Hyva themes
• Magento 2.4.8+: Compatible with latest Magento versions
• PSR-4 Autoloading: Follows Magento coding standards
• RESTful API: Integrates with external campaign APIs
• Multi-language Support: German locale optimized
• SEO Friendly: Clean URLs and meta information

Installation

Prerequisites

• Magento 2.4.8 or higher
• PHP 7.4 or higher
• Hyva Theme (recommended for optimal experience)

Type 1: Zip file installation

1. Unzip the zip file in app/code/MHinspeya/Kampagnen
2. Enable the module:

   php bin/magento module:enable MHinspeya_Kampagnen
   

3. Apply database updates:

   php bin/magento setup:upgrade
   

4. Flush the cache:

   php bin/magento cache:flush
   

Type 2: Composer installation

1. Add the repository to your composer configuration:

   composer config repositories.mhinspeya composer https://your-repo-url.com
   

2. Install the module:

   composer require mhinspeya/inspeya-hyva-kampagnen
   

3. Enable the module:

   php bin/magento module:enable MHinspeya_Kampagnen
   

4. Apply database updates:

   php bin/magento setup:upgrade
   

5. Flush the cache:

   php bin/magento cache:flush
   

Configuration

Admin Configuration

1. Navigate to Stores > Configuration > MHinspeya.de > App Campaigns

2. Configure the following settings:

   • Display search section on frontend: Enable/disable the campaign search functionality
   • Campaigns GC API: Enter the external API endpoint URL for campaign data

API Configuration

The module requires an external API endpoint that provides campaign data in JSON format. The API should return an array of campaign objects with the following structure:

[
  {
    "kampagnen_id": "1",
    "titel": "Campaign Title",
    "teasertext": "Campaign teaser text",
    "beschreibung": "Full campaign description",
    "titel_bild": "image-filename",
    "bild_pfad": "/path/to/images/",
    "bild_aufloesungen": "small,medium,large",
    "bild_typ": ".jpg",
    "gueltig_von": "2024-01-01",
    "gueltig_bis": "2024-12-31",
    "kampagnen_name": "Campaign Type",
    "news_link": "https://example.com/news",
    "magazin_link": "https://example.com/magazine"
  }
]

Usage

Frontend Integration

1. Campaign List Page: Access campaigns at /kampagnen
2. Campaign Detail Page: View individual campaigns at /kampagnendetail?id={campaign_id}
3. AJAX Endpoints:
   • /kampagnen/kampagnenlist - Load filtered campaigns
   • /kampagnen/kampagpaginationlist - Load paginated campaigns

Block Usage

// In your template files
$block = $this->getLayout()->createBlock(\MHinspeya\Kampagnen\Block\KampagnenList::class);

// Get campaign list
$campaigns = $block->getKampagnenList();

// Get campaign details
$block->getKampagnenListDetail();

// Get related campaigns
$block->getRelatedKampagnenList($campaignId);

AJAX Parameters

The AJAX endpoints accept the following parameters:

• searchText: Filter by campaign title
• selectedValue: Filter by campaign type
• selectedDate: Filter by date range (format: "DD.MM.YYYY - DD.MM.YYYY")
• page: Pagination page number

API Integration

External API Requirements

The module integrates with external campaign APIs through the following features:

1. Automatic Data Fetching: Periodic API calls to retrieve campaign data
2. Error Handling: Graceful fallback when API is unavailable
3. Data Validation: Ensures API response format is correct
4. Caching: Optimized performance with intelligent caching

API Endpoints

• Main API: Configured in admin settings
• Authentication: Supports API key authentication
• Timeout: 60-second timeout for API requests
• Retry Logic: Automatic retry on failed requests

Frontend Integration

Template Files

• Kampagnen-page.phtml: Main campaign listing page
• Kampagnen-detail-page.phtml: Campaign detail page

CSS Classes

The module uses the following CSS classes for styling:

• .campaign-list: Main campaign container
• .campaign-item: Individual campaign card
• .filter-block: Search and filter controls
• .pagination: Pagination controls
• .grid-view / .list-view: Layout toggle buttons

JavaScript Features

• Dynamic Filtering: Real-time search and filtering
• AJAX Pagination: Load more campaigns without page refresh
• Layout Toggle: Switch between grid and list views
• Responsive Design: Mobile-optimized interactions

Technical Details

Module Structure

MHinspeya_Kampagnen/
├── Block/
│   └── KampagnenList.php          # Main block class
├── Controller/
│   └── Kampagnen/
│       ├── KampagnenList.php      # Main AJAX controller
│       └── KampagPaginationList.php # Pagination controller
├── Helper/
│   └── Data.php                   # Configuration helper
├── etc/
│   ├── adminhtml/
│   │   └── system.xml            # Admin configuration
│   ├── frontend/
│   │   └── routes.xml            # Frontend routes
│   └── module.xml                # Module declaration
├── view/
│   └── frontend/
│       ├── templates/            # PHTML templates
│       ├── web/
│       │   ├── css/              # Stylesheets
│       │   └── js/               # JavaScript files
│       └── requirejs-config.js   # RequireJS configuration
├── composer.json                 # Composer configuration
├── registration.php              # Module registration
└── README.md                     # This file

Dependencies

• mhinspeya/backend-mod: ^1.0 (Backend configuration support)
• Magento Framework: Core Magento 2 framework
• Hyva Theme: Recommended for optimal frontend experience

Performance Optimizations

• Lazy Loading: Images load as needed
• AJAX Caching: Cached API responses
• Minified Assets: Optimized CSS and JavaScript
• Database Indexing: Optimized database queries

Security Features

• Input Validation: All user inputs are validated
• XSS Protection: Output escaping for security
• CSRF Protection: Form token validation
• API Authentication: Secure API communication

Support

For support and questions:

• Website: https://inspeya.com
• Documentation: Available in the module documentation
• Issues: Report issues through the support channel

License

This module is licensed under the OSL-3.0 license. See LICENSE.txt for details.

Version History

• 1.0.0: Initial release with core campaign functionality
  • Campaign listing and detail pages
  • AJAX filtering and pagination
  • Admin configuration interface
  • Hyva theme compatibility
  • Comprehensive error handling