# CategoryContent: Magento 2 Category Page Hero Banners and FAQ

> Add hero banners, FAQ tabs, and rich details blocks to every Magento 2 category page - managed entirely from the admin, no theme edits required.

---

## Overview

CategoryContent gives every Magento 2 category page a full suite of rich content tools: full-width hero banners with AI-generated backgrounds, collapsible FAQ tabs, and custom details blocks. All content is authored and maintained from the admin - no theme edits required. Heroes support image or solid-colour backgrounds, gradient overlays, and fine-grained typographic controls, while FAQs surface the most useful answers first via built-in popularity tracking.

![CategoryContent heroes and FAQ admin overview](images/overview.png)

This module helps you:

- Add and manage per-category hero banners with images, colours, gradients, and custom title styling
- Bulk-generate on-brand hero images using AI providers (Claude, GPT Image, Gemini, DALL-E 3, and others) without leaving the admin
- Publish category FAQ sections and auto-sort questions by shopper popularity
- Add a rich Details tab to category pages, sourced from custom WYSIWYG content or the existing category description
- Import and export heroes, FAQs, and details via CSV for bulk catalogue management

---

## When to use this

Use CategoryContent when you want to:

- Replace plain category page headers with full-width branded hero banners
- Keep a per-category FAQ section that automatically prioritises the most-clicked questions
- Give category pages a structured details or description tab without editing theme templates
- Populate or update hero content across hundreds of categories from a single CSV import
- Generate hero background images in bulk using AI, then review and activate the best ones

---

## Key capabilities

- **Category heroes** - per-category background images or solid-colour heroes with gradient overlays, custom fonts, and colour controls
- **AI image generation** - multi-provider pipeline (Claude, GPT Image, Gemini 2.5 Flash, Gemini 3 Pro, DALL-E 3, OpenRouter) that queues and processes images via cron
- **FAQ tabs** - category-scoped FAQ sections with click tracking, popularity sorting, and a three-mode sort strategy (manual / popularity / hybrid)
- **Details blocks** - category details tab with WYSIWYG editor and flexible source control (category description, custom content, or none)
- **CSV round-trip** - import and export heroes, FAQs, and details for bulk updates; supports category names in addition to IDs
- **Live site export** - download all current category hero content as a CSV from the running store, ready for AI processing or migration
- **Mobile-responsive controls** - per-breakpoint focus point, zoom, and slim-text settings for hero images on phones and tablets

---

## Installation

CategoryContent installs via Composer, then activates with a license key from your Moogento.com account. The whole flow takes about 5 minutes.

### Step 1: Get your Composer keys from Moogento.com

1. Sign in at **https://www.moogento.com** and open **My Plugins** in your account menu.
2. Find **CategoryContent** in the list of plugins you own.
3. Generate (or reveal) the Composer access keys for that plugin - a **public key** and a **private key**.
4. **Add your install domain to the key.** Each Composer key is tied to a specific domain - if you're installing on `yourstore.com`, add `yourstore.com` to the key's allowed domains. The Composer download will be rejected on any other domain.

If you run staging and production on different domains, add both - separate keys per environment are fine too.

### Step 2: Install the module with Composer

From your Magento 2 root directory:

```
composer require moogento/module-categorycontent
```

When Composer asks for credentials, paste the **public key** as the username and the **private key** as the password. They'll be cached in `~/.composer/auth.json` for future runs.

### Step 3: Enable the module in Magento

```
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:clean
```

If you run `php bin/magento module:status Moogento_Categorycontent` you should see it listed as enabled.

### Step 4: Add your license key in the Moogento admin

1. Still on **https://www.moogento.com > My Plugins**, copy the **license key** for CategoryContent (separate from the Composer keys you used above).
2. In your Magento admin, go to **Stores > Configuration > Moogento > Licenses**.
3. Find the row for **CategoryContent** and paste the license key.
4. Click **Save Config**, then run `php bin/magento cache:clean` once.

The license validates within a few seconds. You should see the module's status flip to active. If it stays inactive, double-check the domain on the license matches where you've installed - domain mismatch is the most common cause.

