=== Sidocode Selling Points & Payment Icons ===
Contributors: sidocode, kusimo
Tags: woocommerce, selling points, trust badges, payment icons, product benefits
Requires at least: 6.0
Tested up to: 7.0
Requires PHP: 7.4
WC requires at least: 5.0
WC tested up to: 10.5
Stable tag: 1.0.0
License: GPL-2.0+
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Add selling-point benefit icons and a payment icons bar to WooCommerce products. Five layouts, per-product overrides, and conditional asset loading.

== Description ==

**Sidocode Selling Points & Payment Icons for WooCommerce** lets you add a benefit bar to your product and category pages — showing icons with titles and descriptions to highlight key selling points like free shipping, secure payment, easy returns, and more.

=== Key Features ===

**Five Display Layouts**

* **Icon List** — A clean horizontal or wrapping list of benefit items, each with an icon, title, and description.
* **Carousel** — A smooth sliding carousel with optional navigation arrows, dot indicators, and configurable auto-play interval.
* **Flash Rotate** — Items animate in one at a time, rotating at a configurable interval — ideal for compact bars.
* **Grid** — A responsive grid of benefit items, great for showcasing multiple features at a glance.
* **Inline Compact** — A tightly spaced single-line bar with separator dividers, perfect for narrow spaces.

**Flexible Display Positions (Product Pages)**

Choose where the benefit bar appears on single product pages:

* Before Add to Cart Form
* After Add to Cart Form
* After Add to Cart Button
* After Product Price
* Before Single Product
* Shortcode Only — use `[ssppi_benefits]` for full manual control

**Mobile Layout Override**

Set a different layout for screens 768 px wide and below — for example, use Icon List on desktop but switch to Carousel on mobile.

**Per-Product Overrides**

Each product has a dedicated **Benefits** tab inside the WooCommerce Product Data metabox. Check the override checkbox to replace the global benefit items with a custom set for that product only.

**Per-Category Overrides**

Each WooCommerce product category (Products → Categories) has a Product Benefits section. Check the override checkbox to define custom benefit items for that category. Products in that category will display the category's items when no product-level override is set.

**Benefit Bar on Category Archive Pages**

Optionally display the benefit bar on WooCommerce category/shop archive pages. Configure:

* **Enable/Disable** independently from product page display
* **Position** — After Category Description/Title, or Before the Product Grid
* **Category Desktop Layout** — Override the global desktop layout for category pages
* **Category Mobile Layout** — Override mobile layout separately for category pages
* **Category Content Alignment** — Override content alignment for category pages

**Three-Tier Item Hierarchy**

Items are resolved in this order:
1. Product-level override (if enabled for that product)
2. Category-level override (checks all categories assigned to the product)
3. Global items (fallback for all products and category pages)

**Three Icon Types per Item**

* **Icon Library** — 12 built-in SVG icons: Shipping, Guarantee, Returns, Secure Payment, Top Rated, Fast Delivery, Free Gift, Satisfaction, Best Price, 24/7 Support, Award/Quality, Package
* **Image** — Upload any image via the WordPress Media Library
* **None (Text Only)** — Show only the title and description without any icon

**Appearance Controls**

* Icon Size (px)
* Background Color
* Text Color
* Title Color
* Column Gap (px)
* Title Font Weight (Normal 400 through Extra Bold 800)
* Content Alignment (Left, Center, Right)
* Description Display (Single Line with overflow clip, or Multi Line with natural wrap)

**Carousel & Flash Rotate Settings**

* Show/hide navigation arrows on the carousel
* Configurable auto-play interval (set 0 to disable)
* Active dot colour
* Flash Rotate rotation interval

**Shortcode**

Use the shortcode anywhere in your content for full manual placement:

`[ssppi_benefits]`

Optional attributes:

* `layout` — Override the layout for this instance (e.g. `layout="carousel"`)
* `product_id` — Display benefits for a specific product (e.g. `product_id="42"`)

Example: `[ssppi_benefits layout="grid" product_id="123"]`

