Merge pull request #22 from fairpm/refactor/views

 Reduce view layer duplication with shared templates and base mode

Author: ilicfilip

README.md

@@ -1,13 +1,14 @@
 # Fair-Explorer
 
-A WordPress plugin that provides a comprehensive repository browser for exploring and managing WordPress plugins and themes from the FAIR ecosystem.
+A WordPress plugin that provides a comprehensive repository browser for exploring and managing WordPress plugins, themes, and TYPO3 extensions from the FAIR ecosystem.
 
 ## Features
 
-- 🔍 **Package Search & Browse** - Search and explore WordPress plugins and themes with detailed information
+- 🔍 **Package Search & Browse** - Search and explore WordPress plugins, themes, and TYPO3 extensions with detailed information
 - 🎨 **Theme Discovery** - Browse and preview WordPress themes with live demos
-- � **Plugin Management** - Discover and explore WordPress plugins
-- �🛒 **Cart Functionality** - Add packages to cart with persistent storage via cookies
+- 🔌 **Plugin Management** - Discover and explore WordPress plugins
+- 🧩 **TYPO3 Extensions** - Browse and search TYPO3 extensions from the extensions API
+- 🛒 **Cart Functionality** - Add packages to cart with persistent storage via cookies
 - 🎮 **WordPress Playground Integration** - Generate blueprint URLs for instant WordPress demos
 - ✨ **Interactive UI** - Modern lightbox galleries, floating cart button, and smooth animations
 - 📱 **Responsive Design** - Mobile-friendly interface with SCSS-powered styling
@@ -20,7 +21,7 @@ A WordPress plugin that provides a comprehensive repository browser for explorin
 1. Download or clone this repository
 2. Place the `fair-explorer` folder in your `/wp-content/plugins/` directory
 3. Activate the plugin through the 'Plugins' menu in WordPress
-4. Create pages with slugs `plugins` and `themes` for the archive pages
+4. Create pages with slugs `plugins`, `themes`, and optionally set up TYPO3 extension routes for the archive pages
 
 ## Template Hierarchy & Customization
 
@@ -30,41 +31,42 @@ Fair-Explorer supports WordPress template hierarchy, allowing themes to override
 
 1. **Child Theme** (highest priority): `wp-content/themes/child-theme/fair-explorer/[template-file]`
 2. **Parent Theme**: `wp-content/themes/active-theme/fair-explorer/[template-file]`  
-3. **Plugin Default** (fallback): `wp-content/plugins/fair-explorer/includes/view/[template-file]`
+3. **Plugin Default** (fallback): `wp-content/plugins/fair-explorer/includes/views/[template-file]`
 
 ### Available Templates
 
 You can override these template files in your theme:
 
-**Search Forms:**
-- `themes-search-form.php` - Theme search form
-- `plugins-search-form.php` - Plugin search form
+**Plugins:**
+- `plugins/plugins-search-form.php` - Plugin search form
+- `plugins/archive/plugins.php` - Plugins listing page
+- `plugins/archive/plugin.php` - Individual plugin card in the archive
+- `plugins/single/plugin.php` - Individual plugin display
 
-**Archive Templates:**
-- `archive/themes.php` - Themes listing page
-- `archive/plugins.php` - Plugins listing page
+**Themes:**
+- `themes/themes-search-form.php` - Theme search form
+- `themes/archive/themes.php` - Themes listing page
+- `themes/archive/theme.php` - Individual theme card in the archive
+- `themes/single/theme.php` - Individual theme display
 
-**Single Templates:**
-- `single/theme.php` - Individual theme display
-- `single/plugin.php` - Individual plugin display
+**TYPO3 Extensions:**
+- `extensions/extensions-search-form.php` - Extension search form
+- `extensions/archive/extensions.php` - Extensions listing page
+- `extensions/archive/extension.php` - Individual extension card in the archive
+- `extensions/single/extension.php` - Individual extension display
 
 ### Example Theme Override
 
 To customize the themes listing in your theme:
 
-1. Create folder: `wp-content/themes/your-theme/fair-explorer/`
-2. Copy: `wp-content/plugins/fair-explorer/includes/view/archive/themes.php`
-3. Paste to: `wp-content/themes/your-theme/fair-explorer/archive/themes.php`
+1. Create folder: `wp-content/themes/your-theme/fair-explorer/themes/archive/`
+2. Copy: `wp-content/plugins/fair-explorer/includes/views/themes/archive/themes.php`
+3. Paste to: `wp-content/themes/your-theme/fair-explorer/themes/archive/themes.php`
 4. Customize as needed
 
