WordPress Documentation

Getting started

Filmstrip Photo & Video Slider turns photos and videos into a draggable filmstrip. Each frame represents a category. Clicking a frame can open its media, visit a link, or simply center the frame.

The plugin has three menu pages under FWD Filmstrip Photo & Video Slider: Presets Manager, Galleries Manager, and Support. Use the preset manager for appearance and behavior, and the gallery manager for your content.

A preset and a gallery are separate. You can show the same content with different presets, or reuse one preset across several galleries.

Install and update

The plugin requires WordPress 6.5 or newer and PHP 8.0 or newer. Visitors need a browser with WebGL support. WooCommerce is optional and is only needed for product gallery integration.

1. Open Plugins > Add New Plugin > Upload Plugin.
2. Select filmstrip-photo-and-video-slider.zip, click Install Now, then activate the plugin.
3. Open FWD Filmstrip Photo & Video Slider in the WordPress sidebar.

If your download is a complete marketplace package, extract it first and upload the installable plugin ZIP inside it.

Updating an existing installation

Back up your site and database first. Upload the new plugin ZIP through the same installer and use WordPress's replacement option. Clear your page cache and any asset or CDN cache after the update. You do not need to delete the plugin to replace its files.

The current development build resets presets and galleries when upgrading stored data older than schema 4. Do not rely on automatic import from the older plugin. Test that upgrade on a backup or staging site first. Current saved galleries use schema 5.

Create your first gallery

1. Open Galleries Manager and click Add New Gallery. Enter a unique gallery name, for example My Filmstrip.
2. Click Edit Categories on its card, then Add New Category.
3. Enter a category name and choose Open category. Confirm with OK.
4. Click Edit Items on the category card, then Add New Item.
5. Enter an item name, use Choose media to select a file, and wait for its width and height to be detected. For video, also use Choose poster.
6. Add optional captions, confirm the item, and repeat for your other media.
7. Click Update Gallery to save the content to WordPress.
8. Choose Preset 1 in the shortcode below and place it in a Shortcode block on a page.

[filmstrip_slider preset_name="Preset 1" gallery_name="My Filmstrip"]

Use the exact saved preset and gallery names in the shortcode. Publish or preview the page to see the filmstrip.

Manage galleries

The gallery grid lists your saved galleries. Add New Gallery creates a new container. The pencil edits its name and optional gallery image. Edit Categories opens its categories, and the delete icon removes the gallery after confirmation.

The optional gallery image is the manager card's artwork. It does not set a filmstrip frame's cover. Each category gets its cover from its own first item.

Drag cards to reorder them. Use Back To Galleries or the breadcrumb to return. Navigation and edit dialogs start at the top of the page. Deleting gallery content does not delete the original files from the Media Library.

Categories and click actions

Each category becomes one frame in the filmstrip. Click Add New Category to create one, the pencil to change its settings, or Edit Items to manage its media. Drag category cards to change the frame order.

Category name and film title is printed on the film frame and shown in category navigation. Use a unique name within the gallery. Film code is optional short text printed on the frame, such as a year or collection code.

The click action belongs to the category, not to an individual photo or video. Category navigation includes categories that open their own items. Link-only and no-action frames are not destinations in that navigation.

The first item is the category's cover. To change the cover, open Edit Items and drag another item into first position. An empty category can be saved while you work, but it does not appear on the public filmstrip until it contains media.

Add photos and videos

Open a category's Edit Items view. Click Add New Item, or use the pencil on an existing item to edit it. Drag media cards to set their order. The Cover badge marks the first item.

Landscape, portrait, square, and wide images can be mixed in the same category. Use browser-compatible image files such as JPEG, PNG, or WebP. Transparent PNG images are supported. The available upload types also depend on your WordPress installation.

Leave both caption fields empty for media without text. Caption fonts, colors, padding, spacing and smaller-screen sizes are controlled by the preset's Category settings.

Video playback

Select your own browser-compatible video, such as an MP4 or WebM, and choose a matching poster. Videos can be category covers or items inside a category. Place a video first in the item list to make it the cover.

Visible videos autoplay muted and loop without controls. The poster remains visible until a decoded video frame is ready, or when playback cannot start. Hidden videos pause. Category arrow previews can play the destination cover video, while the category dropdown uses still thumbnails.

