List view and details page

• VidPly list view (mpc_vidply_listview) – displays one or more named ‘shelves’ (as a grid or horizontal scroll) containing media cards.
• VidPly detail view (mpc_vidply_detail) – displays the VidPly player and metadata for a single media record, identified by the URL slug.

Editor picks media/categories
      │
      ▼
 mpc_vidply_listview (Content Element)
   ├── row 1  (headline, layout, selection)
   ├── row 2
   └── row n
      │           each card: <a href="/mediathek/{slug}">
      ▼
 mpc_vidply_detail (Content Element, on routed page)
      │
      ▼
 Reuses VidPlyProcessor + VidPly.html player

1. Guidelines for Editors

1.1 Preparing a detail page

1. Create a standard page (e.g. ‘Media Library Detail’) at any location in the page tree.
2. Insert a single VidPly detail content element onto this page. The element requires no backend configuration – it simply identifies the requested media record at runtime based on the URL.
3. Make a note of the page UID; you will need to reference it in every list view element so that the card links know where to point to.

1.2 Creating the overview page

1. Insert a ‘VidPly Listview’ content element on your landing page (e.g. /mediathek ).
2. Under ‘Details page’, select the page created in 1.1.
3. Under ‘Listview rows’, add one row per shelf and configure them as follows:
   • Row heading – displayed above the row.
   • ‘Show all’ link (optional) – displayed next to the heading.
   • Layout – Horizontal shelf or responsive grid.
   • Card style – Poster (16:9), Compact (3:4) or Landscape.
   • Max. items – upper limit on the number of items loaded for the row.
   • Client-side pagination (optional, grid layout only) – the horizontal bar always uses scrolling within the row rather than paginated ‘pages’. Only with the responsive grid can you enable pagination and set the number of items per page (default: 12); if there are more items than this number, a pagination element appears. Disable pagination to always display the entire set (up to the maximum number of items). Each row is independent, even if a content item spans multiple ListView rows.
   • Sort order (backend default when loading items) – manual/MM order, newest first or title A–Z. The frontend may provide a sort control allowing visitors to change the order in the browser without reloading.
   • Selection mode – Manual (select entries manually) or Automatic (by category). The corresponding selection field is displayed below.

Cards display the title, optionally an artist line and category chips (from the media record’s own categories), where available.

Assigning categories:   For each VidPly media record , open the ‘Categories’ tab and select one or more categories. These are displayed on the cards in the list view and control the automatic (by category) row selection.

1.3 Slugs

Each record in tx_mpcvidply_media is automatically assigned a URL-friendly slug, generated from its title. Editors can override the slug on the ‘Metadata’ tab. Slugs are checked for uniqueness per website to avoid redirect ambiguities.

Records without a slug remain accessible: the list view automatically uses ?media=<uid>&cHash;=… automatically, so editors can publish a record first and add a more appealing URL later without breaking existing links.

1.4 Translated (linked) list view rows

On multilingual websites, the definitions of the list view shelves follow the content element of the default language (inline tx_mpcvidply_listview_row records are linked to the source tt_content UID), so that a translation is not ‘overlaid’ with empty placeholder rows. Configure the shelves once in the default language ; translated pages use the same rows unless you maintain separate row data. Further information can be found in the ListviewProcessor and the extension’s TCA.

1.5 Media: Short and long text on the detail page

In every VidPly media record, editors can use the following:

• Description – Short text.
• Long description – Rich text (CKEditor) for the details page; this is displayed below the short description using standard HTML formatting.

Cards in grid rows also display the detailed description without leaving the list: a small button in the bottom-right corner of the card opens it in a pop-over, which browser displays at the top level – so the text is neither cut off from the card nor does it extend beyond the height of a grid row. Shelf rows deliberately omit it: they trim vertical overflow and are designed for quick horizontal scanning.

The button is an element of equal rank to the card’s elongated link, never a subordinate element, so that the card never nests two controls. Toggling, soft-closing, the Escape key and returning focus to the button are handled natively; no JavaScript is required. Where the popover API is unavailable, a @supports not selector(:popover-open) query hides both the button and the panel, rather than copying the rich text into every card, and the detail page remains the place where it can be read.