---

## Setup overview

Most setup happens in:

Stores > Configuration > Moogento > CategoryContent

You'll mainly work with:

- **General** - master enable switch, logging, custom CSS, and live-site export
- **Category: Hero** - enable heroes, typography, colours, gradient overlay, fallback image, mobile/tablet breakpoints, and AI image generation
- **Category: Details & FAQ** - enable the Details and FAQ tabs, expandable descriptions, and FAQ popularity sorting
- **CMS: FAQ Widget** - settings for FAQ widgets placed on CMS pages (homepage, contact, etc.)

Day-to-day content work happens in the three admin grids under **Catalog > CategoryContent**:

- **Heroes** - create, edit, and generate AI images for category heroes
- **Details** - manage per-category detail content blocks
- **FAQs** - create, import, and manage FAQ questions across categories

---

## Common setups

### Enable category heroes and add your first banner

Give your category pages a branded header instead of the plain Magento title block.

#### How to set it up

1. Go to:
   Stores > Configuration > Moogento > CategoryContent > General

2. Set:
   - **Enable** = Yes

3. Go to:
   Stores > Configuration > Moogento > CategoryContent > Category: Hero

4. Set:
   - **Enable: Category Heroes** = Yes
   - **Remove: Default Header Section** = Yes (hides the stock Magento category title)

5. Save Config, then run `php bin/magento cache:clean`.

6. Go to **Catalog > CategoryContent > Heroes** and click **Add New** (or find the auto-created hero for the category you want).

7. Set the background type to **Image** and upload a photo, or set it to **Color** and pick a hex value. Add above-title blurb text and a title if needed.

8. Save the hero. Clear `layout`, `block_html`, and `full_page` caches to see the change on the storefront.

![CategoryContent General config group](images/config-general.png)

#### Notes

- Heroes are linked to categories by category ID. CategoryContent can auto-create a blank hero for every category - use the Heroes grid mass actions to do this in bulk.
- If a hero is set to **Image** but no image is uploaded, the fallback image set in Stores > Configuration > Moogento > CategoryContent > Category: Hero > Style: Background is shown.

---

### Set up AI hero image generation

Generate on-brand hero background images across your catalogue using AI providers - no designer required.

#### How to set it up

1. Go to:
   Stores > Configuration > Moogento > CategoryContent > Category: Hero > AI: Image Generation

2. Set:
   - **Enable: AI Image Generation** = Yes

3. Expand **Providers** and click **Add Provider** to add your first AI provider. Fill in:
   - Provider type (e.g. `claude_gpt_image`, `gemini_flash`, `dalle3`)
   - API key
   - Roles to assign (`prompt`, `image_primary`, `image_secondary`)

4. Expand **Prompts > General Context**. Enter your homepage and about-us URLs, then click **Auto-Generate: Style 1 Prompt** to let the AI analyse your site and write a brand context prompt. Review and adjust the generated text in the **Style 1 General Prompt** field.

5. Expand **Image Creation** and set:
   - **Generate: Images Per Request** = 2–4 (depends on your API plan)
   - **Max Generations: Per Hero** = 4 (keeps storage manageable)
   - **Auto-Select: Latest Generation** = Yes (automatically activates the newest image)

6. Save Config.

7. Go to **Catalog > CategoryContent > Heroes**, select the heroes you want to generate images for, and use the mass action **Generate AI Images** to add them to the queue.

8. Cron processes the queue automatically. To check queue status, run:
   ```
   php bin/magento moogento:categorycontent:ai:queue-status
   ```

9. Once images appear in each hero's AI gallery, open the hero, review the generated options, and click the one you want to make active.

![CategoryContent AI: Image Generation config group](images/config-ai-image-generation.png)

#### Notes

- Cron must be running. If images are not generating, look for the admin notification "CategoryContent: Please check your Magento cron is running".
- Product images from the category can be sent as context to the AI - enable **Include: Product Images for Context** under **Prompts > Product Context** for more relevant results.
- On local or staging environments where product image URLs are not publicly reachable, set **Replacement Reachable URL: For Product Images** to a public tunnel or staging domain.

