Swiper Gallery

Overview

A touch-enabled image carousel built on the Swiper block’s foundation: pick images from the media library and the block renders one slide per image, with Method’s arrows and pagination, per-tier sizing, hash navigation, an optional lightbox and media-library captions.

• Block name: method/swiper-gallery
• Title: Swiper Gallery (Method)
• Category: method-component-blocks
• Supports: align (wide, full); html off
• Render type: Dynamic (PHP render_callback: render_method_swiper_gallery_block()), which builds the slides from the attachment ids and hands them to method_swiper_render()
• Inner blocks: No — the images are attributes
• Scripts: editorScript (index.js) and viewScript (frontend.js: the shared Swiper runtime and the lightbox). Swiper itself is enqueued by the theme (handle swiper).
• Shared with: Swiper — the same option attributes, the same inspector panels (MethodSwiperControls) and the same render function (method_swiper_render()).
• Source: lib/blocks/method-swiper-gallery/method-swiper-gallery.php, lib/blocks/method-swiper-gallery/src/edit.js, lib/blocks/method-swiper/method-swiper.php, lib/blocks/components/MethodSwiperControls.js

Usage

Insert a Swiper Gallery and choose images with Select images in the block toolbar (or the placeholder); Edit gallery reopens the picker. Each selected attachment becomes one slide, in the order chosen. The Images panel shows how many images there are, and holds Open images in a lightbox and Show captions; Image sizing sets an aspect ratio for the slides or leaves the images at their natural proportions.

Everything else works as it does on the Swiper block, through the same panels: Effect (fade), Slide sizing (slides per view per tier, or Set slide widths), Space between, and Navigation (arrows with theme icons, pagination inside or outside the track, hash navigation). Two things are the gallery’s own: Mark center slides, which keeps a class on the middle visible slide(s) for a child theme to style, and the Hash identifier that hash navigation derives every slide’s hash from, since image slides have no hash field of their own. The editor preview runs a live Swiper that follows the canvas tier (useCanvasViewport) and shows the captions and center marking the page will have.

The gallery loops — as it always has — but only at a tier where it can: Swiper needs at least one more slide than it shows at once, so a tier whose per-view count equals the image count runs without the loop.

Attributes

responsiveSettings Structure

Per-tier settings live under responsiveSettings.base, mobile, tablet and wide. A tier is only read while its enabled flag is true; base is always on. The keys this block’s CSS map reads:

• aspectUses — "ratio" to force a preset ratio on every slide, empty for the images’ natural proportions (base).
• aspectRatio — the preset, e.g. "-16-9", "-4-3", "-1-1" (base), emitted as aspect-ratio on the image container.

The swiper options are top-level attributes with …Tablet / …Mobile suffixes for their tiers, not part of responsiveSettings.

Control Sets

Data & Dependencies

• Swiper: inc/swiper/swiper-bundle.min.js and .css under the handle swiper, enqueued by method_swiper_gallery_enqueue_assets() on enqueue_block_assets (and by the theme on every page).
• Shared render: method_swiper_render() (lib/blocks/method-swiper/method-swiper.php) builds the shell, arrows, pagination and init script; the gallery passes class => method-swiper-gallery, watch_slides_progress => true (so keyboard focus moving between visible lightbox links does not jump the track), center_class when center marking is on, and per-tier loop flags from method_swiper_gallery_get_loop_tiers().
• Hashes: method_swiper_gallery_get_hash_id() normalises hashId the way the editor does and method_swiper_gallery_get_slide_hash() builds each slide’s data-hash; the shared runtime (lib/blocks/utils/swiperRuntime.js) puts method-hash-active on links whose hash matches a visible slide.
• Lightbox: method_get_lightbox_attributes() per slide, with the lightbox script from lib/blocks/utils/lightbox.js in the view script; the first block on the page installs it, later ones are no-ops.
• Captions: method_swiper_gallery_get_caption_markup() — with the lightbox on the slide item is already a link, so links inside a caption are reduced to their text. The editor fetches the same captions through core-data (up to the REST API’s page cap of 100 attachments).
• Images: wp_get_attachment_image( $id, 'method_hd' ) with the method-fit-img (ratio set) or method-fluid-img (natural) class; in width mode a sizes attribute per tier.
• Styles (assets/scss/global.scss): the wrapper also carries .method-swiper, so the arrow, pagination and width-mode rules apply; .method-swiper-gallery-item is a relative, overflow-hidden block (the link variant inherits color and drops the underline); .method-img-shade has pointer-events: none; the caption sits along the bottom of the image in white 0.875rem text over a dark gradient.
• Responsive CSS: method_get_block_responsive_styles() and method_collect_css() under #method{id} (no hyphen — the id also prefixes the init script’s variable).

Frontend Rendering

<div class="wp-block-method-swiper-gallery method-swiper method-swiper-gallery method-swiper-has-nav" id="method68f1b2c3a4d5e">
  <div class="swiper-outer">
    <div class="swiper-outer-wrap">
      <div class="swiper-outer-wrap-inner">
        <div class="swiper swiper-container">
          <div class="swiper-wrapper">
            <div class="swiper-slide" data-hash="gallery-k3x9pq-slide-1">
              <a class="method-swiper-gallery-item method-lightbox-trigger" href="…/photo-full.jpg" data-method-lightbox="1" data-method-lightbox-src="…" data-method-lightbox-width="2400" data-method-lightbox-height="1600" data-method-lightbox-alt="…" aria-haspopup="dialog">
                <div class="method-fit-img-container method-ratio method-ratio-16-9">
                  <div class="method-img-shade"> </div>
                  <img class="method-fit-img" src="…" srcset="…" alt="…">
                  <div class="method-swiper-gallery-caption">The caption from the media library.</div>
                </div>
              </a>
            </div>
            …
          </div>
          <div class="swiper-pagination"> </div>
        </div>
      </div>
    </div>
    <div class="method-swiper-button-prev">…</div>
    <div class="method-swiper-button-next">…</div>
  </div>
</div>
<script>…new Swiper('#method68f1b2c3a4d5e .swiper-container', { … breakpoints: { 768: { slidesPerView: 2, spaceBetween: 24, loop: true }, 1200: { slidesPerView: 3, spaceBetween: 24, loop: true } }, loop: true, autoHeight: true, watchSlidesProgress: true, … });…</script>

Without the lightbox the slide item is a <div class="method-swiper-gallery-item">; without a ratio the image container is .method-swiper-img-container with a .method-fluid-img; without a caption there is no caption element. A gallery with no renderable images prints nothing. The loop flag appears per breakpoint only when some tier loops.

Generated CSS (per instance): arrows → textColor; .swiper-pagination → linkColor; .method-swiper-gallery-item → bgColor; .method-swiper-gallery-item > .method-fit-img-container → aspect-ratio; .method-img-shade → bgShade.

Filters

No PHP filters of its own. The Swiper configuration is assembled by method_swiper_render(), and the runtime registry is reachable as window.methodSwiperQueue (see the Swiper page). The caption passes through wp_kses() with the standard post allow-list, so the wp_kses_allowed_html filter applies to it.

Changelog