=== Rankology Ajax Live Search ===
Contributors: rankology
Tags: ajax product filter, woocommerce product search, search by sku, woocommerce product filter, woocommerce filter
Requires at least: 6.2
Tested up to: 7.0
Requires PHP: 8.1
Stable tag: 1.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

High-performance AJAX live search with relevance ranking, advanced filters, search analytics, and WooCommerce support.

== Description ==

Rankology Ajax Live Search upgrades the native WordPress search experience with fast, modern AJAX results, a dedicated relevance index, and a polished admin workflow. Visitors get instant suggestions as they type; site owners get visibility into what people search for and what they cannot find.

Built for production sites, Rankology is suitable for blogs, business websites, membership portals, and WooCommerce stores that need accurate, configurable search without slowing down the front end.

= Search experience =

* **Live AJAX search** — Results update as visitors type, with configurable debounce and keyboard-friendly navigation.
* **Autocomplete suggestions** — Surface popular, recent, and Google-style query suggestions before a full search runs.
* **Multiple result layouts** — Vertical dropdown, horizontal grid, polaroid tiles, and isotopic masonry.
* **Visual polish** — Thumbnails, keyword highlighting, smart excerpts, and 8 built-in color themes (Classic, Dark Pro, E-commerce, Glass, Magazine, Material Design, Minimal, Neon).
* **Single-result redirect** — Optionally send visitors straight to the destination when only one match is found.
* **Modal and voice search** — Open search in a modal overlay and accept voice input where supported by the browser.
* **Add to cart from results** — Add WooCommerce products straight from the live results dropdown, no page reload required.
* **Trending / popular searches widget** — Surface trending queries on the frontend as a standalone block, shortcode, or classic widget.
* **Live filtering on archive pages** — Apply the same AJAX filters directly on taxonomy and post-type archive pages, not just the search results view.
* **Responsive UI** — Mobile-friendly search instances and result panels.

= Relevance and performance =

* **Custom search index** — Dedicated indexing engine with BM25-style relevance scoring and configurable field weights.
* **Configurable content scope** — Include posts, pages, products, custom post types, taxonomies, and custom fields.
* **File indexing** — Optional extraction of text from attached PDF, DOCX, and TXT files.
* **WooCommerce ready** — Search products, show prices, add to cart from results, and weight SKU and catalog fields.
* **Caching and rate limiting** — Protect the public search endpoint from abuse while keeping responses fast.

= Filters and discovery =

* **Live filters** — Taxonomy, price range, and custom field filters with AJAX updates, usable in search results and on archive pages.
* **Filter builder** — Configure filter panels from the admin without writing code.
* **SERP templates** — Customize the on-site search results page experience, including archive fields, SEO fields, and template layout.
* **Result Tuning** — a dedicated workspace covering:
  * **Redirects** — send specific queries to a chosen URL by pattern, role, or language.
  * **Merchandising** — pin, promote, or hide specific results, with optional scheduled campaign windows (e.g. Black Friday) that activate and expire automatically.
  * **A/B Experiments** — test ranking or layout variations and compare performance.
  * **Synonyms** — map alternate terms to the same results.
  * **Stop Words** — exclude noise words from matching.

= Search widgets =

Create unlimited **Search Widgets** — each an independent placement with its own post types, layout, theme, behavior, filters, and relevance-weight overrides.

* Gutenberg block (`rankajlisrh/search`)
* Shortcode: `[rankajlisrh]`
* Standalone filter panel shortcode: `[rankajlisrh_filters]`
* Trending searches shortcode: `[rankajlisrh_trending_searches]`
* Classic widget
* Per-widget shortcodes for precise placement in headers, sidebars, and landing pages

= Smart Search (AI-assisted, optional) =

Connect OpenAI, Google Gemini, or Anthropic Claude to layer AI features on top of the core search engine — nothing here is required for the plugin to work:

* **AI Overviews** — a generated summary paragraph above the result list.
* **Per-result AI summaries** — short AI-written summaries for individual hits.
* **Smart query understanding** — typo correction and natural-language constraint parsing (e.g. "red shoes under $50").
* **Intent ranking** — reorders results based on detected query intent.
* **Semantic redirects** — AI-assisted fallback matching for redirect rules when no exact pattern matches.
* **Related content & "People also search for"** — AI-surfaced related content carousel and related-query suggestions.
* **Personalization & click learning** — results adapt per-session based on prior clicks, without user accounts or persistent profiles.
* **Phrase autocomplete** — AI-assisted phrase-level suggestions.
* **Usage & cost dashboard** — track token usage and estimated cost per provider.
* **Encrypted API keys** — provider keys are encrypted at rest, never stored as plaintext.