---

### Set up Magento 2 category page FAQ tabs

Add an expandable FAQ section to every category page and let shopper behaviour determine which questions appear first.

#### How to set it up

1. Go to:
   Stores > Configuration > Moogento > CategoryContent > Category: Details & FAQ

2. Set:
   - **Enable: Details Tab** = Yes (to show the category description in a tab)
   - **Enable: FAQ Tab** = Yes
   - **Enable: FAQ Popularity Sorting** = Yes
   - **FAQ: Frontend Sort Method** = **Hybrid** (recommended - balances manual order with click count)

3. Save Config.

4. Go to **Catalog > CategoryContent > FAQs** and click **Add New FAQ**. Fill in:
   - Question
   - Answer
   - Category assignments
   - Sort order

5. Save. Clear `full_page` cache to see the FAQ tab on the storefront.

![CategoryContent Category: Details & FAQ config group](images/config-category-tabs.png)

#### Notes

- The FAQ tab only appears on the first pagination page of a category and only when at least one active FAQ exists for that category.
- Popularity data builds up over time. Allow 2–3 weeks of click data before evaluating the Hybrid sort results.
- To import many FAQs at once, use **Catalog > CategoryContent > FAQs > Import** and upload a CSV with columns: `question`, `answer`, `sort_order`, `is_active`, `categories` (ID or name).

---

### Download live-site hero content for bulk editing or AI processing

Export all current category hero content to CSV - useful for migration, backup, or feeding to an AI pipeline.

#### How to set it up

1. Go to:
   Stores > Configuration > Moogento > CategoryContent > General

2. Click **Download: Category data from site**.

3. Select the store view if prompted, then click **Download**.

4. A CSV file downloads with columns for category name, above-title text, main title, below-title text, category description, image URL, and store ID.

5. Edit the CSV (or pass it through an AI tool), then re-import via **Catalog > CategoryContent > Heroes > Import**.

#### Notes

- Extraction crawls every active category page via HTTP. For large catalogues (100+ categories) this may take several minutes.
- Progress is logged to `var/log/moogento_categorycontent.log`.

---

## Features reference

### Category: Hero - Titles styling

Control the typography inside every category hero globally. These settings apply unless a specific hero overrides them.

- **What it does:** Sets font colour, font size, text shadow, and above/below-title blurb styling across all category heroes.
- **When to use it:** When your brand uses a specific heading size or colour that differs from the theme default.
- **Config path:** Stores > Configuration > Moogento > CategoryContent > Category: Hero > Hero: Titles

The style picker for each property offers three options: **Inherit from theme**, **CategoryContent default**, or **Custom**. Selecting Custom reveals a colour picker or size input. Per-hero overrides in the Heroes grid offer a fourth option - **Use module config** - so individual heroes can defer to these global settings.

---

### Category: Hero - Style: Background

Upload a fallback image for heroes and control the gradient overlay on background images.

- **What it does:** Provides a store-wide fallback image when a hero is set to Image mode but has no image uploaded. Also enables or disables the dark left-to-right gradient overlay that improves text legibility over busy photos.
- **When to use it:** Set a fallback image at launch so no hero ever shows a blank background.
- **Config path:** Stores > Configuration > Moogento > CategoryContent > Category: Hero > Style: Background
- Technical path: `moogento_categorycontent/category_head/style_background/hero_fallback_image`

---

### Category: Hero - Style: Mobile

Control how hero background images position and scale on phones and tablets.

- **What it does:** Sets default focus point (horizontal position) and zoom level for mobile and tablet breakpoints, and lets you define the pixel widths where mobile and tablet layouts kick in.
- **When to use it:** When hero images have a focal point (a face, product, or logo) that appears off-screen on smaller devices.
- **Config path:** Stores > Configuration > Moogento > CategoryContent > Category: Hero > Style: Mobile
- Individual heroes can override these defaults from the hero edit page.