The plugin plays the supplied file at its full duration. It does not transcode, trim, or convert uploads into adaptive streams. File size, bitrate, device decoding support and your hosting speed affect loading. Use a resolution appropriate to the displayed size and avoid putting many large videos on screen together.

The initial loading sequence uses cover photos and video posters. Category media start loading as the category opens and populate their meshes as they become available.

Presets Manager

A new installation includes Preset 1 through Preset 9. All nine start with the same settings and can be edited independently.

1. Choose a preset from Select your preset.
2. Use the General, Filmstrip, Category, Category selector, Post-processing, and WooCommerce tabs to change its settings.
3. Click Update Preset and wait for the saved confirmation.

Duplicate Preset creates a variation with a unique name. Reset Preset restores the selected preset's editor values to the defaults. Save to apply the reset. If you rename a preset, update shortcodes that use its old name.

On/off settings use checkboxes. All duration and delay fields use seconds, so 0.65 means 650 milliseconds. Validation shows a tooltip next to a field that needs attention.

Layout and category navigation

Display type controls sizing. responsive calculates the gallery height from Max height, Auto scale, and Auto scale start width, with a minimum height of 450px. afterparent follows its host container. The shortcode host starts at the preset's Max height.

Frame width and Frame height set the film frame ratio. Film strip gap adds space between film frames in scene units. Category image gap sets space between opened category media in CSS pixels and reduces on smaller screens.

Mouse wheel behavior is separate for the filmstrip, opened category slider, and category dropdown. Dragging remains available when a mouse wheel option is off.

In Category selector, enable Show cateogry navigation arrows for previous/next category controls, Show cateogry navigation select for the dropdown, or enable both. Turn both off to hide category navigation. These field labels retain the spelling used in the current editor.

Category navigation wraps through available categories. With two categories, both arrows point to the other category. The arrow preview shows its destination's media and title. Image navigation inside an opened category is separate from category navigation.

Infinite allows wrapping when there is enough media to fill the visible area. Short filmstrips and categories can use finite scrolling to avoid empty space or visible repetition.

Deep linking

Enable Deep linking in the preset's General tab and save the preset used by your shortcode. It is off by default. Enable it on only one gallery per page.

https://example.com/gallery/#category=Salt_Sea&item=An_Open_Blue

The category route comes from its name. Item routes use the item's Deep link ID, then its caption title, then an item-number fallback. Spaces and most punctuation become underscores. Duplicate keys receive a suffix such as ~2.

Open the category, move to the desired item, let the movement settle, and copy the browser URL. A shared URL opens that category and item after loading. Browser Back and Forward are supported. Closing the category removes the gallery route.

Use stable, unique deep link IDs when item captions may change. Renaming a category changes its generated route. An unknown category is ignored. A missing or unknown item opens the first item of a known category.

Place a gallery on a page

In the WordPress block editor, add a Shortcode block and paste:

[filmstrip_slider preset_name="Preset 1" gallery_name="My Filmstrip"]

Replace both values with the exact saved names. For a page builder, use its shortcode widget or shortcode element. Do not use a code-display block, which prints the shortcode instead of rendering it.

The Filmstrip Photo & Video Slider metabox on post and page editing screens generates the shortcode. Choose a preset and a gallery, then copy the generated text into your content. On WooCommerce products, the metabox saves the gallery assignment directly. See WooCommerce integration.

You can place multiple shortcodes on a page. Each gets its own host and API instance. Keep Deep linking enabled for at most one of them.

For a PHP template, render the shortcode with WordPress:

echo do_shortcode('[filmstrip_slider preset_name="Preset 1" gallery_name="My Filmstrip"]')

The older [fwdfs] alias is registered only if another plugin has not already claimed it. Use [filmstrip_slider] in new content.

WooCommerce integration

Use Filmstrip Photo & Video Slider in place of the product image gallery on classic WooCommerce product pages and in WooCommerce Product Gallery blocks. The integration was checked with WooCommerce 11.0.0. WooCommerce is optional for galleries on ordinary pages and posts.

Set up a product gallery