= Analytics and optimization =

Understand how search performs on your site:

* **Overview dashboard** — Top queries, trending terms, and zero-result searches.
* **Search logs** — Detailed query history with results count, click tracking, device, and locale.
* **Per-search detail view** — Drill into an individual search: query, filters applied, results returned, and clicks.
* **Engagement tracking** — Anonymous scroll-depth funnel and mouse heat-zone data for the search results area.
* **Zero-result and low-CTR alerts** — Scheduled checks that flag queries returning nothing or rarely getting clicked, so content or indexing gaps get noticed automatically.
* **Query redirect rules** — Send specific searches to a chosen URL by pattern, role, or language.
* **Exports** — Download analytics as CSV or a printable PDF report.
* **Scheduled email reports** — Optional periodic analytics summaries sent via WordPress `wp_mail()`.

= Developer tools =

* **REST API** — Headless and custom integrations under the `rankajlisrh/v1` namespace: search, click tracking, redirects, merchandising, A/B experiments, engagement tracking, personalization, voice parsing, and streaming AI summaries.
* **WP-CLI commands** — `wp rankajlisrh index rebuild|status|reindex`, `cache flush`, `benchmark`, and `embed` (generate Smart Search embeddings) from the command line.
* **Extensible hooks** — Customize search criteria and response payloads via WordPress filters.
* **Multisite aware** — Network-level settings synchronization, with optional per-subsite overrides for individual sites in a WordPress multisite install.
* **Privacy tools integration** — Search logs are included in WordPress core's personal data export and erase tools, and analytics tracking respects the WP Consent API "statistics" category when active.
* **Compatibility layer** — Automatic detection of, and remediation adapters for, common caching plugins (so cached pages don't serve stale search results) and page builders (Elementor, Divi, WPBakery, Bricks).
* **Migration tools** — One-click import from Ajax Search Pro and SearchWP, plus Rankology's own JSON settings export/import for backups and staging-to-production moves.

= Admin =

A unified **Rankology** menu in wp-admin: Dashboard, Search Indexing, Appearance, Search Filter, SERP Builder, Result Tuning, Smart Search, Analytics & Logs, Integrations, Tools, and Settings — organized set up → tune → measure → maintain, for clarity on both small blogs and larger editorial teams. Search Widgets are managed from their own screen (**Rankology → Search Widgets**).


== Installation ==

= Automatic installation =

1. In your WordPress admin, go to **Plugins → Add New**.
2. Search for **Rankology Ajax Live Search**.
3. Click **Install Now**, then **Activate**.

= Manual installation =

1. Upload the `rankajlisrh` folder to `/wp-content/plugins/`.
2. Activate the plugin through the **Plugins** screen in WordPress.
3. Go to **Rankology → Appearance** to review global search settings.
4. Go to **Rankology → Search Widgets** to create your first search widget, or add the block/shortcode to a page.

= After activation =

1. Visit **Rankology → Search Indexing** and run an initial index build if one is not started automatically.
2. Place a search widget using the Gutenberg block, `[rankajlisrh]` shortcode, or classic widget.
3. Optional: enable search logging under **Rankology → Settings**, then review results under **Rankology → Analytics & Logs**.

== Frequently Asked Questions ==

= Does Rankology work with WooCommerce? =

Yes. Rankology can include WooCommerce products in search results, display product prices where appropriate, and apply relevance weighting to SKU and product fields when WooCommerce is active.

= Does this replace the default WordPress search? =

Rankology does not remove WordPress core search automatically. You place the Rankology search bar where you want it — via block, shortcode, or widget — and can customize the on-site search results template for a complete replacement experience.

= How do I add search to my theme header? =

Create a Search Widget in **Rankology → Search Widgets**, copy its shortcode, and paste it into your header template, a block theme header pattern, or a hook-friendly location. You can also use the **Rankology Search** Gutenberg block in the site editor.

= What is a Search Widget? =

A Search Widget is an independent search configuration. Each widget can target different post types, use a different layout or theme, enable its own filters, and override relevance weights — useful when a shop search and a blog search need different behavior.

= Will Rankology slow down my site? =

Rankology is built for performance. Search queries use a dedicated index and cached responses where appropriate, and the public endpoint includes rate limiting. Initial indexing runs in the background and can be managed from the admin or WP-CLI.

= Can I see what visitors search for? =

Yes. Enable search analytics and visit **Rankology → Analytics & Logs** for top queries, trending terms, zero-result searches, engagement (scroll/mouse) tracking, and individual log entries. Data can be exported for reporting, and zero-result/low-CTR alerts flag emerging gaps automatically.

= What are query redirect rules? =

Redirect rules let you send specific search queries (exact or pattern-based) to a custom URL — for campaigns, synonyms, or steering users to the right landing page. Rules can be scoped by user role and language, and live under **Rankology → Result Tuning → Redirects**. With Smart Search enabled, semantic matching can also catch queries that don't match a rule's exact pattern.

= What does Smart Search / AI do, and is it required? =

No — Smart Search is entirely optional. When enabled with an API key for OpenAI, Google Gemini, or Anthropic Claude, it adds AI overviews, per-result summaries, typo-tolerant query understanding, intent-based ranking, semantic redirects, related-content suggestions, and click-based personalization on top of the core keyword/BM25 search engine, which works fully on its own without it.

= Is there a REST API? =

Yes. Rankology exposes REST endpoints under `rankajlisrh/v1` covering search, click tracking, redirects, merchandising, A/B experiments, engagement tracking, personalization, voice parsing, and Smart Search summary streaming — suitable for headless WordPress and custom front ends.

= Does Rankology work on multisite? =

Yes. Network-level settings synchronization is available for WordPress multisite installations, with optional per-subsite overrides when individual sites need different settings.

= Do I need extra libraries for PDF or DOCX indexing? =

Yes, if you want file content indexing beyond plain TXT files. Install `smalot/pdfparser` for PDF support and `phpoffice/phpword` for DOCX support via Composer on your server. Rankology detects them automatically when available. They are not bundled with the plugin.

= Does Rankology bundle React or other JavaScript frameworks? =

No. The admin dashboard hub uses WordPress core packages (`wp-element`, `wp-components`, `wp-i18n`). Frontend scripts are custom and depend on jQuery, which WordPress provides.

= Does Rankology send data to external services? =

When **Google-style autocomplete** is enabled, partial search terms are sent to Google's public suggest API (`suggestqueries.google.com`) to retrieve suggestion phrases. Responses are cached locally with WordPress transients. All other search, indexing, and analytics data stays on your WordPress site unless you configure email reports through your own mail server via `wp_mail()`.

== Screenshots ==

1. Rankology Overview dashboard with index status and quick actions.
2. Live AJAX search results with thumbnails and keyword highlighting.
3. Search Configuration — design, indexing, filters, and autocomplete settings.
4. Search Widget editor with layout, theme, and relevance options.
5. Analytics & Search Logs with top queries, trends, and detailed log table.
6. Result Tuning — Redirects, Merchandising, Experiments, Synonyms, and Stop Words.

== Changelog ==

= 1.1.0 =
* Zero-result and low-CTR alerts — scheduled analytics checks that flag queries returning nothing or rarely clicked.
* Trending / Popular Searches frontend widget — Gutenberg block, shortcode, and classic widget support.
* Add to cart directly from live search results for WooCommerce products.
* Multisite per-subsite overrides on top of existing network settings sync.
* Privacy tools integration — search logs are exportable/erasable via WordPress core's personal data tools, and tracking respects the WP Consent API "statistics" category when present.
* Scheduled campaign windows for result merchandising rules (pin/promote/hide rules can activate and expire automatically on start/end dates).
* Cache-plugin compatibility layer — automatic detection and remediation adapters for common caching plugins so cached pages don't serve stale search results.
* Admin information architecture consolidated from 15 to 11 sidebar rows, with several settings relocated to their correct tabs.
* Search Tuning tabs now switch in place with per-tab hero sections; sidebar "jump" links now stay in sync with the active tab across all Settings and Integrations pages.
* Analytics & Logs Engagement tab now shows the scroll-depth funnel and mouse heat zones side by side.
* Admin settings clarity, field dependency wiring, and save-safety across multiple settings tabs.
* Full PHPCS compliance pass across analytics, multisite, and Smart Search code, and remaining unprefixed JS globals prefixed per WordPress.org plugin review guidance.
* Database schema updated to version 1.10.0 (automatic on activation/update, no manual action needed).

= 1.0.0 =
* Initial public release.
* Live AJAX search with autocomplete, multiple layouts, themes, and responsive UI.
* Custom search index with BM25 relevance scoring, field weights, and optional PDF/DOCX/TXT extraction.
* Search Widgets (custom post type) with Gutenberg block, shortcode, and classic widget support.
* Advanced live filters: taxonomy, price range, custom fields, and visual filter builder.
* WooCommerce product search with price display and SKU weighting.
* Analytics & Search Logs: top queries, trending terms, zero-result tracking, click logging, CSV/PDF export, and email reports.
* Query redirect rules with admin UI and REST API.
* REST API, rate limiting, transient caching, modal search, and voice search.
* WP-CLI index commands, multisite network settings sync, and legacy plugin migration tools.

== Upgrade Notice ==

= 1.1.0 =
Adds Zero-Result/Low-CTR alerts, a Trending Searches widget, WooCommerce add-to-cart from live results, multisite per-subsite overrides, privacy/consent tooling, scheduled merchandising campaigns, and an updated admin layout. The database schema updates automatically on activation — no manual steps required.

= 1.0.0 =
Initial release of Rankology Ajax Live Search. After updating, rebuild the search index from **Rankology → Search Indexing** if you are upgrading from a pre-release build.

== Credits ==

= Bundled libraries =

* [Composer ClassLoader](https://github.com/composer/composer) — MIT License. Copyright (c) Nils Adermann, Jordi Boggiano. Used for PSR-4 autoloading in `vendor/composer/`.

= WordPress core dependencies (not bundled) =

* jQuery — Admin and frontend UI interactions.
* WordPress packages (`wp-element`, `wp-components`, `wp-i18n`) — Admin dashboard hub UI.

= Optional Composer libraries (not bundled) =

* [smalot/pdfparser](https://github.com/smalot/pdfparser) — LGPL-3.0. Optional. PDF attachment text extraction.
* [phpoffice/phpword](https://github.com/PHPOffice/PHPWord) — LGPL-3.0. Optional. DOCX attachment text extraction.

TXT file extraction uses native PHP only.

= Compatible plugins (not bundled) =

* WooCommerce — Product search, prices, SKU weighting, and variation indexing.
* WPML — Per-language indexing and search filtering.
* Polylang — Per-language indexing and search filtering.
* Advanced Custom Fields (ACF) — Custom field indexing and filter UI.
* WP Mail Logging — View scheduled analytics email content from the admin.

== Privacy Policy ==

This plugin stores search analytics, index data, and plugin settings in your WordPress database. It does not phone home to Rankology servers.

= Personal data export and erasure =

Search logs associated with a visitor are included automatically in WordPress core's built-in personal data export and erase tools (**Tools → Export/Erase Personal Data**), so data-subject requests can be fulfilled without manual database work.

= Consent Awareness =

When the [WP Consent API](https://wordpress.org/plugins/wp-consent-api/) is active, Rankology checks the visitor's "statistics" consent category before logging search queries, clicks, or engagement data. If a compatible consent plugin has not granted that category, tracking is skipped for that visitor.

= Google Suggest API =

When **Google-style autocomplete** is enabled in **Rankology → Appearance → Autocomplete**, the plugin may send partial search terms from your site to Google's public suggestion service at `https://suggestqueries.google.com/complete/search`.

* **What is sent:** The current partial search query and optional language or region parameters.
* **When it is sent:** Only while autocomplete is enabled and local suggestion sources do not already fill the suggestion list.
* **Why it is sent:** To retrieve Google-style query suggestions for visitors.
* **Caching:** Responses are cached locally with WordPress transients to reduce repeat requests.
* **Third-party policy:** Review [Google's Privacy Policy](https://policies.google.com/privacy) for how Google handles data sent to its services.

= AI provider integrations (optional) =

When Smart Search AI features are enabled and an API key is configured, the plugin may send request data to your selected provider (OpenAI, Google Gemini, or Anthropic Claude) to generate summaries, query understanding, or related AI-assisted search output.

* **What may be sent:** Search query text and limited content context required to generate a response (for example, titles and excerpts for summary generation).
* **When it is sent:** Only when AI features are enabled and a remote provider is selected in plugin settings.
* **Why it is sent:** To return AI-generated search enhancements configured by the site owner.
* **Caching:** AI responses may be cached locally (WordPress transients) when response caching is enabled.
* **Third-party policies:** [OpenAI Privacy Policy](https://openai.com/policies/privacy-policy), [Google Privacy Policy](https://policies.google.com/privacy), [Anthropic Privacy Policy](https://www.anthropic.com/privacy).

= Email reports =

If you enable scheduled analytics email reports, message content is sent through your WordPress site's configured mail transport (`wp_mail()`). Rankology does not provide or operate that mail service.

= Voice search =

When voice search is used in supported browsers, speech recognition is handled by the visitor's browser. Rankology does not record or transmit audio to its own servers.