---

### CMS: FAQ Widget

Embed FAQ blocks on CMS pages (homepage, contact page, landing pages) outside the category context.

- **What it does:** Configures the default visual style, interaction behaviour (accordion vs. always-open), icon style, mobile breakpoint, and background images for the CMS FAQ widget.
- **When to use it:** When you want a FAQ section on your homepage or other CMS pages, not just on category pages.
- **Config path:** Stores > Configuration > Moogento > CategoryContent > CMS: FAQ Widget

To place the widget, use Magento's standard widget insertion in any CMS page or block. Use the background image gallery to find media paths, then reference them in the widget code as:
```
bg_image="{{media url='categorycontent/cms-faqs/filename.jpg'}}"
```

---

### Details blocks

Control whether a Details tab appears on category pages and what content it shows.

- **What it does:** Adds a Details tab beneath the hero. The tab can show the standard Magento category description, a custom WYSIWYG block from the Details grid, or nothing (disabled per category).
- **When to use it:** When you want category descriptions in a collapsible tab rather than inline, or when you need custom content that differs from the category description attribute.
- **Config path:** Stores > Configuration > Moogento > CategoryContent > Category: Details & FAQ > Enable: Details Tab
- Manage per-category content at: Catalog > CategoryContent > Details

The Details grid supports mass actions to switch all selected details to category-description mode, custom-content mode, or none.

---

## Advanced configuration

### AI Prompts - dual visual style system

CategoryContent supports two simultaneous visual styles for AI image generation, allowing you to generate a standard variation and a more artistic or experimental variation for each hero.

#### What it does

Style 1 (primary) is typically your main brand direction. Style 2 (secondary) can be set to a more creative direction. Each has its own general brand context prompt and an independently configurable Visual Style setting (Photo-realistic, Illustration, Abstract, and others, plus Auto).

#### Setup

1. Go to:
   Stores > Configuration > Moogento > CategoryContent > Category: Hero > AI: Image Generation > Prompts

2. Under **Visual Style**, set **Model 1 Visual Style** and (if using) **Model 2 Visual Style**.

3. Under **General Context**, generate or write both Style 1 and Style 2 brand context prompts.

4. Under **Image Creation**, enable **Auto-Split: Between Models**. When Images Per Request > 1, generation requests are split between your primary and secondary image providers so each hero receives one image from each style direction.

#### Notes

- Auto-Split requires a secondary image provider to be configured in the Providers Table with an `image_secondary` role.
- Auto-detected visual styles (when set to **Auto**) are populated after you run prompt generation for a hero. The read-only **Detected Style** fields show what the AI chose.

---

### FAQ popularity sorting and cron

The popularity sorting system tracks every FAQ click on the storefront and runs a nightly cron to re-sort questions by engagement.

#### What it does

Shoppers expand FAQ questions during normal browsing. Each expansion is tracked via a non-blocking AJAX call (de-duplicated per session). A cron job at 2 AM daily recalculates sort order using the chosen method.

**Sort method options** (`moogento_categorycontent/category_tabs/faq_sort_method`):

| Method | Behaviour |
|---|---|
| Manual | Uses `sort_order` only - full admin control |
| Popularity | Sorts by click count descending - fully data-driven |
| Hybrid | Combines manual order and click count - recommended |

#### Setup

1. Go to:
   Stores > Configuration > Moogento > CategoryContent > Category: Details & FAQ

2. Set **Enable: FAQ Popularity Sorting** = Yes and choose a **FAQ: Frontend Sort Method**.

3. Save Config. Ensure Magento cron is running (`crontab -l` or your server cron manager).

#### Notes

- With Hybrid sorting, you can still influence position via the Sort Order field on each FAQ - higher-clicked FAQs naturally rise within their manual range.
- The admin FAQ grid shows a **Clicks** column so you can see which questions attract the most engagement.
- Give the system 2–3 weeks of data before drawing conclusions on FAQ performance.

---

## Tips & best practices