1. Open Galleries Manager, create your categories, add their photos or videos, and click Update Gallery.
2. Open Presets Manager and select the preset that this product will use.
3. Open the WooCommerce tab, choose Filmstrip Position, then click Update Preset.
4. Edit your WooCommerce product and find the Filmstrip Photo & Video Slider metabox in the editor sidebar.
5. Turn on Enable Filmstrip, choose the Preset and Gallery, then click the product editor's Update or Publish button.
6. View the product page. Its image area now uses the assigned gallery and the position saved in your preset.

No shortcode is needed in the product description. The assignment belongs to this product. Turn Enable Filmstrip off and update the product to restore the normal product images. Products with no assignment keep their usual images.

The dropdowns list saved presets and galleries. Create your gallery in Galleries Manager first. If you rename or delete a selected preset or gallery, select an available entry again and update the product. Missing selections and galleries without media leave the normal product images in place.

Choose the filmstrip position

Position is saved per preset. Products using the same preset share its position and appearance. Use separate presets when different products need different layouts. Existing presets use Replace Product Image until you change it.

Use the preset's General tab to adjust the slider height and responsive behavior. The WooCommerce tab changes placement only. Photos, videos, captions and category actions are still managed in Galleries Manager.

Single Product blocks on pages

Add a WooCommerce Single Product block and choose the product. Keep its Product Gallery or Product Image Gallery block inside the layout. The filmstrip reads the assignment from that product, not from the page containing the block. Open the chosen product in Products, enable its filmstrip, choose the preset and gallery, and update it.

On the public page, the filmstrip replaces the gallery block. The editor keeps WooCommerce's native preview. Replace Product Image stays inside the image column. Replace Product Image Full Width stacks the nearest enclosing Columns block so the filmstrip and product details each use the available width. Columns elsewhere on the page are unchanged.

A separate filmstrip shortcode on the page remains a separate slider. Remove it if you only want the gallery inside the product block.

Product templates and variations

Automatic replacement supports classic WooCommerce image hooks and the Product Gallery and Product Image Gallery blocks. This includes Single Product blocks embedded on ordinary pages and product templates using those gallery blocks. For a custom builder that uses neither, place a shortcode at the desired location and manage its surrounding layout in the builder. The position setting does not rearrange a manually placed shortcode.

The gallery displays the categories and media you assigned to it. Choosing a product variation does not automatically replace its images. Normal WooCommerce price, variation and add-to-cart controls remain part of the product details.

Existing shortcode products

Products configured with a shortcode in their full description continue to work until an assignment is saved. The metabox reads that existing selection for you. Save it with the product, then remove the old shortcode from the description. The saved metabox assignment takes priority, including when Enable Filmstrip is off.

If the usual product images still appear

Check that Enable Filmstrip is on in the product metabox, that a preset and gallery are selected, and that the gallery contains media. Update the product to save its assignment. Confirm that you saved the preset and that your product template uses the classic image hooks or a supported WooCommerce gallery block. If you use page caching, clear it after changing the preset.

Settings reference

Find a field by its editor label or setting key. Defaults below are the plugin defaults, not the values currently saved in your site.

{
  "heading": "Categories",
  "counter": "{current} / {total}",
  "navigation": "Category navigation",
  "previous": "Previous category: {title}",
  "next": "Next category: {title}",
  "previewPrevious": "Previous category",
  "previewNext": "Next category"
}

{
  "heading": "COLLECTIONS",
  "mediaCountOne": "{count} item",
  "mediaCountMany": "{count} items",
  "photoCountOne": "{count} photo",
  "photoCountMany": "{count} photos",
  "current": "Currently viewing",
  "open": "Open collection",
  "details": "{photos} · {status}",
  "counter": "{current} / {total}",
  "dialog": "Choose a collection",
  "close": "Close collection picker",
  "scroll": "Scroll collections",
  "option": "{title}, {photos}",
  "chooseCategory": "{title}: choose collection",
  "openCategory": "Open {title}",
  "returnToCategory": "Return to {title}"
}

JavaScript API

For custom integration, each shortcode host exposes its gallery instance through host.filmstrip. You can also use FWDFPAVS.get(hostId). The first host on a page is usually fwdfpavs-gallery-0. Inspect the rendered shortcode host when more than one gallery is present.

This example handles both an existing instance and one that is created later. Add it through your theme or a custom script. The WordPress wrapper emits filmstrip:created on the host and bubbles it to the document.

