README

mhinspeya/mhinspeya-hyva-vimeogallery

Magento 2 / Hyvä module that displays reels-style video galleries sourced from Vimeo (project/folder, channel, or account library). Admin UI uses the Reels product name; fields that talk to Vimeo’s API stay labeled Vimeo (access token, project/folder ID, channel ID, API checks).

Includes GDPR-friendly local preview images, click-to-play on the standard web gallery, an optional in-app WebView feed (vertical snap + tap-to-play), toolbar search and category filters, portrait/landscape layouts, hero header and Instagram footer blocks, per-CMS-page embed profiles, separate config for Web Reels, CMS embeds, and App Reels, license validation, short-lived API caching, and LiteMage-friendly AJAX loading.

Requirements
Features
Installation
Configuration (admin)
CMS page reel embeds
License
Vimeo setup (sample)
Frontend usage
In-app WebView feed
Frontend routes & AJAX
GDPR & privacy (preview images)
Caching & LiteMage
Admin refresh
CLI
Troubleshooting: works locally, fails on server
Exception handling & logging
Development & Magento standards
Translations (i18n)
PHP compatibility
Uninstall
Post-install commands
Support
User guide

Requirements

Dependency	Notes
Magento 2.4.x	Tested with Magento 2.4.8
PHP `>= 7.2`	Compatible through current PHP 8.x
Hyvä Theme	Storefront uses Alpine.js AJAX loading
`mhinspeya/backend-mod`	Required (`^1.0`) for Inspeya admin menu / tab
Vimeo account	Personal access token with scopes for your chosen video source

Features

Storefront (web reels)

Gallery at configurable Reels URL path (web) (default segment: reels → /reels)
Per-CMS-page embeds via named profiles and {{block}} (see CMS page reel embeds)
Live video list via AJAX (page shell can be LiteMage / FPC cached)
Video source (admin dropdown, one at a time): Project / Folder, Channel, or all account videos (/me/videos)
Video privacy: public only (Vimeo “Anyone”) or all videos the token can list
GDPR-friendly previews: thumbnails under pub/media/vimeogallery/thumbnails/; Vimeo iframe loads after click on the standard grid
Display mode: Portrait (9:16) or Landscape (16:9)
Design, header/footer, pagination, search, and filters (see config sections)

In-app WebView feed (app reels)

When Enable App WebView Mode is Yes and the app opens the configured reels WebView URL:

Headless layout, full-viewport vertical feed, snap scroll
Tap-to-play (no autoplay on scroll)
Uses App Reels config paths (webview_general, webview_design, webview_loadmore) where set

Admin

Reels menu under Inspeya (Configuration, Web Reels, CMS Page, App Reels, CMS Page Reel Embeds)
Stores → Configuration → MHinspeya.de: nested Reels group with tabs License, Web Reels, CMS Page, App Reels (opens License first; no empty overview page)
Horizontal subnav on Reels config sections for quick tab switching
License key validation (Inspeya license service)
Encrypted Vimeo Access Token and source IDs per context (list / CMS / WebView)
Refresh video list now per section (clears cache, re-fetches Vimeo, refreshes previews)
CMS Page Reel Embeds: CRUD profiles, copy block directive, save-time Vimeo API probe
Save validation + post-save Vimeo probe on system config
CLI: vimeogallery:test-api, vimeogallery:seed-cms-embeds (sample data / QA)

Installation

For production environments, prefer your normal deploy flow. Use --keep-generated only when appropriate.

Type 1: Manual (Zip / app code)

Copy the module to:
```
app/code/MHinspeya/VimeoGallery
```
Ensure mhinspeya/backend-mod (MHinspeya_BackendMod) is installed.
Enable and upgrade:

php bin/magento module:enable MHinspeya_BackendMod MHinspeya_VimeoGallery
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush

Type 2: Composer

Add the Inspeya repository (if not already configured):

composer config repositories.inspeya composer https://repo.inspeya.com/

Require the package:

composer require mhinspeya/mhinspeya-hyva-vimeogallery

Enable and upgrade (same commands as above).

Verify module status

php bin/magento module:status MHinspeya_VimeoGallery

Expected: Module is enabled.

Configuration (admin)

Paths:

Stores → Configuration → MHinspeya.de → Reels (nested submenu + horizontal tabs)
Inspeya → Reels → Configuration (same config; lands on License)
Inspeya → Reels → CMS Page Reel Embeds (profile manager)

Section IDs (system.xml):

Tab (admin label)	Section ID	Purpose
License	`vimeogallery_license`	License key
Web Reels	`vimeogallery_list`	Dedicated web reels URL + list design/pagination
CMS Page	`vimeogallery_cms`	Shared CMS tab defaults + link to embed profiles
App Reels	`vimeogallery_webview`	App WebView URL + WebView-only Vimeo credentials & design

Legacy URL …/section/vimeogallery_configuration/ redirects to License.

Use scope Default Config unless you configure per website/store intentionally.
On a new server, re-paste the Vimeo access token (encrypted values are not portable between installs).

Note: Values in core_config_data override etc/config.xml. After upgrades, use Use Default on new fields or save again if defaults changed.

Display contexts & config paths

The module resolves settings by display context:

Context	Used for	Typical config groups
`gallery_page`	Web Reels list URL	`vimeogallery/general`, `design`, `loadmore`
`cms_embed`	CMS block with `cms_profile`	Profile JSON + `cms_general`, `cms_design`, `cms_loadmore` defaults
`webview`	App reels WebView	`webview_general`, `webview_design`, `webview_loadmore`

Shared across tabs where noted: Enable Module, Reels URL path (web), license.

1. License

Field	Path	Description
License Key	`vimeogallery/license/license_key`	Required. Validated against Inspeya license API. Green / red icon in admin.

2. Web Reels tab (`vimeogallery_list`)

Web Reels — Module & Vimeo API

Field	Path	Default (config.xml)	Description
Enable Module	`vimeogallery/general/enabled`	No (`0`)	Storefront reels on/off
Reels URL path (web)	`vimeogallery/general/gallery_url_path`	`reels`	Standard web gallery → `/reels`
Video privacy	`vimeogallery/general/video_privacy_scope`	`public_only`	Public only vs all token-visible videos
Vimeo Access Token	`vimeogallery/general/access_token`	—	Encrypted. Required when enabled.
Video Source	`vimeogallery/general/video_source_type`	`account`	`project`, `channel`, or `account`
Vimeo Project / Folder ID	`vimeogallery/general/project_id`	—	When Video Source = Project
Vimeo Channel ID	`vimeogallery/general/channel_id`	—	When Video Source = Channel
Reel video list (cache)	—	—	Count + Refresh video list now