**Import / Export**

Export all global benefit items and plugin settings to a JSON file from the plugin settings page. Import a previously exported file to restore your configuration — useful for migrating between sites or keeping backups. Per-product and per-category overrides are not included in the export.

**Theme Templates**

All five layout templates can be overridden from your theme. Copy any template file from `wp-content/plugins/woocommerce-product-benefits/templates/` to `wp-content/themes/your-theme/woocommerce-product-benefits/` and customise freely.

**Developer Hooks**

* `ssppi_render_items` — Filter benefit items before rendering on product pages
* `ssppi_render_settings` — Filter display settings before rendering on product pages
* `ssppi_render_category_items` — Filter benefit items before rendering on category pages
* `ssppi_render_category_settings` — Filter display settings before rendering on category pages
* `ssppi_pi_render_items` — Filter payment icon items before rendering
* `ssppi_pi_render_settings` — Filter payment icon display settings before rendering

**Payment Icons Bar**

Display a row of accepted payment method icons anywhere on your store. Goes alongside — but is completely independent of — the benefit bar.

* **Built-in icon library** — a broad set of payment SVGs (Visa, Mastercard, PayPal, Apple Pay, Google Pay, Stripe, and more), always color-accurate.
* **Two icon types** — library icons or WordPress Media Library image.
* **Three placement options** — product page (before or after the Add to Cart form), cart page (before or after the Checkout button), and the site-wide footer.
* **Flexible header** — optional title with configurable text, font size, font weight (300–700), color, and left/center/right alignment. Optional lock icon beside the title.
* **Banner layout** — Column mode (header stacks above icons) or Row mode (header and icons sit side by side, with optional mobile stack).
* **Style modes** — Default (full color) or Monochrome (grayscale filter).
* **Sizing and spacing** — separate icon sizes and gap values for desktop and mobile.
* **Placement CSS classes** — each placement adds a modifier class (`ssppi-pi-placement-footer`, `ssppi-pi-placement-product`, `ssppi-pi-placement-cart`) so you can style each location independently from your theme stylesheet.
* **No render-blocking CSS** — styles are inlined via `wp_add_inline_style` rather than a `<link>` tag; assets load only on pages that actually display the bar.
* **Live admin preview** — changes to all settings are reflected instantly in a sticky preview panel beside the icon picker.
* **Theme template override** — copy `templates/payment-icons.php` to your theme to fully customise the markup.

**Performance**

CSS and JavaScript are registered early and enqueued only on pages that actually display a benefit bar or payment icons bar. No assets are loaded on unrelated pages. Payment icon styles are fully inlined to avoid render-blocking requests on above-fold content.

**WooCommerce HPOS Compatible**

Fully compatible with WooCommerce High Performance Order Storage (Custom Order Tables).

== Installation ==

1. Upload the `woocommerce-product-benefits` folder to the `/wp-content/plugins/` directory, or install directly via the WordPress Plugins screen.
2. Activate the plugin through the **Plugins** screen in WordPress.
3. Go to **WooCommerce → Settings → Product Benefits** to configure global items and settings.
4. Optionally open any product's **Product Data → Benefits** tab to set per-product overrides.
5. Optionally open any product category (**Products → Categories → Edit**) to set per-category overrides.

== Frequently Asked Questions ==

= Does this plugin require WooCommerce? =

Yes. WooCommerce must be installed and active. The plugin will display an admin notice and will not load if WooCommerce is missing.

= How does the item hierarchy work? =

When displaying benefits for a product, the plugin checks in this order:
1. Does the product have its own override enabled? If yes, use the product's items.
2. Does any category assigned to this product have an override enabled? If yes, use the first matching category's items.
3. Otherwise fall back to the global items configured in WooCommerce → Settings → Product Benefits.

= Can I use different layouts on the same site? =

Yes. The global layout applies to all product pages. You can override it per shortcode instance using the `layout` attribute. For category archive pages, you can set a separate desktop and mobile layout independently.

= Will the carousel work without JavaScript? =

