List view and details page

• VidPly list view (mpc_vidply_listview) – displays one or more areas known as ‘shelves’ (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 the 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. This 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.

1.2 Creating the overview page

1. Insert a ‘VidPly Listview’ content element on your landing page (e.g. /mediathek ).
2. Under ‘Detail page’, select the page created in 1.1.
3. Under ‘Listview rows’, add one row per shelf and configure it 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 shelf 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 bar appears. Disable pagination to always display the complete set (up to the ‘Max. elements’ count). Each row is independent, even if a content element spans multiple list view rows.
   • Sort order (backend default when loading items) – manual/MM order, newest first or title A–Z. The frontend may provide a sort control so that visitors can change the order in the browser without reloading.
   • Selection mode – Manual (select entries manually) or Automatic (by category). The corresponding selection field appears 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 appear 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 confusion with redirects.

Records without a slug remain accessible: the list view automatically uses ?media=<uid>&cHash;=… automatically, so that 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), ensuring 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. For further information, see the ListviewProcessor and the extension’s TCA.

1.5 Media: Short and long text on the detail page

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

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

1.6 Title and breadcrumb for the details page

In a valid detail view, 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 navigation reads: Home › Media Library › My Great 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 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

lead 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 the database structure

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

• tx_mpcvidply_media.slug, and over time, for example, long_description (RTE) for detailed text
• tx_mpcvidply_listview_row (table) and columns such as enable_pagination / pagination_per_page for row-by-row client-side pagination
• 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 — Listview, 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 elements 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 the full list).

4. Accessibility

• Each map is a genuine <a> element (not just a JavaScript click target) with a visible focus ring; for readability, category chips and labels are positioned above the link overlay of the full map.
• The shelf’s scroll container can be controlled via 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 output in the page code <head> for SEO / rich results . List views are automatically integrated and link each card to the configured detail page. See Structured Data (JSON-LD).