(() => {
    const hostId = 'fwdfpavs-gallery-0'
    const connected = new WeakSet()

    function connect(gallery) {
        if (connected.has(gallery)) return
        connected.add(gallery)

        gallery.on('categoryOpened', event => {
            console.log('Opened category', event.category)
        })

        if (gallery.isReady) console.log(gallery.getState())
        else gallery.once('ready', () => console.log(gallery.getState()))
    }

    document.addEventListener('filmstrip:created', event => {
        if (event.detail.host.id === hostId) connect(event.detail.gallery)
    })

    const gallery = window.FWDFPAVS?.get(hostId)
    if (gallery) connect(gallery)
})()

Wait for ready before the first navigation call. Methods that request navigation can return false when the target is unavailable or the current transition cannot accept the request.

The wrapper destroys instances when their shortcode hosts are removed from the DOM. FWDFPAVS.refresh() checks for inserted hosts when the runtime is already loaded. It does not fetch the runtime for a page that never loaded a gallery.

See the complete method reference and state reference for arguments, return values, and transition behavior.

Events

Use gallery.on(eventName, callback) to listen to runtime events. Each runtime event includes its type and gallery target. Register listeners before the action you want to observe.

Category switching can overlap outgoing and incoming events. Check the event's category and reason rather than assuming every event refers to the newly selected category. The complete event reference includes video, picker, interaction and playback events with their payload fields.

The WordPress wrapper also emits the DOM events filmstrip:created and filmstrip:error. The latter reports initialization failures through event.detail.error.

Troubleshooting

The shortcode shows no gallery

Check that the plugin is active, the preset and gallery names match exactly, and the gallery has a category with at least one saved item. Use a Shortcode block, then preview the published page.

Changes do not appear

Confirm with Update Gallery, Update Galleries, or Update Preset. Check that the shortcode uses the preset you edited. Clear page, optimization and CDN caches. Avoid loading an older copy of the standalone slider alongside the plugin.

A video stays on its poster

Check that the video URL loads, the format and codec are supported by the browser, and the file has a valid poster. Browser autoplay or power-saving restrictions can prevent playback. Test with a known working MP4. Media on another domain must permit cross-origin requests.

Dimensions are empty or invalid

Select the file again with Choose media and wait for detection. The file must be reachable so the browser can read its metadata when attachment dimensions are missing.

Deep links do not open the expected item

Enable Deep linking on the preset actually used by the shortcode. Use unique item IDs and test the URL copied after navigation settles. Only one gallery on a page should own deep linking.

The gallery is slow

Reduce oversized media and video bitrates. Try disabling optional post-processing effects and avoid many simultaneous visible video galleries. Check the browser console and network requests for failed or repeatedly downloaded files.

The product gallery does not change

Enable Filmstrip in the product metabox, select a saved preset and gallery containing media, and update the product. For a Single Product block, configure the product selected in the block. Custom templates need a supported WooCommerce gallery block, classic image hooks, or a manually placed shortcode.

Data and uninstall

Presets and galleries are stored in the WordPress option fwdfpavs_data. Deactivating the plugin keeps the data.

Deleting the plugin also keeps its saved galleries and presets. There is no uninstall cleanup routine or data-deletion option. Uploaded Media Library files are retained.

Keep a database backup before upgrades or uninstalling. See Install and update for the current older-schema reset behavior.

Source files

The plugin includes readable PHP, admin JavaScript and styles, plus the unbundled slider source in source. Runtime changes can be rebuilt with Node.js 22.12 or newer:

cd source
npm ci
npm run build

The build refreshes js/FWDFPAVS.js in the plugin. The Three.js Draco decoder is embedded in the runtime. Third-party licenses are included in the licenses folder.

Plugin runtime assets and Roboto fonts are local. The plugin does not add analytics or telemetry. Media files are fetched by visitors' browsers from their configured URLs.

Support

Open FWD Filmstrip Photo & Video Slider > Support in WordPress, or contact us directly:

• tibi_diablo@yahoo.com
• tibi@fwdapps.net
• Contact form

Include the page URL, plugin version, browser, and a short description of the steps that reproduce the issue. A screenshot and any browser console error help us identify the problem.