The carousel and flash-rotate layouts require JavaScript to animate. Icon list, grid, and inline layouts are pure CSS and work without JavaScript.

= Can I override templates in my theme? =

Yes. Copy any file from `plugins/woocommerce-product-benefits/templates/` to `themes/your-theme/woocommerce-product-benefits/` and it will be used instead of the plugin's version.

= How do I use the shortcode? =

Place `[ssppi_benefits]` anywhere in a post or page. Optional attributes:
* `layout="carousel"` — forces a specific layout for this instance
* `product_id="42"` — shows benefits for a specific product instead of the current post

= What does Export include? =

The export JSON contains all plugin settings and global benefit items. It does not include per-product or per-category overrides. Importing overwrites the current global settings and items.

= Is this compatible with WooCommerce HPOS? =

Yes. The plugin declares compatibility with WooCommerce High Performance Order Storage (Custom Order Tables).

= What is the Payment Icons bar and how does it differ from the benefit bar? =

The Payment Icons bar is a separate, independent feature for displaying accepted payment method logos (Visa, Mastercard, PayPal, etc.). It has its own settings page under WooCommerce → Settings → Product Benefits → Payment Icons. It does not share items, settings, or templates with the benefit bar — both can be active on the same page simultaneously.

= Can I style the payment icons bar differently in the footer versus the product page? =

Yes. When the bar is rendered, a placement modifier class is added to the wrapper: `ssppi-pi-placement-footer` in the footer, `ssppi-pi-placement-product` on product pages, and `ssppi-pi-placement-cart` on the cart. Use these classes in your theme stylesheet to target each location independently.

== Screenshots ==

1. Global settings — Display Settings section showing layout, mobile layout, and position options.
2. Global settings — Appearance section showing colour, size, alignment, and font weight controls.
3. Global settings — Carousel and Flash Rotate interval settings.
4. Global settings — Category Page section showing enable toggle, position, desktop layout, mobile layout, and alignment.
5. Global settings — Benefit items repeater with draggable rows, icon picker, and image upload.
6. Global settings — Import / Export panel.
7. Product Data → Benefits tab showing the per-product override checkbox and items repeater.
8. Products → Categories edit screen showing the per-category override fields.
9. Frontend — Icon List layout on a product page.
10. Frontend — Carousel layout with navigation arrows and dot indicators.
11. Frontend — Flash Rotate layout animating items in sequence.
12. Frontend — Grid layout showing four benefits in a responsive grid.
13. Frontend — Inline Compact layout in a narrow bar with dividers.
14. Frontend — Benefit bar displayed on a category archive page.

== Changelog ==

= 1.0.0 =
* Initial release.

**Five frontend layouts**

* Icon List — horizontal/wrapping list with icon, title, description.
* Carousel — sliding carousel with optional arrows, dots, and auto-play.
* Flash Rotate — single-item rotation animation.
* Grid — responsive CSS grid of benefit items.
* Inline Compact — single-line bar with divider separators.

**Display position**

* Six positions on product pages: Before/After Add to Cart Form, After Add to Cart Button, After Price, Before Single Product, Shortcode Only.

**Mobile layout**

* Independent mobile layout override for screens ≤ 768 px (Same as Desktop / Flash Rotate / Carousel / Stack).

**Per-product overrides**

* Benefits tab added to WooCommerce Product Data metabox.
* Override checkbox with items repeater; items saved as sanitized JSON post meta.
* Nonce verification and `edit_post` capability check on save.

**Per-category overrides**

* Benefits section added to product category add and edit screens.
* Override checkbox with items repeater; items saved as sanitized JSON term meta.
* Nonce verification and `manage_product_terms` capability check on save.

**Three-tier item hierarchy**

* Resolution order: product override → category override → global fallback.

**Category archive page display**

* Enable/disable benefit bar on category archive pages independently.
* Two position options: After Category Description/Title or Before Product Grid.
* Category Desktop Layout (inherits global or overrides to a specific layout).
* Category Mobile Layout (inherits global mobile setting or overrides independently).
* Category Content Alignment (inherits global or overrides to Left/Center/Right).

