Vidal Slider Block

Native Gutenberg block for creating image sliders in WordPress, with no shortcodes and no heavy third-party plugins.

✨ Features

• 🖼️ Select multiple images directly from the WordPress Media Library
• 🔗 Optional link per slide (relative or absolute), with automatic new-tab opening for external links
• 📐 Content-width layout (boxed) or full-width (full width)
• ▶️ Configurable autoplay (on/off), with automatic pause on slider hover
• ⏱️ Adjustable interval between slides (1 to 10 seconds)
• 🔘 Dot navigation, optional
• ◀️▶️ Navigation arrows (previous/next), optional — inline SVG, with no external library dependency
• 📏 Configurable minimum height, set independently for desktop (default 500px) and mobile (default 250px), in px, vh or em
• 📱 Responsive: on mobile (≤600px), the slider always takes up the full screen (even with boxed layout) and images get a reduced height (250px)
• ⚡ Dynamic block — markup is generated server-side on every page load

✅ Requirements

📦 Installation (regular plugin usage)

Use this path if you just want to use the plugin on a WordPress site, without touching the code.

1. Download an already-packaged version of the plugin (zip) or clone this repository.
2. Upload the vidal-slider-block folder to /wp-content/plugins/ on your site.
3. Activate the plugin under Plugins in the WordPress admin.
4. In the block editor, add the Vidal Slider Block block (category "Widgets").

⚠️ If you cloned the repository directly (instead of downloading an already-packaged zip), the build/ folder doesn't exist yet — the plugin won't work until you generate it. Follow the 🛠️ Development section below.

🛠️ Development

Use this path if you're going to edit the block's code (JS, SCSS, PHP).

1. Put the project in the right place

This plugin needs to run inside a real WordPress installation. Clone (or already have cloned) the repository directly into wp-content/plugins/:

cd /path/to/your/wordpress/wp-content/plugins/
git clone git@github.com:pedrorvidal/vidal-slider-block.git
cd vidal-slider-block

2. Install the dependencies

npm install

3. Compile the assets

npm run start   # development mode, with watch (recompiles on every change)

or, to generate a production build (without watch):

npm run build

Either command generates/updates the build/ folder, which is what vidal-slider-block.php actually registers and loads in WordPress — the plugin reads from build/, never directly from src/.

4. Activate the plugin

With build/ generated, go to Plugins in wp-admin and activate Vidal Slider Block normally. While npm run start is running, any change to src/ recompiles automatically — just reload the page to see the result.

📜 Available scripts

🗂️ Project structure

vidal-slider-block/
├── vidal-slider-block.php     # plugin bootstrap, registers the block from build/
├── src/
│   └── vidal-slider-block/
│       ├── block.json          # name, attributes and asset wiring for the block
│       ├── index.js            # registers the block in the editor
│       ├── edit.js             # block UI in the editor (image selection, settings)
│       ├── slider-images.js    # pure image/link logic (no UI), tested with Jest
│       ├── save.js             # always returns null — the block is dynamic
│       ├── render.php          # front-end markup, generated server-side
│       ├── view.js             # front-end script (autoplay, navigation)
│       ├── style.scss          # styles used in both the editor and the front end
│       ├── editor.scss         # styles used only in the editor
│       └── test/               # Jest tests (e.g. slider-images.js)
├── tests/                      # PHPUnit tests (render.php)
└── build/                      # generated by npm run start/build — do not edit by hand

🧪 Tests

The block has two kinds of automated tests, one for each side of the code: PHPUnit for everything that runs on the server (render.php) and Jest for the editor's pure JavaScript logic (slider-images.js).

JavaScript (Jest)