Web Reels — Design, Header & Footer, Pagination: paths under vimeogallery/design/* and vimeogallery/loadmore/* (display mode, colors, limits, batches 8/16/24, max videos, sort from Vimeo date).

Enable App WebView Mode and Reels URL path (app WebView) live on the App Reels tab (vimeogallery/general/webview_enabled, vimeogallery/general/reels_url_path).

3. CMS Page tab (`vimeogallery_cms`)

CMS page embed profiles — link to CMS Page Reel Embeds admin grid
CMS Page — Reels & Vimeo API — vimeogallery/cms_general/* (Vimeo token/source for CMS embeds; video privacy shared for all CMS embeds)
CMS Block Embed — Design / Header & Footer / Pagination — vimeogallery/cms_design/*, vimeogallery/cms_loadmore/*

Per-page overrides: create a profile in CMS Page Reel Embeds (token, source, design fields stored in mhinspeya_vimeo_cms_profile).

4. App Reels tab (`vimeogallery_webview`)

App Reels — WebView — WebView enable, app URL path, vimeogallery/webview_general/* (Vimeo API for app feed)
App WebView — Reels feed & overlay — vimeogallery/webview_design/*, vimeogallery/webview_loadmore/*

Vimeo API endpoints (by Video Source)

Video Source	Vimeo API
Project / Folder	`/me/projects/{id}/videos` (or `/users/{id}/projects/…` when applicable)
Channel	`/channels/{id}/videos`
All account videos	`/me/videos`

After changing Video privacy or source IDs, use Refresh video list now or wait for the ~60s API cache.

Search placeholder on the storefront is fixed/translated (not admin-configurable).

CMS page reel embeds

Admin: Inspeya → Reels → CMS Page Reel Embeds
Create a profile (label, profile key, CMS page reference, store scope, optional Vimeo overrides, design).
On save, the module runs a Vimeo API probe (same idea as system config save).
Copy the generated directive into the CMS page Content (HTML).

Example directive (profile key summer-lookbook):

{{block class="MHinspeya\VimeoGallery\Block\ChannelVideos" name="vimeo.gallery.cms.summer-lookbook" template="MHinspeya_VimeoGallery::videos.phtml" display_context="cms_embed" cms_profile="summer-lookbook"}}

Shared CMS settings (all embeds): display mode, videos per page, max videos, sort order, video privacy — configure on Stores → Configuration → Reels → CMS Page (not duplicated on each profile).

License

Same flow as other Inspeya modules:

Enter the license key and Save Config.
Valid key → success message; merchant can set Enable Module to Yes/No.
Invalid / empty / expired / wrong-domain key → module is force-disabled (enabled = 0).

Default: module is disabled until you enable it (after a valid license is stored).

Vimeo setup (sample)

Choose Video Source in admin, then fill the matching Vimeo ID field.

Option A: Vimeo folder / project

Folder ID from https://vimeo.com/manage/folders/30378241 → 30378241
Token with read access to your videos/projects
Video Source = Project / Folder, Vimeo Project / Folder ID = 30378241

Option B: Vimeo channel

Channel ID (not Showcase), e.g. 1969845
Token with channel read scope
Video Source = Channel, Vimeo Channel ID = 1969845

Option C: All account videos

Token for your account
Video Source = All account videos; leave project/channel empty

Geographic privacy (servers)

If Magento is hosted in another country, allow that region in Vimeo geographic privacy. Otherwise Vimeo may return error 5451 (restricted in your region) even with a valid token.

Open the web gallery

Default (with gallery_url_path = reels):

https://your-store.example/reels

Legacy route /vimeogallery may still exist depending on theme/routes; prefer the configured Reels URL path (web).

Frontend usage

Open the configured web reels URL (default /reels)
Videos load via AJAX (sort + max limit from admin)
Preview images from your domain; click a card to load the Vimeo player (standard mode)
Use search and category pills if enabled
Scroll to load the next batch (8 / 16 / 24 videos)

In-app WebView feed

Requirements:

Enable App WebView Mode = Yes (vimeogallery/general/webview_enabled)

URL (typical defaults)	Purpose
`/reels`	Standard web reels gallery
`/reels=1` (or configured segment)	App WebView feed when WebView mode is enabled

Legacy: /reels?webview=1, /vimeogallery/webview/.

Behavior:

Vertical full-height slides, snap scroll
Tap to play — poster until user starts video
Title/description on slides; viewport handling for mobile WebViews
Scrolling mostly off-screen stops the active player

Frontend routes & AJAX

Type	Path	Description
Page	`/{gallery_url_path}`	Web reels (default `/reels`)
Page	`/{reels_url_path}`	App feed path (default `reels=1`)
Page	`/vimeogallery/webview/`, `?webview=1`	Legacy WebView entry
AJAX GET	`/vimeogallery/ajax/videos`	JSON: videos, filters, design; accepts `display_context`, `cms_profile`

GDPR & privacy (preview images)

Mode	Preview	Player
Standard gallery	`/media/vimeogallery/thumbnails/…`	Vimeo iframe after click
WebView feed	Poster until tap	Vimeo iframe after tap

Preview files are generated from Vimeo API picture URLs ({videoId}_portrait_… / {videoId}_landscape_…).

Technical description only — not legal advice. Align with your privacy policy and DPA.

Caching & LiteMage

Layer	Behavior
Gallery HTML page	Cacheable (LiteMage / FPC friendly)
AJAX `/vimeogallery/ajax/videos`	Short browser cache when warm; no-cache on fresh fetches
Vimeo API list	Magento cache ~60 seconds; keys include source, sort, privacy
Preview images	Under `pub/media/vimeogallery/thumbnails/`; refreshed on admin Refresh
Stale fallback	On API errors / 429, last good cached list may be served

Optional LiteMage exclude: /vimeogallery/ajax/videos

API paging: up to 100 × 5 pages = 500 videos from Vimeo, then Maximum Videos trims for the storefront.

Admin refresh

Refresh video list now (in each Reels config section that shows Reel video list (cache)):

Clears Vimeo list cache for that display context / source
Re-fetches from Vimeo
Re-downloads preview images
Does not flush full Magento FPC globally

Use after Vimeo content changes, privacy/source/sort/display mode changes, or when you need an instant update instead of ~60s TTL.

CLI

# Diagnose Vimeo API using saved config (token, source IDs)
php bin/magento vimeogallery:test-api

---

## Troubleshooting: works locally, fails on server

**Vimeo 5451 — restricted in your region:** Allow the server’s country in Vimeo geographic settings.

| Symptom | What to do |
| ------- | ---------- |
| Token missing / decrypt error | Re-paste **Vimeo Access Token** on that server |
| HTTP 401 / 403 | New token with correct read scopes |
| HTTP 404 | Wrong folder/channel ID or Showcase ID used instead of channel |
| Empty gallery with folder | Confirm folder ID; **Video Source** = Project |
| Private videos missing | Widen **Video privacy**; refresh cache |
| WebView layout issues | Test real device WebView; check `webview_enabled` |
| Blurry thumbnails | Set display mode, then **Refresh video list now** |
| HTTP 429 | Wait and refresh again |
| CMS profile save blocked | Read Vimeo API probe message; fix token/source for that profile |

---

## Exception handling & logging

Failures are handled defensively (no uncaught fatals on normal storefront/admin flows). Search logs for:

```text
MHinspeya_VimeoGallery

in var/log/system.log and var/log/exception.log.

Development & Magento standards

Check	Command / note
Coding standard	`vendor/bin/phpcs --standard=Magento2 app/code/MHinspeya/VimeoGallery`
DI compile	`php bin/magento setup:di:compile` after constructor changes
Patterns	Constructor DI, `declare(strict_types=1)`, ACL on admin actions, encrypted token backend model

The module is intended to pass Magento2 PHPCS with 0 errors and 0 warnings on the paths above.

Translations (i18n)

Locale	File
`en_US`	`i18n/en_US.csv`
`de_DE`	`i18n/de_DE.csv`
`de_AT`	`i18n/de_AT.csv`
`de_CH`	`i18n/de_CH.csv`

Includes Reels admin labels, Vimeo API field labels, CMS embed UI, storefront copy, license messages, API/refresh errors, and User Guide admin chrome (menu, page title, intro notes, config button).

After deploy:

php bin/magento cache:flush

PHP compatibility

Constraint	Value
`composer.json`	`"php": ">=7.2.0"`
Coding style	Magento2 PHPCS

Uninstall

php bin/magento module:disable MHinspeya_VimeoGallery
php bin/magento setup:upgrade
php bin/magento cache:flush

Remove app/code/MHinspeya/VimeoGallery or uninstall the Composer package.

Config under vimeogallery/* and table mhinspeya_vimeo_cms_profile may remain unless you remove them manually. Media under pub/media/vimeogallery/ is not deleted automatically.

Post-install commands

php bin/magento module:enable MHinspeya_VimeoGallery
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush

Support

Package: mhinspeya/mhinspeya-hyva-vimeogallery
Vendor: MHinspeya / Inspeya
Contact: info@mhinspeya.com
License: GPL-3.0

User guide

Bundled with the module (works on any server after install):

Asset	Path
HTML (admin viewer)	`docs/user-guide/USER_GUIDE.html` (English default). Optional locale files: `USER_GUIDE.de_DE.html`, `USER_GUIDE.de.html`, or `de_DE/USER_GUIDE.html` — loaded from the admin user’s locale with English fallback.
Markdown (repo / export)	`docs/user-guide/USER_GUIDE.md`
Screenshots	`docs/user-guide/images/` — reference in `USER_GUIDE.html` as `src="images/your-file.png"` (see `docs/user-guide/images/README.md`)

Admin access:

Stores → Configuration → MHinspeya.de → Reels → License → Open Reels User Guide
User Guide button on the horizontal Reels config tabs (all sections)
Inspeya → Reels → User Guide

Routes: vimeogallery/userguide/index (frame), userguide/content (HTML), userguide/asset (images). Requires ACL Reels Configuration.

mhinspeya / mhinspeya-hyva-vimeogallery

Package info

Security

Statistics