**Three icon types**

* Built-in SVG icon library with 12 icons.
* WordPress Media Library image upload.
* None (text-only items).

**Appearance settings**

* Icon size, background color, text color, title color, column gap.
* Title font weight (400–800).
* Content alignment (Left / Center / Right).
* Description display (Single Line / Multi Line).

**Carousel settings**

* Show/hide navigation arrows.
* Auto-play interval (0 = disabled).
* Active dot color.

**Flash Rotate settings**

* Configurable rotation interval.

**Shortcode**

* `[ssppi_benefits]` with optional `layout` and `product_id` attributes.

**Import / Export**

* Export all global settings and benefit items to a dated JSON file.
* Import via XHR/FormData; validates plugin identifier, sanitizes all values on import.
* Nonce protection and `manage_woocommerce` capability check on both handlers.

**Conditional asset loading**

* CSS registered for all layouts; enqueued only when the relevant layout is active on the current page.
* Carousel and Flash Rotate JavaScript loaded only when those layouts are in use.
* CSS custom properties (color, size, gap tokens) output as a single inline style block.

**Theme template overrides**

* All five layout templates overridable from `{theme}/woocommerce-product-benefits/`.

**Developer filters**

* `ssppi_render_items`, `ssppi_render_settings` (product pages).
* `ssppi_render_category_items`, `ssppi_render_category_settings` (category pages).

**Payment Icons bar**

* Built-in SVG payment icon library (Visa, Mastercard, PayPal, Apple Pay, Google Pay, Stripe, and more).
* Two icon types: library, WordPress Media Library image.
* Three placement options: product page (before/after Add to Cart form), cart page (before/after Checkout button), site footer.
* Optional header with configurable title, font size, font weight (300/400/500/600/700), color, and alignment.
* Optional lock icon beside the header title.
* Banner layout modes: Column (header stacks above icons) and Row (side by side, optional mobile stack).
* Style modes: Default (full color) and Monochrome (grayscale).
* Separate icon sizes and gap values for desktop and mobile.
* Placement modifier classes on the wrapper: `ssppi-pi-placement-footer`, `ssppi-pi-placement-product`, `ssppi-pi-placement-cart`.
* All styles inlined via `wp_add_inline_style` — no render-blocking `<link>` tag; assets load only on pages that display the bar.
* Static CSS + dynamic CSS custom properties combined into a single inline `<style>` block.
* Live admin preview with sticky right-column layout; all settings reflected in real time.
* Two-column admin layout: settings on the left, icon picker and live preview sticky on the right.
* Developer filters: `ssppi_pi_render_items`, `ssppi_pi_render_settings`.
* Theme template override: `{theme}/woocommerce-product-benefits/payment-icons.php`.

**Admin UI**

* Drag-and-drop sortable item rows using jQuery UI Sortable.
* Collapsible item rows; clicking the item label or the toggle arrow expands/collapses.
* Live title preview updates the row header as you type.
* Icon picker with active state highlight.
* Image upload via WordPress media frame with remove button.
* Icon type switcher hides/shows relevant fields instantly.

**Security**

* All saved data sanitized: `sanitize_text_field`, `wp_kses_post`, `absint`, `sanitize_hex_color`.
* Nonce verification on every save action (global items, product meta, category meta, import).
* Capability checks before any data write: `manage_woocommerce`, `edit_post`, `manage_product_terms`.
* SVG output escaped with `wp_kses` + plugin-defined SVG allowlist.
* All frontend output escaped with `esc_html`, `esc_attr`, `esc_url`, `wp_kses_post`.

**Compatibility**

* Requires WordPress 6.0+, WooCommerce 7.0+, PHP 7.4+.
* Declared compatible with WooCommerce High Performance Order Storage (HPOS).
* Follows WordPress Coding Standards (PHPCS WordPress ruleset).

== Upgrade Notice ==

= 1.0.0 =
Initial release — no upgrade steps required.
