# Factorize Catalog — 5-Minute Quickstart

Get your store sorting like a merchandiser: in stock first, proven sellers up, deepest discount wins — plus SKU search, "sold this week" badges, auto Featured picks, and infinite scroll.

## Prerequisites

- WordPress 6.2+ and PHP 7.4+
- **WooCommerce** active (the plugin is inert without it)
- **Factorize Essentials** active — recommended. It provides `empire_tools_discount_pct()`, which the deal rank calls for its percent-off signal. Without it (or your own implementation of that function), rank recomputation on product save will fail.
- WP-CLI access is handy for the one-time backfill (not required for day-to-day use)

## Install

1. Copy the `factorize-catalog` folder into `wp-content/plugins/` (or upload the zip via **Plugins > Add New > Upload Plugin**).
2. Activate **Factorize Catalog**. A "Factorize" menu appears in wp-admin — this plugin's card lives on the **Selling** tab.

## First value in 4 steps

1. **Backfill the ranks once** (existing catalogs only — new products rank themselves on save):

   ```sh
   wp eval "empire_tools_rebuild_ranks();"
   ```

2. **Visit your shop page.** The sorting dropdown now defaults to **Best deals**, with **Most popular** alongside. Out-of-stock items sink to the bottom of every sort, and archives load continuously instead of paginating.

3. **Try a SKU search.** Search for part of a model number to see SKU matches mixed into results (in-stock first); search for an exact SKU to be redirected straight to that product — even if it is out of stock.

4. **Pick Featured products** (optional):

   ```sh
   wp eval "empire_tools_refresh_featured();"
   ```

   This flags the top industry-popularity products that are in stock and photographed as WooCommerce Featured (falling back to the best-ranked deals). If Factorize Auctions is installed, its hourly tick runs this for you automatically.

From here everything maintains itself: ranks refresh on product saves, stock changes, and order status changes; weekly "sold this week" counts refresh as orders come in.

## Configuration

Values come from the `factorize-catalog_options` option (an array; the legacy `empire-catalog-ranking_options` option still works), merged over defaults and passed through the `factorize-catalog_config` filter. Read anywhere via `empire_catalog_config( 'key' )`.

| Key | Default | Effect |
| --- | --- | --- |
| `featured_limit` | `4` | How many products `empire_tools_refresh_featured()` selects as Featured when called without an explicit limit. |

Example override:

```php
update_option( 'factorize-catalog_options', array( 'featured_limit' => 6 ) );
```

or

```php
add_filter( 'factorize-catalog_config', function ( $config ) {
    $config['featured_limit'] = 6;
    return $config;
} );
```

## Troubleshooting

- **Fatal error (undefined function `empire_tools_discount_pct`) when saving a product.** The rank calculation depends on that function, which ships with Factorize Essentials. Activate Essentials, or define the function yourself before saving products. Everything else (search, stock-first ordering, badges, infinite scroll) works without it.
- **Shop order looks unchanged after activation.** On an existing catalog, `_et_rank` is empty until each product is saved — the "Best deals" sort has nothing to sort by. Run `wp eval "empire_tools_rebuild_ranks();"` once and it takes effect immediately.
- **No "sold this week" badges.** They only render when a product sold at least one unit in the last 7 days, counted from *processing* and *completed* orders. Counts are cached for an hour in the `et_weekly_sales` transient, but the cache is busted whenever an order changes status, so it stays fresh in practice.
- **Featured never changes on its own.** This plugin exposes the refresh as a function but does not schedule it. Factorize Auctions' hourly tick calls it when installed; otherwise run it via WP-CLI or your own cron job.
- **Infinite scroll doesn't kick in.** The script needs WooCommerce's standard markup: a `ul.products` grid and a `nav.woocommerce-pagination` block with a next-page link. Themes that replace that markup fall back to normal numbered pagination (which keeps working — the script never removes it, only hides it).
