WordPressに再利用可能なGIFウィジェットを実装する｜ショートコード・ランダム切り替え・表示制御の設計記録

Building a Reusable GIF Widget in WordPress: Shortcodes and Fixing Theme CSS Conflicts

This article was structured and written with the help of several AI tools, each used for different parts of the work (prototype: Gemini; shared component: ChatGPT; root-cause investigation and cross-page display fix: Claude), based on the actual development work carried out for FUKABORI COLORS.

I added a small GIF window to the FUKABORI COLORS homepage as an entry point to the Dancing GIF Hall. It sits above the interactive door, rotates through animated GIFs at regular intervals, and links to the GIF gallery when clicked.

This article records the design and two problems I ran into along the way: PHP written in page content that never ran, and a layout that broke on pages other than the homepage.

1. Goals and Requirements

The goal was to make the entrance to the GIF gallery more noticeable while reusing animated content already published on the site. The requirements were:

• Use published GIF content registered in WordPress
• Rotate images at roughly ten-second intervals, avoiding consecutive repeats where possible
• Make the whole widget a link to the gallery page
• Adjust the size on smaller screens
• Make it reusable on other pages with a short snippet, not a homepage-only effect
• Reduce unnecessary work when the widget is off-screen or its tab is hidden
• Provide a fallback when an image cannot be loaded

2. The First Pitfall: PHP in Page Content Does Not Run

The first prototype was built with Gemini. It put the PHP that fetches the GIF list directly inside a script pasted into the homepage content. That code did not assume it would be pasted into WordPress page content, where PHP is not executed, so it collided with how WordPress works. This kind of mismatch can happen with any tool when the conditions of the destination are not communicated.

As a result, the window frame appeared but its content stayed black. In the browser's developer tools, the image element's src was still the initial placeholder.

The browser console also reported:

Uncaught SyntaxError: Unexpected token '<'

The cause was that WordPress does not execute <?php ... ?> written in page content. The raw PHP reached the browser, and the JavaScript parser stopped at the <. PHP only runs in WordPress-side code such as theme files and plugins.

I moved the logic into a WordPress-side file and switched to calling it from content through a shortcode.

3. Structure and the Shortcode

The widget splits its responsibilities across PHP, CSS, and JavaScript.

• PHP: retrieves the GIF data, generates the markup, and loads the CSS and JavaScript. Each instance gets a unique ID, so several widgets can coexist on one page.
• CSS: window size, aspect ratio, border, image presentation, and narrow-screen widths.
• JavaScript: image rotation, error handling, and viewport and tab visibility checks.

Design changes mostly touch CSS, behavior changes JavaScript, and data changes PHP.

The component is called with a WordPress shortcode, so a page only needs this one line:

[gif-window]

Because HTML and JavaScript are not duplicated across pages, a change in the shared files applies everywhere, and adding the widget to another page is trivial. CSS and JavaScript live in external files rather than as a long script embedded in page content.

The shortcode has to be placed where WordPress processes shortcodes; in some blocks, such as Custom HTML, it may appear as literal text. Conversely, to display the shortcode as text in an article like this one, the square brackets must be written as HTML entities ([ and ]), or WordPress will execute it and render the widget instead.

4. Retrieving GIF Data from WordPress

GIFs are managed as a custom post type in WordPress. The widget fetches only published posts, in the order set in the admin screen, and collects the image URL associated with each one.

This lets GIFs be added and organized from the admin screen without hard-coding URLs. The URLs are encoded as JSON, stored in an HTML attribute, and read by JavaScript, with output escaped for its context.

A published post can still point to a deleted or unavailable file, so the code does not assume every image will load; the error handling in section 7 covers that case.

5. Random Rotation and Repeat Avoidance

Every ten seconds or so, the widget picks the next image at random. Since pure randomness can show the same image twice in a row, it remembers the last image and excludes it from the next pick.

This only helps when several images are available; with a single image there is nothing else to choose. Images that failed to load are also excluded, so the widget does not keep retrying an unavailable file.

6. Controlling Updates Based on Visibility

A timer-driven widget keeps running even when nobody is looking at it. The widget rotates images only when both conditions below are met:

• It is in the viewport: the Intersection Observer API reports when the widget enters or leaves the visible area, instead of recalculating its position on every scroll event. The timer stops while it is off-screen and resumes when it returns.
• The tab is visible: the Page Visibility API pauses rotation while the user is on another tab.

These measures reduce unnecessary timer activity. How much CPU or battery they save depends on the device and browser, and I have not measured it.

7. Image Errors and Fallback Display

Network problems or missing files can leave the window empty. When an image fails to load, the widget shows a fallback (a Dancing GIF Hall thumbnail) and excludes the failed image from future picks. The window area and the link to the gallery are preserved.