- Clear the `layout`, `block_html`, and `full_page` caches after every hero background or style change - the new styles won't appear until those cache types are flushed.
- Use the **Download: Category data from site** button to export your current category content before making bulk changes. It gives you an instant backup and a ready-made CSV for AI enhancement.
- For AI image generation, write a specific and detailed general prompt - describe brand colours, mood, audience, and product types. The more context the AI has, the more on-brand the results.
- Start AI image generation on a small subset of 5–10 category heroes before running bulk generation across the whole catalogue. Review the results and adjust your general prompt before scaling up.
- Use the **Hybrid** FAQ sort method from the start. It respects your initial manual ordering while letting popular questions rise over time - you can always override individual FAQ positions without rebuilding the entire list.
- Set a global fallback hero image so every category has a presentable background even before you've uploaded or generated category-specific images.
- On multi-store installations, the CategoryContent config section only appears at the Default scope (showInWebsite="0"). Manage heroes, FAQs, and details at the default scope and rely on Magento's standard category scoping for store-specific content.

---

## Troubleshooting

### Heroes or FAQ tabs not appearing on the storefront

Category content is not visible on the live site after saving.

- **Cause:** Stale cached layout or block HTML from before the content was added.
- **Check:** Verify the module is enabled at Stores > Configuration > Moogento > CategoryContent > General > Enable = Yes, and that Category Heroes or FAQ tabs are enabled in their respective groups.
- **Resolution:** Run `php bin/magento cache:clean` with specific types: `php bin/magento cache:clean layout block_html full_page`. If the hero is set to Image but no image shows, check that a fallback image is set or that the hero has an image selected.

---

### AI images are not being generated

The Heroes grid shows items in the queue but no images appear after a long wait.

- **Cause:** Magento cron is not running, stopping the `ProcessAiImageQueue` job from executing.
- **Check:** Look for the admin notification "CategoryContent: Please check your Magento cron is running". Run `php bin/magento moogento:categorycontent:ai:queue-status` to see queue depth and last-processed time.
- **Resolution:** Confirm cron is active on your server. To process a batch immediately without waiting for cron, run `php bin/magento moogento:categorycontent:ai:process-queue`. After cron is confirmed running, new queue items will process automatically within the configured cron interval.

---

### AI provider connection is rejected

Running the image generation queue produces API errors in the log.

- **Cause:** API key is missing, expired, or does not have sufficient credits for the selected provider.
- **Check:** Run `php bin/magento categorycontent:ai:keys:check` to verify keys are present. Run `php bin/magento categorycontent:ai:test-connection` to test live connectivity. Check `var/log/moogento_categorycontent.log` for the specific error message.
- **Resolution:** Re-enter the API key in the Providers Table at Stores > Configuration > Moogento > CategoryContent > Category: Hero > AI: Image Generation > Providers. Ensure the provider's account has available credits.

---

### FAQ tab only appears on some category pages

FAQs are visible for a few categories but not others, even though FAQs exist in the grid.

- **Cause:** FAQ tabs only render on the first pagination page of a category, and only when at least one active FAQ is linked to that category.
- **Check:** Confirm the FAQ's status is Active and its category assignment includes the expected category. Open the category page without any `?p=2` or later pagination parameters.
- **Resolution:** Edit the FAQ record in **Catalog > CategoryContent > FAQs** and verify the categories list. Set Status = Enabled, then clear the `full_page` cache.

---

### CSV import says "Missing required CSV columns"

Importing heroes via CSV produces a validation error about missing headers.

- **Cause:** The CSV does not include the required column headers.
- **Check:** Heroes CSV must include: `category_id` (or `category_name`), `above_title_text`, `text_in_title`, `below_title_text`. FAQs CSV must include: `question`, `answer`, `sort_order`, `is_active`, `categories`.
- **Resolution:** Download the template CSV from the import form (Catalog > CategoryContent > Heroes > Import > Download Template), then map your data to the required headers.

---

## FAQs

<!-- seo: FAQPage schema - the page converter should emit JSON-LD for this section -->

## How do I add a hero banner to a specific category?

