Getting Started

This guide walks you through a full setup from a fresh install to a working filter on the frontend.

---

Install the Plugin

1. Download the WPXFacets .zip file from your account dashboard on wpxfacets.com.
2. In your WordPress admin, go to Plugins → Add New → Upload Plugin.
3. Select the downloaded .zip and click Install Now.
4. Click Activate Plugin.

After activation, a new XFacets menu item appears in the WordPress admin sidebar.

---

Activate Your ElasticServer server

1. Go to XFacets → Settings → Elastic Server.
2. Enter your Elastic Server URL, User and Pass — both are available in your wpxfacets.com account dashboard.
3. Click Save.

If you’re on the Free plan, you can skip this step. License activation is required for Starter, Grow and Custom plans to connect to the managed Elasticsearch infrastructure. The free plan uses native WordPress queries.

---

Set the Filter Mode

1. Go to XFacets → Settings → General.
2. Set Filter Mode to Elasticsearch.
3. Click Save.

---

Run Your First Sync

During the 15-day Starter trial, Elasticsearch indexing is limited to 1,000 products.

Before facets can return results, your product catalog needs to be indexed.

1. Go to XFacets → Sync.
2. Click Start Sync.
3. Wait for the sync to complete. Progress is shown inline.

Run a sync whenever you make significant changes to your catalog — new products, updated attributes, new taxonomies. Small individual changes (single product saves) are picked up automatically.

---

Create a Facet

1. Go to XFacets → Facets → Add New.
2. Give the facet a name (internal label, not shown on frontend unless used as the filter heading).
3. Select a Source — the data origin for this facet (e.g., Taxonomy, Product Attributes, WooCommerce).
4. Select a Source Value if required by the source (e.g., for WooCommerce source: Price, Rating, Stock).
5. Select a Display Type — the UI component shown to the user (e.g., Checkbox, Slider, Rating).
6. Configure any Display Settings (see Display Settings).
7. Click Save.

Available display types update dynamically based on your source selection. Not all combinations are valid — see the Source → Display Type Reference.

---

Create a Filter Form

A Filter Form is a container that groups one or more facets and renders them together on the frontend.

1. Go to XFacets → Filter Forms → Add New.
2. Give the form a name.
3. Add the facets you want to include.
4. Click Save.

Currently, a single Filter Form with all your facets is the only supported setup. Multiple forms with separate shortcodes will be supported in a future release.

---

Display on the Frontend

WPXFacets uses two shortcodes to render the filter UI and the filtered results.

Create a new WordPress page (or edit an existing one) and add both shortcodes to the page content:

[xfacets_filter_form]
[xfacets_search_results]

• [xfacets_filter_form] — renders the filter sidebar with all facets from your active Filter Form.
• [xfacets_search_results] — renders the product grid, updated dynamically as filters are applied.

Place them side by side in a two-column layout for a standard filter + results UI.

---

Settings

License

Field	Description
License Key	Provided in your wpxfacets.com account dashboard.
Token	Paired with the license key. Required for Starter, Grow and Custom plans.

Elastic Server

Field	Description
ElasticSearch Server URL	Elasticsearch URL, auto-generated at subscription activation.
Username	Elasticsearch username, auto-generated at subscription activation.
Password	Elasticsearch password, auto-generated at subscription activation.

Credentials are tied to your WooCommerce subscription. If your subscription lapses, access is automatically revoked.

General

Field	Description
Filter Mode	Sets the query backend. Options: WordPress Native (Free) or Elasticsearch (Starter / Grow / Custom).

---

Sync

The Sync screen triggers a full re-index of your product catalog into Elasticsearch.

When to run a manual sync:

• After initial setup.
• After bulk-importing products.
• After adding or renaming taxonomies or product attributes.
• After changing which fields you want to use as facet sources.

Incremental changes (editing a single product) are indexed automatically on save and do not require a manual sync.

---

Filter Forms

A Filter Form groups multiple facets into a single renderable unit.

• Each form has a name and an ordered list of facets.
• The form is rendered on the frontend via the [xfacets_filter_form] shortcode.
• Facets appear in the order they are listed in the form.

To add a facet to a form, the facet must already exist under XFacets → Facets.

[SCREENSHOT PLACEHOLDER — Filter Form screen]

---

Facets

A facet defines a single filter dimension: what data it reads from (source), how it presents choices to the user (display type), and any additional configuration (display settings).

---

Source

The Source defines where the facet reads its values from.

Source	Description
Taxonomy	Any registered WordPress taxonomy — includes WooCommerce product categories, tags, and custom taxonomies.
Meta Fields	Any post meta field attached to products. Supports the widest range of display types.
WP Objects	Post content (title, description). Can only be used with the Search display type.
WooCommerce	Native WooCommerce fields: Price, Rating, On Sale, Discounted, Favorites, Stock. Each value maps to specific display types — see reference below.
Product Attributes	WooCommerce product attributes (e.g., Color, Size). Supports Checkbox and Radio.

---

Display Type

The Display Type defines the UI component rendered for this facet.

Display Type	Description
Checkbox	Multi-select list of values. User can select one or more options.
Radio	Single-select list. Only one option can be active at a time.
Slider	Dual-handle range slider. Used for numeric ranges (price, stock).
Single custom range	Two manual input fields (min / max). Alternative to the slider for numeric ranges.
Search field	Text input that filters by post content or meta field value.
Rating	Star-based filter. Filters products at or above the selected rating.

---

Source → Display Type Reference

Not all source and display type combinations are valid. The table below shows what is available for each source.

Source	Source Value	Available Display Types
Taxonomy	—	Checkbox, Radio
Product Attributes	—	Checkbox, Radio
Meta Fields	—	Checkbox, Radio, Slider, Single custom range, Search, Rating
WP Objects	—	Search
WooCommerce	Price	Slider, Single custom range
WooCommerce	Rating	Rating, Single custom range
WooCommerce	On Sale	Checkbox
WooCommerce	Discounted	Checkbox, Single custom range
WooCommerce	Favorites	Checkbox
WooCommerce	Stock	Checkbox, Single custom range

The facet editor enforces these constraints automatically — invalid display types are disabled when you select a source.

---

Display Settings

The following settings are available on every facet regardless of source or display type.

Setting	Description
Hide filter	Saves the facet but does not render it on the frontend. Useful for keeping a facet configured without exposing it to users yet.
Show a limited number of filter terms	Truncates the visible list of options and adds a “Show more” toggle. Useful for taxonomies or attributes with many values.