.. include:: /Includes.rst.txt .. _usage-viewhelper: ================== Fluid ViewHelper ================== Declare the ViewHelper namespace once per template and call :html:``. .. code-block:: html :caption: Fluid template {# Simplest case: one ratio, renders an with the full ladder #} {# By file UID or path #} {# Art direction: per-breakpoint ratios render a with one each. Keys are breakpoint aliases (xs, lg, …) or px min-widths (0, 992, …); each becomes a (min-width:Npx) , and the min-0/xs entry becomes the fallback. #} {# Full-bleed hero: a fixed CSS height instead of a ratio. Width climbs the ladder, the height stays pinned (the rendered image only gets wider/flatter from tablet to 4K, never taller). #} {# Mix ratio and fixed-height tiers per breakpoint: a portrait-ish ratio on small screens, a pinned height on large ones. #} {# LCP / above-the-fold image #} .. _usage-arguments: Arguments ========= .. list-table:: :header-rows: 1 :widths: 20 20 15 45 * - Argument - Type - Default - Description * - ``image`` - ``File`` / ``FileReference`` - – - FAL object. Use this **or** ``src``. * - ``src`` - string - ``''`` - File **UID** or path (e.g. :file:`fileadmin/img/x.jpg`). * - ``treatIdAsReference`` - bool - ``false`` - Treat ``src`` as a ``sys_file_reference`` UID. * - ``aspectRatio`` - string | map - – - ``"W:H"``, a fixed CSS height ``"600px"`` (full-bleed hero: width climbs the ladder, height pinned), a ``{breakpoint: "W:H"|"Npx"}`` map, or the raw :ref:`aspect_ratio JSON `. Omitted: the crop variant (for a reference) or original image ratio. A malformed tier value raises an error; ``auto`` / empty skips the tier. * - ``cropVariant`` - string - ``default`` - FAL crop variant to use. * - ``alt`` - string - ``''`` - Alternative text. * - ``title`` - string - – - ``title`` attribute on the :html:``. * - ``class`` - string - – - CSS class on the :html:``. * - ``priority`` - bool - ``false`` - Mark as the LCP image (see :ref:`usage-priority`). :html:`width` and :html:`height` are always emitted from the largest rung, so there is zero layout shift. .. _usage-fixed-height: Fixed-height tiers ================== A tier value of ``"600px"`` (or ``"600"``) pins the **height** instead of deriving it from a ratio. Width still climbs the ladder, so a full-bleed hero keeps a constant CSS height across viewports while the served crop only gets wider and flatter, but never needlessly taller, from tablet to 4K. The ``px`` value is a **CSS** height. To stay sharp on high-DPR screens the tier is emitted as several ````\ s gated by ``min-resolution``: 1× serves the given height, 2× serves twice it, 3× three times up to :confval:`fixedHeightDprCap ` (default 3). A low-DPR screen matches no ``min-resolution`` source and gets the cheap 1× height; a retina screen matches a gated source and stays crisp. Height is chosen by the device pixel ratio, width by the layout. So the served pixels match the need with no waste. Heights are never scaled beyond the source image's own height. Pair a fixed-height image with CSS such as ``width:100%; height:600px; object-fit:cover``; any surplus served height is re-cropped by ``object-fit``. .. _usage-priority: Priority / LCP images ===================== Set :html:`priority="1"` on the above-the-fold (LCP) image. Imaginator then: * drops :html:`loading="lazy"` and adds :html:`fetchpriority="high"` on the :html:``; * renders an explicit :html:`sizes="100vw"` instead of :html:`sizes="auto"`; * adds a :html:`` to the :html:``, so the request is discoverable in the initial document. This satisfies Lighthouse's *LCP request is discoverable*, *not lazily loaded* and *fetchpriority should be applied* audits. .. important:: Use :html:`priority="1"` on the single most important above-the-fold image.