Go to **Catalog > CategoryContent > Heroes**, find or create the hero for that category, set the background type to Image or Color, upload or select an image, and save. Flush the layout and full-page cache to see the change on the storefront. Full steps are in the [Enable category heroes](#enable-category-heroes-and-add-your-first-banner) section above.

## How do I generate hero images with AI?

Enable AI Image Generation under Stores > Configuration > Moogento > CategoryContent > Category: Hero > AI: Image Generation, add an AI provider with its API key, generate a general brand context prompt, then select heroes in the Heroes grid and use the **Generate AI Images** mass action. The queue is processed by Magento cron. See [Set up AI hero image generation](#set-up-ai-hero-image-generation) for the full walkthrough.

## Why aren't my AI-generated hero images appearing?

The most common reason is that Magento cron is not running. CategoryContent processes AI image requests in a background queue that requires cron to execute. Check for the admin notification warning about cron, or run `php bin/magento moogento:categorycontent:ai:queue-status` to inspect the queue. See [Troubleshooting - AI images are not being generated](#ai-images-are-not-being-generated) for more detail.

## How do I add FAQs to a category page?

Go to **Catalog > CategoryContent > FAQs**, click **Add New FAQ**, fill in the question, answer, and category assignments, then save. Ensure the FAQ tab is enabled at Stores > Configuration > Moogento > CategoryContent > Category: Details & FAQ > Enable: FAQ Tab = Yes. See [Set up FAQ tabs](#set-up-magento-2-category-page-faq-tabs) for full steps.

## What is hybrid FAQ sorting and should I use it?

Hybrid sorting combines your manual sort order with live click counts so the most-clicked questions naturally rise within the position range you set, while you retain overall control. It is the recommended setting because it balances editorial curation with real shopper behaviour. Set it at Stores > Configuration > Moogento > CategoryContent > Category: Details & FAQ > FAQ: Frontend Sort Method = Hybrid.

## Does CategoryContent work with Hyvä themes?

Yes. A dedicated Hyvä compatibility module (`Hyva_MoogentoCategorycontent`) ships alongside CategoryContent. It replaces RequireJS/Knockout-based assets with Alpine.js and Tailwind-compatible equivalents, keeps the hero full-width on Hyvä category pages, and routes FAQ tracking through Hyvä's form-key mechanism. No manual template swaps are needed.

## What happens if I disable CategoryContent?

Disabling the module (or setting Enable = No in config) stops all category hero blocks, FAQ tabs, and details tabs from rendering on the storefront. Category pages revert to the standard Magento layout. Hero records, FAQ records, and details records remain in the database and are restored when the module is re-enabled.

## Can I import heroes and FAQs in bulk from a spreadsheet?

Yes. Export a template CSV from **Catalog > CategoryContent > Heroes > Import > Download Template** (or the FAQs import form), fill it in, and upload it back. The importer supports category names as well as category IDs, so you don't need to look up numeric IDs before importing.

## How do I move category description content into a collapsible Details tab?

Enable the Details tab at Stores > Configuration > Moogento > CategoryContent > Category: Details & FAQ > Enable: Details Tab = Yes, then go to **Catalog > CategoryContent > Details** and create a detail record for the category. Set Source = **Category Description** to pull the existing Magento category description into the tab automatically.

## Which AI providers does CategoryContent support?

CategoryContent supports Claude + GPT Image (`claude_gpt_image`), Claude + DALL-E 3 (`claude_dalle3`), Google Imagen 4 via Gemini Flash/Pro (`google_banana`), OpenRouter (`openrouter`), Gemini 2.5 Flash (`gemini_flash`), Gemini 3 Pro (`gemini_3_pro`), GPT Image 1.5 (`gpt_image`), and DALL-E 3 (`dalle3`). Configure them in the Providers Table under AI: Image Generation settings.

---

## Related guides

- **Moogento Licenses** - managing license keys for all Moogento modules (needed for CategoryContent activation)

---

## Need help?

- moo@moogento.com
- Include:
  - Magento version
  - Module name
  - What you're trying to do