If the fallback image itself is unavailable, this does not help, so its URL should be checked during maintenance too.

8. Corner Misalignment on Other Pages

Symptom

The homepage rendered correctly, but when the shortcode was placed on other pages, the corners of the GIF no longer matched the corners of the window. The image did not fill the window and sat small, centered, and pushed toward the bottom.

First attempt and the handover

My first attempt was changing the image's object-fit from contain to cover, which made no visible difference. At this point ChatGPT's free usage limit was reached, so I handed the remaining investigation and fixes to Claude, which revised the CSS and PHP files.

Likely cause

Because the homepage was fine and only post pages broke, the likeliest explanation was that the theme's CSS for post content was interfering with the image's width, height, or max-width. Generic styles for images in content can apply to posts but not to the homepage. I did not identify the exact rule responsible; instead I chose to harden the widget so that it depends less on the theme.

There were two likely reasons the cover change had no effect:

• The original CSS had low specificity and no !important, so theme rules won.
• The stylesheet URL used a fixed version number, so browsers and caches kept serving the old CSS after the file changed.

The fix

The fix touched the CSS and PHP files; the JavaScript was unchanged.

• Pin the image to the inside of the window with position: absolute, so theme rules like height: auto matter less.
• Scope selectors under .fukabori-gif-window-wrap to raise specificity, and add !important.
• Cancel properties that themes commonly set on images: max-width, margins, borders, radius, shadows, transform, and float.
• Generate the CSS and JavaScript version numbers from each file's modification time.

The key CSS, excerpted and simplified:

.fukabori-gif-window-wrap .fukabori-gif-window {
    position: relative !important;
    aspect-ratio: 16 / 9 !important;
    overflow: hidden !important;
}

.fukabori-gif-window-wrap .fukabori-gif-window .fukabori-gif-window__image {
    position: absolute !important;
    top: 0 !important; left: 0 !important;
    right: 0 !important; bottom: 0 !important;
    width: 100% !important;
    height: 100% !important;
    max-width: none !important;
    margin: 0 !important;
    transform: none !important;
    object-fit: cover !important;
}

On the PHP side, the fixed '1.0.0' was replaced with the value of filemtime():

$css_ver = file_exists($asset_path . 'gif-window.css')
    ? filemtime($asset_path . 'gif-window.css') : '1.0.1';

wp_enqueue_style('fukabori-gif-window', $asset_url . 'gif-window.css', array(), $css_ver);

Now the URL changes whenever the CSS file changes, so stale copies are less likely to linger. I also fixed a doubled slash in the asset URL.

Remaining caveats

object-fit: cover fills the window but crops the top and bottom, or the sides, of any GIF that is not 16:9. Switching to contain shows the whole image at the cost of visible window background; either way, the window's corners match its frame.

Heavy use of !important is a strong way to resist theme CSS, but it makes later overrides harder. Limiting it to this widget's own class names is a deliberate trade-off.

9. Responsive Design and Performance

Media queries reduce the window width on narrow screens, and a fixed aspect ratio keeps its shape stable.

Performance depends on more than file size: loading timing, animation decoding, and JavaScript frequency all matter. I therefore:

• avoid unnecessarily large images,
• pause rotation off-screen and in hidden tabs, and
• manage CSS and JavaScript as shared files.

The image uses lazy-loading and async-decoding attributes, but they do not always help. In the initial viewport, lazy loading can delay the first paint, and animated GIFs can cost more to decode and render than static images. Decisions should be based on the actual placement and measurements.

10. Maintainability and Security

The basic principles are:

• Escape values according to their HTML output context
• Pass data to JavaScript as JSON
• Limit the source to published posts
• Avoid duplicating logic across pages

These are basic safeguards, not a guarantee of site-wide security; WordPress core, the theme, and plugins still need ongoing updates and validation. This record also leaves out server-internal and administrative details.

11. Testing and Further Validation

Beyond the homepage, I confirmed that the window and image corners now match on a post page. Next I plan to check:

• Whether the layout holds with other themes and other page types (pages, posts, archives)
• That GIFs rotate every ten seconds with fewer consecutive repeats
• Mobile layout and fallback behavior on load failure
• That rotation actually stops off-screen and in hidden tabs

Performance will be measured with tools such as PageSpeed Insights, under comparable conditions before and after. The measures described here are design intentions, not measured speed improvements.

Conclusion

I built a reusable WordPress widget that pulls registered GIFs and can be inserted with a shortcode. Along the way, I resolved PHP that never ran in page content by moving the logic to the WordPress side, and fixed a layout that broke on other pages by pinning the display with CSS.

Handing the work from one AI tool to another after a usage limit was not a problem: sharing the code and the error details was enough to continue. FUKABORI COLORS will keep growing through small, practical features that make the site a place to explore.