-Your customizations will be preserved during plugin updates.
-
-## Installation
+Each overridable template receives an `$args` array with all the data it needs. The type-specific templates (e.g. `plugins/archive/plugins.php`) delegate to shared partials internally, but when you override a template, you have full control and can write completely custom markup.
 
-1. Download or clone this repository
-2. Place the `fair-explorer` folder in your `/wp-content/plugins/` directory
-3. Activate the plugin through the 'Plugins' menu in WordPress
-4. Create pages with slugs `plugins` and `themes` for the archive pages
+Your customizations will be preserved during plugin updates.
 
 ## Configuration
 
@@ -83,6 +85,8 @@ Create WordPress pages with these exact slugs:
 - **plugins** - For the plugins archive and individual plugin pages
 - **themes** - For the themes archive and individual theme pages
 
+TYPO3 extensions use the hardcoded root `packages/typo3`, so the archive is served at `packages/typo3/extensions/`. Ensure a WordPress page exists at that path for the content to render on.
+
 
 ## URL Structure
 
@@ -96,6 +100,10 @@ With the default configuration, your URLs will be:
 - Archive: `yoursite.com/packages/themes/`
 - Individual: `yoursite.com/packages/themes/theme-name/`
 
+**TYPO3 Extensions:**
+- Archive: `yoursite.com/packages/typo3/extensions/`
+- Individual: `yoursite.com/packages/typo3/extensions/extension-name/`
+
 **REST API:**
 - Playground Blueprint: `yoursite.com/wp-json/fair-explorer/v1/playground/blueprint`
 
@@ -176,36 +184,56 @@ Returns a JSON blueprint compatible with WordPress Playground:
 ```
 fair-explorer/
 ├── includes/
-│   ├── controller/          # MVC Controllers
-│   │   ├── class-main.php      # Main plugin controller
-│   │   ├── class-packages.php  # Unified packages controller (themes & plugins)
-│   │   └── class-playground.php # WordPress Playground API
-│   ├── model/              # Data Models  
-│   │   ├── class-singleton.php   # Base singleton pattern
-│   │   ├── class-plugin-info.php # Plugin data model
-│   │   └── class-theme-info.php  # Theme data model
-│   ├── view/               # Template Files (Plugin Defaults)
-│   │   ├── archive/           # Archive page templates
-│   │   │   ├── plugins.php
-│   │   │   └── themes.php
-│   │   ├── single/            # Single item templates  
-│   │   │   ├── plugin.php
-│   │   │   └── theme.php
-│   │   ├── plugins-search-form.php
-│   │   └── themes-search-form.php
-│   ├── class-utilities.php    # Template hierarchy helper
-│   └── autoload.php           # PSR-4 autoloader
+│   ├── controller/              # MVC Controllers
+│   │   ├── class-main.php          # Main plugin controller
+│   │   ├── class-packages.php      # Unified packages controller (plugins, themes & extensions)
+│   │   ├── class-typo3.php         # TYPO3 extensions API fetcher
+│   │   └── class-playground.php    # WordPress Playground API
+│   ├── model/                   # Data Models
+│   │   ├── class-singleton.php     # Base singleton pattern
+│   │   ├── class-assetinfo.php     # Base asset model (shared properties & methods)
+│   │   ├── class-plugininfo.php    # Plugin data model
+│   │   ├── class-themeinfo.php     # Theme data model
+│   │   └── class-extensioninfo.php # TYPO3 extension data model
+│   ├── views/                   # Template Files (Plugin Defaults)
+│   │   ├── plugins/                # Plugin templates (overridable)
+│   │   │   ├── archive/
+│   │   │   │   ├── plugins.php
+│   │   │   │   └── plugin.php
+│   │   │   ├── single/
+│   │   │   │   └── plugin.php
+│   │   │   └── plugins-search-form.php
+│   │   ├── themes/                 # Theme templates (overridable)
+│   │   │   ├── archive/
+│   │   │   │   ├── themes.php
+│   │   │   │   └── theme.php
+│   │   │   ├── single/
+│   │   │   │   └── theme.php
+│   │   │   └── themes-search-form.php
+│   │   ├── extensions/             # TYPO3 extension templates (overridable)
+│   │   │   ├── archive/
+│   │   │   │   ├── extensions.php
+│   │   │   │   └── extension.php
+│   │   │   ├── single/
+│   │   │   │   └── extension.php
+│   │   │   └── extensions-search-form.php
+│   │   └── shared/                 # Shared partials (internal, not overridable)
+│   │       ├── archive-list.php       # Generic archive listing
+│   │       ├── archive-card.php       # Generic archive card
+│   │       ├── search-form.php        # Generic search form
+│   │       └── single.php             # Generic single view
+│   └── autoload.php             # PSR-4 autoloader
 ├── assets/
 │   ├── js/
-│   │   └── fair-explorer.js    # Main JavaScript (ES6 classes)
+│   │   └── fair-explorer.js     # Main JavaScript (ES6 classes)
 │   ├── scss/
-│   │   ├── fair-explorer.scss  # Main SCSS file
+│   │   ├── fair-explorer.scss   # Main SCSS file
 │   │   ├── _cart.scss           # Cart styling
 │   │   ├── _lightbox.scss       # Lightbox component
 │   │   └── _search.scss         # Search components
 │   └── css/
-│       └── fair-explorer.css   # Compiled CSS
-└── composer.json           # PHP dependencies and scripts
+│       └── fair-explorer.css    # Compiled CSS
+└── composer.json                # PHP dependencies and scripts
 ```
 
 