1.6 Title and breadcrumb of the detail page

When a valid detail view is displayed, the extension automatically performs the following:

• replaces the title of the current breadcrumb element with the title of the media item, so that the breadcrumb reads: Home › Media Library › My brilliant episode;
• sets the HTML tag <title> tag via a special PageTitleProvider (priority: before the SEO and data record providers).

Both overrides only take effect if the current page contains a VidPly Detail CE and the URL contains a resolvable media parameter. On normal pages, the default behaviour remains unchanged.

If you set the detail page to ‘Hide in menu’ (so that it does not appear in the main navigation), enable the TypoScript extension of the site set page.10.dataProcessing.70.includeNotInMenu = 1 — it is included in the delivery mpc-vidply — so that the breadcrumb header row continues to list the hidden page and its parent pages (e.g. Home › Media Library › …). Without this extension, TYPO3’s standard HMENU nav_hide omits pages from the breadcrumb navigation, and the path may appear incorrect.

2. Administrator’s Guide

2.1 Automatic Route Enhancer (TYPO3 14.1+)

The extension contains a site set (Configuration/Sets/mpc-vidply/route-enhancers.yaml), which includes a Simple route enhancer and the MpcVidplyMediaRoute aspect (slug optional, query fallback) in the slug field of tx_mpcvidply_media. If your website uses the mpc-vidply Site Set, the enhancer is automatically applied – URLs of the form

example.com/mediathek/my-great-episode

are resolved to the detail page and load the referenced media record.

2.2 Manual fallback (TYPO3 < 14.1 or custom scope)

If you need to restrict the Enhancer to a specific page or are using an older version of TYPO3, add the following to config/sites/<site>/config.yaml:

routeEnhancers:
  VidPlyDetail:
    type: Simple
    routePath: '/{media}'
    limitToPages:
      - 42   # UID of the detail page
    defaultController: 'VidPly::detail'
    requirements:
      media: '[a-z0-9\-]+'
    aspects:
      media:
        type: MpcVidplyMediaRoute
        tableName: tx_mpcvidply_media
        routeFieldName: slug

2.3 Analyse database structure

After installing the extension, run the ‘Analyse database structure’ function via the installation tool (or typo3 database:updateschema). Among other things, the update adds the following fields:

• tx_mpcvidply_media.slug, and over time, for example, long_description (RTE) for detail text
• tx_mpcvidply_listview_row (table) and columns such as enable_pagination / pagination_per_page for client-side pagination by row
• tx_mpcvidply_listview_row_media_mm (MM for manual selection)
• tt_content.tx_mpcvidply_listview_rows and tt_content.tx_mpcvidply_detail_page

2.4 Clear the cache

Clear the TYPO3 cache once after updating the extension so that the new TypoScript, TCA and icon registrations are applied.

3. Front-end assets

The Listview content element always loads (grid and shelf):

• Resources/Public/Css/listview.min.css — list view, cards, detail-oriented layout, pager UI
• Resources/Public/JavaScript/Listview.min.js (ES module) — horizontal scrolling in the shelf and arrows, sorting <select> , client-side pagination (if a row is configured for pagination and contains more items than the page size) and optional display of cards

Both elements take into account prefers-reduced-motion and provide custom CSS properties for theming (see listview.css for the full list).

4. Accessibility

• Each map is a genuine <a> element (not just a JavaScript click target) with a visible focus ring; for the sake of readability, category chips and labels are positioned above the link overlay of the full map.
• The shelf’s scroll container can be operated using the keyboard (tabindex="0", navigation using the arrow keys / Home / End). The arrow keys are aria-controls and are disabled at the ends.
• The sorting controls and pagination <nav> use native <select> and <button> with corresponding labels; the pager can switch to a compact ‘Page x of y’ display when there are many pages.
• Poster images use native lazy loading (loading="lazy", decoding="async") and always feature a alt text derived from the media title.
• schema.org JSON-LD (VideoObject / AudioObjector a ItemList on gallery pages) is <head> for SEO / rich results . List views are automatically integrated and link each card to the configured detail page. See Structured Data (JSON-LD).