slider-images.js holds the editor's state logic that doesn't depend on the UI — link validation, merging images while preserving the link when reopening the media selection, invalid-link checking. It was separated out from edit.js specifically so it could be tested without needing to render the whole block (which would require simulating WordPress's media picker).

Runs directly on your host, no need for ddev — it's plain JavaScript:

npm run test:unit

The tests live in src/vidal-slider-block/test/*.js.

PHP (PHPUnit)

Covers the logic in render.php — including security validations, such as always resolving the image URL from the attachment ID (never trusting a URL passed along with the block's attributes).

⚠️ Unlike Jest, the PHP tests only run inside this project's ddev environment, because they depend on a real WordPress installation and a test database. They don't work with your host's PHP/Composer.

1. Install the test dependencies

ddev exec "cd /var/www/html/web/wp-content/plugins/vidal-slider-block && composer install"

2. Create the test database (only the first time per environment)

The tests use a database separate from the site's database (db_test), which is recreated from scratch on every run:

ddev exec "mysql -h db -u root -proot -e \"CREATE DATABASE IF NOT EXISTS db_test; GRANT ALL PRIVILEGES ON db_test.* TO 'db'@'%'; FLUSH PRIVILEGES;\""

3. Run the tests

ddev exec "cd /var/www/html/web/wp-content/plugins/vidal-slider-block && composer test"

Or, if you prefer an interactive session inside the container (avoids repeating cd on every command):

ddev ssh -d /var/www/html/web/wp-content/plugins/vidal-slider-block
composer test

The tests live in tests/*Test.php. Method names are always in English, even though the rest of the project is in pt-BR.

🚀 How to use (wp-admin)

1. In the editor, click Add block and search for "Vidal Slider Block".

2. Click Add images and select (or upload) one or more images in the Media Library.

3. (Optional) For each image, fill in the Link field with a relative (/page) or absolute (https://...) URL — any other format shows an error and blocks the save button until it's fixed. Links to domains other than the site's (including subdomains) automatically open in a new tab.

4. In the sidebar, under Slider Settings, adjust:

   Option	What it does
   🖥️ Full width	Makes the slider take up the entire screen width
   ▶️ Autoplay	Turns automatic slide advancing on/off
   ⏱️ Interval between slides	Sets, in seconds, the time between one transition and the next (with autoplay enabled)
   🔘 Show navigation dots	Turns the dots below the slider on/off
   ◀️▶️ Show navigation arrows	Turns the previous/next arrows over the slider on/off
   📏 Slider Height	Minimum height of the slider on desktop — a number plus a unit (px, vh or em). Default: 500px
   📏 Slider Height (Mobile)	Same as above, but applied only below the 600px breakpoint. Default: 250px

5. To change the images later, use Edit images; to remove a specific image, hover over it and click Remove.

6. Publish or update the page/post to see the slider on the front end.

❓ Frequently asked questions

Does the slider work without JavaScript on the front end? The markup (slides and navigation dots) is always rendered server-side, but the interactive behavior (autoplay, slide switching and clicking the dots) depends on the front-end script (view.js). Without JavaScript, only the first slide is visible.

Can I use videos or other media types? No, for now the block only accepts images.

Do I need to run npm run build every time I update the plugin? Only if you're working from the source code (src/ folder). If you downloaded an already-packaged/zipped version of the plugin, the build/ folder is already provided.

🗺️ Changelog

1.0.0

• 📏 Added configurable slider height, set independently for desktop (default 500px) and mobile (default 250px), each with a unit of px, vh or em.
• 🐛 Autoplay is now disabled when the slider has only one slide, matching the behavior view.js already had — the wrapper's markup no longer claims data-autoplay="true" when there's nothing to advance to.
• 🌍 Full i18n pass: wrapped the one remaining untranslated string (the link field's placeholder), and added load_plugin_textdomain() so PHP-side translations actually load at runtime (this plugin isn't hosted on WordPress.org, so that isn't automatic).
• 🧹 Cleaned up leftover @wordpress/create-block scaffold defaults: real block icon and description in block.json (were still the tool's placeholders), and removed the scaffold's debug border from editor.scss.
• 📄 Added the missing LICENSE file (GPL-2.0-or-later, matching what the plugin header and this README already declared).
• 🇺🇸 Translated this README to English.

0.1.0

• 🎉 Initial version: image selection, layout/autoplay/interval settings and dynamic rendering on the front end.
• ▶️ Implemented the slider's front-end behavior (view.js): slide switching, autoplay with pause on hover and dot navigation.
• 🎨 Added the styles (style.scss) for the track, slides and navigation dots (.vidal-slider__*).
• 🔗 Added an optional link per slide, with validation (relative /something or absolute http(s)://) in the editor and revalidated on the server. The target isn't chosen by the user: it's always derived by comparing the link's domain with the site's — an external link (including subdomains) automatically opens in a new tab, with rel="noopener noreferrer".
• 🔘◀️▶️ Navigation dots are now optional (showDots), and navigation arrows were added (showArrows), also optional — inline SVG with a frosted-glass effect (backdrop-filter + filter: drop-shadow), with no external library dependency.
• 📱 Added a mobile breakpoint (≤600px): image height reduced to 250px, and the boxed layout now behaves like full width (full-screen bleed), since 400px and content width make less sense on a small screen.
• ✅ Added Jest tests (npm run test:unit) for the editor's image/link logic, extracted into slider-images.js specifically so it could be tested without needing to render the whole block.
• 🐛 Fixed the full width layout: the manual breakout (100vw/negative margins) broke in block themes (FSE), which force automatic margins on any child without the core's alignfull class. Now render.php adds alignfull when layout is "full", letting the theme itself resolve the breakout correctly.
• 📏 Added configurable slider height, set independently for desktop (heightDesktop/heightUnitDesktop, default 500px) and mobile (heightMobile/heightUnitMobile, default 250px), each with a unit of px, vh or em. The values are passed to the front end as CSS custom properties (--vidal-slider-height, --vidal-slider-height-mobile) on the block wrapper, consumed by style.scss.

📄 License

GPL-2.0-or-later

Made with 💙 by Pedro Vidal