@@ -284,7 +312,7 @@ The cart system allows users to collect packages for later reference:
 ### Rewrite Rules Not Working
 
 1. Go to **Settings > Permalinks** and click "Save Changes"
-2. Ensure your pages have the correct slugs (`plugins`, `themes`)
+2. Ensure your pages have the correct slugs (`plugins`, `themes`, etc.)
 3. Check that `AE_ROOT` constant matches your URL structure
 4. Verify `Packages` class instances are properly initialized
 

includes/controller/class-main.php

@@ -7,6 +7,9 @@
 
 namespace FairExplorer\Controller;
 
+use FairExplorer\Controller\Typo3\Typo3;
+use FairExplorer\Controller\WordPress\Playground;
+
 class Main extends \FairExplorer\Model\Singleton {
 	/**
 	 * Constructor.
@@ -33,23 +36,38 @@ public static function get_platforms() {
 
 		$platforms = [
 			[
-				'asset_type'  => 'plugins',
-				'root'        => $root,
-				'model_class' => 'FairExplorer\Model\PluginInfo',
-				'fetcher'     => null,
+				'asset_type'   => 'plugins',
+				'root'         => $root,
+				'view_prefix'  => 'wordpress',
+				'model_class'  => 'FairExplorer\Model\PluginInfo',
+				'fetcher'      => null,
+				'css_prefix'   => 'plugin',
+				'label'        => 'Plugin',
+				'label_plural' => 'Plugins',
+				'search_label' => 'Search WordPress Plugins',
 			],
 			[
-				'asset_type'  => 'themes',
-				'root'        => $root,
-				'model_class' => 'FairExplorer\Model\ThemeInfo',
-				'fetcher'     => null,
+				'asset_type'   => 'themes',
+				'root'         => $root,
+				'view_prefix'  => 'wordpress',
+				'model_class'  => 'FairExplorer\Model\ThemeInfo',
+				'fetcher'      => null,
+				'css_prefix'   => 'theme',
+				'label'        => 'Theme',
+				'label_plural' => 'Themes',
+				'search_label' => 'Search WordPress Themes',
 			],
 			[
-				'asset_type'  => 'extensions',
-				'root'        => 'packages/typo3',
-				'slug_var'    => 'extension_slug',
-				'model_class' => 'FairExplorer\Model\ExtensionInfo',
-				'fetcher'     => [ Typo3::class, 'fetch' ],
+				'asset_type'   => 'extensions',
+				'root'         => 'packages/typo3',
+				'view_prefix'  => 'typo3',
+				'slug_var'     => 'extension_slug',
+				'model_class'  => 'FairExplorer\Model\ExtensionInfo',
+				'fetcher'      => [ Typo3::class, 'fetch' ],
+				'css_prefix'   => 'typo3-extension',
+				'label'        => 'Extension',
+				'label_plural' => 'Extensions',
+				'search_label' => 'Search TYPO3 Extensions',
 			],
 		];
 

includes/controller/class-packages.php

@@ -50,6 +50,31 @@ class Packages {
 	 */
 	protected $fetcher;
 
+	/**
+	 * CSS class prefix for this asset type (e.g. 'plugin', 'theme', 'typo3-extension').
+	 */
+	protected $css_prefix;
+
+	/**
+	 * Singular display label (e.g. 'Plugin', 'Theme', 'Extension').
+	 */
+	protected $label;
+
+	/**
+	 * Plural display label (e.g. 'Plugins', 'Themes', 'Extensions').
+	 */
+	protected $label_plural;
+
+	/**
+	 * Search input placeholder / label text.
+	 */
+	protected $search_label;
+
+	/**
+	 * View directory prefix (e.g. 'wordpress', 'typo3').
+	 */
+	protected $view_prefix;
+
 	/**
 	 * Constructor.
 	 *
@@ -64,6 +89,11 @@ public function __construct( $config = 'plugins' ) {
 		$this->asset_singular = rtrim( $this->asset_type, 's' );
 		$this->model_class    = $config['model_class'];
 		$this->fetcher        = $config['fetcher'] ?? null;
+		$this->css_prefix     = $config['css_prefix'] ?? $this->asset_singular;
+		$this->label          = $config['label'] ?? ucfirst( $this->asset_singular );
+		$this->label_plural   = $config['label_plural'] ?? ucfirst( $this->asset_type );
+		$this->search_label   = $config['search_label'] ?? 'Search ' . ucfirst( $this->asset_type );
+		$this->view_prefix    = $config['view_prefix'] ?? '';
 
 		$root = $config['root'] ?? '';
 		if ( '' !== $root ) {
@@ -106,10 +136,11 @@ protected static function legacy_config( $asset_type ) {
 		];
 
 		return [
-			'asset_type'  => $asset_type,
-			'root'        => $root,
-			'model_class' => $model_map[ $asset_type ] ?? 'FairExplorer\Model\PluginInfo',
-			'fetcher'     => null,
+			'asset_type'   => $asset_type,
+			'root'         => $root,
+			'view_prefix'  => 'wordpress',
+			'model_class'  => $model_map[ $asset_type ] ?? 'FairExplorer\Model\PluginInfo',
+			'fetcher'      => null,
 		];
 	}
 
@@ -389,11 +420,16 @@ public function the_content( $content ) {
 	protected function archive_the_content( $search_keyword ) {
 		ob_start();
 
+		$view_base = $this->view_prefix . DIRECTORY_SEPARATOR . $this->asset_type;
+
 		Utilities::include_file(
-			$this->asset_type . DIRECTORY_SEPARATOR . $this->asset_type . '-search-form.php',
+			$view_base . DIRECTORY_SEPARATOR . $this->asset_type . '-search-form.php',
 			[
 				'target_page_slug' => $this->target_page_slug,
 				'search_keyword'   => $search_keyword,
+				'css_prefix'       => $this->css_prefix,
+				'search_label'     => $this->search_label,
+				'label'            => $this->label,
 			]
 		);
 
@@ -409,13 +445,21 @@ protected function archive_the_content( $search_keyword ) {
 		}
 
 		Utilities::include_file(
-			$this->asset_type . DIRECTORY_SEPARATOR . 'archive' . DIRECTORY_SEPARATOR . $this->asset_type . '.php',
+			$view_base . DIRECTORY_SEPARATOR . 'archive' . DIRECTORY_SEPARATOR . $this->asset_type . '.php',
 			[
 				'target_page_slug'            => $this->target_page_slug,
 				$this->asset_type . '_result' => $this->api_response->$results_property,
+				'results'                     => $this->api_response->$results_property,
 				'current_page'                => max( 1, get_query_var( 'paged' ) ),
 				'total_results'               => $this->api_response->info['results'],
 				'total_pages'                 => ceil( $this->api_response->info['results'] / $this->default_search_results_per_page ),
+				'css_prefix'                  => $this->css_prefix,
+				'label'                       => $this->label,
+				'label_plural'                => $this->label_plural,
+				'model_class'                 => $this->model_class,
+				'asset_type'                  => $this->asset_type,
+				'asset_singular'              => $this->asset_singular,
+				'view_prefix'                 => $this->view_prefix,
 			]
 		);
 
@@ -438,10 +482,16 @@ protected function single_the_content( $asset_slug ) {
 		$model_class = $this->model_class;
 		$asset_info  = new $model_class( $this->api_response );
 
+		$view_base = $this->view_prefix . DIRECTORY_SEPARATOR . $this->asset_type;
+
 		Utilities::include_file(
-			$this->asset_type . DIRECTORY_SEPARATOR . 'single' . DIRECTORY_SEPARATOR . $this->asset_singular . '.php',
+			$view_base . DIRECTORY_SEPARATOR . 'single' . DIRECTORY_SEPARATOR . $this->asset_singular . '.php',
 			[
 				$this->asset_singular . '_info' => $asset_info,
+				'asset_info'                    => $asset_info,
+				'css_prefix'                    => $this->css_prefix,
+				'asset_type'                    => $this->asset_type,
+				'label'                         => $this->label,
 			]
 		);