Reference Omeka S module

Image Endpoint

URL

GET /og-image/{resource_type}/{resource_id}?site_id={siteId}
Parameter Values
resource_type site, item, item_set, media, page, search, blog_post
resource_id The numeric ID of the resource. For site this is the site ID; for search the module uses the site ID and adds the query as q.
site_id Optional query parameter. Selects the site whose title, tagline, logo and template override are used. Public pages always include it.

The endpoint is public; no login is required. It is registered outside the site namespace, so the same URL serves every site.

Response

Case Response
Image generated or served from cache 200, Content-Type: image/png, Cache-Control: public, max-age=86400, X-OG-Image: OgImages/1.0
Generation disabled, or the resource type is not enabled in settings 200 with a 1x1 transparent PNG and the same headers
The resource does not exist (its title resolves to empty) 404 with an empty body
GD is not available 200 with a 1x1 transparent PNG

The X-OG-Image header is a quick way to confirm that a response came from this module rather than a proxy or a theme.

Meta tags injected into pages

On a covered public page the module adds these tags through the headMeta() view helper:

<meta property="og:image" content="https://example.org/og-image/item/42?site_id=1">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:type" content="image/png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:image" content="https://example.org/og-image/item/42?site_id=1">
<meta property="og:title" content="Item title">
<meta property="og:description" content="Item description">

og:title and og:description are omitted when the value is empty. The width and height tags always report 1200 x 630 even when a template uses a different canvas size.

The image URL is absolute (force_canonical), built from the request's scheme and host.

Theme integration

  • Your theme's layout must print $this->headMeta() in <head>. The default theme does. Without it no tags appear.
  • Tags are set with setProperty / setName, which replace any existing headMeta entry with the same property or name. A theme or module that sets og:image earlier in the render is overridden; one that sets it later wins.
  • Tags are only injected when the request is a site request, the module is enabled, and the resource type is enabled in settings.
  • The listener keys on the controller and action: item, media and page show actions, the item browse action when it lists one item set (the item-set-id route parameter of /s/{site}/item-set/{id}), every action of the site index controller, the cross-site search controller, and the Blog module's post show action.

Cache keys

Generated files are stored as {cache_dir}/{resource_type}/{resource_id}.png, or {resource_id}_s{siteId}.png when site_id is present. Non-alphanumeric characters in the ID are stripped from the file name. See Cache Management.

Admin AJAX endpoints

Used by the template editor and the site settings section. The editor's two require the same role as template management; for other roles they answer 403 with { "error": "..." }.

Method and path Purpose
GET /admin/og-images/preview-vars?resource_type=item&resource_id=42[&site_id=1] Returns { "ok": true, "vars": { ... } } with the resolved variables for the live preview.
GET /admin/og-images/random-resource?resource_type=item Returns { "ok": true, "id": "17" } for a random resource of that type (not supported for search).
POST /admin/og-images/site-settings Saves per-site overrides; fields site_id, template_{type} (empty for the default) and the og_site_settings_csrf token printed in the site's section. Returns { "ok": true } when called with X-Requested-With: XMLHttpRequest; a missing or wrong token, or a user who may not edit that site (only its owner, Admins in its User permissions and Site and Global Administrators may), answers 403 and a template of another resource type 400, with { "error": "..." }, and nothing is saved.
GET /admin/og-images/flush-cache[?type=item] Flushes all cached images, or one type. Returns JSON when called with X-Requested-With: XMLHttpRequest.
Log in for Support