RAN Ecwid Shop Teaser

RAN Ecwid Shop Teaser is a standalone dynamic WordPress product-grid block. Its canonical block name is ran/ecwid-shop-teaser.

Features

• Provides editor previews, caching, and theme-independent baseline styling.
• Reads credentials from the installed Ecwid WordPress plugin by default.
• Safely renders last-good cached or filter-provided cards when Ecwid is unavailable.
• Keeps diagnostic information editor-only.

Requirements

• WordPress 6.5 or newer.
• PHP 8.0 or newer.
• An Ecwid store integration, or filters that provide an Ecwid store ID and API token.

Installation

1. Install the plugin in wp-content/plugins/ran-ecwid-shop-teaser.
2. Activate RAN Ecwid Shop Teaser in WordPress administration.
3. Configure the Ecwid WordPress plugin, or supply credentials through the documented filters.

The committed build/blocks/ directory is required at runtime. Deploy the plugin with those compiled assets; the source blocks/ directory is for development rather than a production fallback.

Usage

Insert Ecwid Shop Teaser from the core Widgets category. Select the desired category and product count in the block inspector. Published visitors receive cards from Ecwid when available, then the last-good cache or valid filter-provided fallback cards.

The editor uses these routes:

• POST /ran-ecwid-shop-teaser/v1/ecwid-shop-teaser/preview
• POST /ran-ecwid-shop-teaser/v1/ecwid-shop-teaser/refresh

External service

The plugin optionally retrieves product data from the Ecwid REST API through the official Ecwid WordPress plugin or credentials supplied by its filters. That request sends the configured store ID, API token, category ID, and product query to Ecwid; it is made server-to-server and does not expose the API token to visitors. Sites using this integration are responsible for reviewing Ecwid's terms of service and privacy policy.

Development

Run commands from this plugin directory:

pnpm install --frozen-lockfile
pnpm start
pnpm build
pnpm format:check
pnpm check
composer check

Source files live in blocks/. Rebuild build/blocks/ after block changes and commit the generated runtime assets with their source.

See QUALITY.md for PHP source coverage, deterministic quality-tool tests and the separate WordPress integration lane.

Agent workflow

See AGENTS.md for the local Dex workflow, WordPress skills, generated-asset rules, quality checks, and release guidance.

Extensibility and compatibility

The plugin registers only ran/ecwid-shop-teaser. Rendered markup uses .ran-ecwid-shop-teaser* and .ran-ecwid-shop-teaser-card* classes, with --ran-ecwid-shop-teaser--* presentation variables.

Available filters include ran_ecwid_shop_teaser_store_id, ran_ecwid_shop_teaser_token, ran_ecwid_shop_teaser_query_args, ran_ecwid_shop_teaser_product_url, ran_ecwid_shop_teaser_product_card, and ran_ecwid_shop_teaser_static_fallback_products. Fallback cards must supply an ID, name, price, image URL and alt text, destination URL, and stock state.

Accessibility and security

Product images require meaningful alternative text, and unavailable products must preserve their visible state. Category IDs are scoped to their resolved Ecwid store. Do not expose Ecwid API tokens in public markup or logs; public fallbacks must not reveal diagnostic details.

Release lifecycle

Quality qualifies ordinary PRs, exact Release Please candidates, and pushes to protected main. It builds the deterministic ZIP and SHA-256 file, keeps the detailed archive manifest in CI evidence, checks generated block assets and POT, runs PHP standards and syntax checks, WordPress 6.5/PHP 8.0 and current WordPress/PHP 8.3 integration, Plugin Check, and installation of the same ZIP in fresh WordPress.

After exact successful main Quality, the shared Profile B workflow runs Release Please, which owns version, changelog, release PR, tag, and draft GitHub Release. Profile B requires successful Quality on the exact release PR head before its protected-main merge. After that merge, the new main Quality produces an exact run/attempt artifact; Profile B verifies its promotion manifest and SHA-256 digests, uploads only the tested ZIP and checksum to the Release Please draft, publishes immutable, and reads back tag target and asset digests. Recovery requires a fresh qualified change and a new version/tag.

The unpublished 1.2.3 proposal was superseded and has no tag or release. WordPress.org publication is a separate optional downstream path and is disabled by the committed deployment contract.

License

RAN Ecwid Shop Teaser is licensed under the GNU General Public License v2.0 or later (GPL-2.0-or-later).

Support and contributing

Report reproducible issues at RocketsAreNostalgic/ran-ecwid-shop-teaser. Include the relevant lint and build output with changes.