# FacetWP Remote Data

**FacetWP Remote Data** is a WordPress plugin that fetches **FacetWP-filtered data** from a remote WordPress site. This allows you to query and display posts filtered by FacetWP from an external source.

## Features
- Fetch FacetWP-filtered post IDs from a remote site.
- Retrieve full post details via the WordPress REST API.
- Easily configure remote connection settings via the **WordPress Admin**.
- **Custom Templating System:** Customize the output by overriding the default template in your theme or via a filter.
- **JavaScript Enqueueing:** Load scripts dynamically for listing and property pages.
- **Neighbourhood Pages:** Allow preselected FacetWP filters for specific pages.

## Installation
1. **Upload the plugin** to your WordPress site.
2. **Activate the plugin** via the **Plugins** menu in WordPress.
3. **Go to Settings → FacetWP Remote Settings** and enter:
    - **Username**
    - **Password**
    - **Remote Site URL**
4. Save changes and click on **'Sync FacetWP Settings'** to sync FacetWP settings from the main site.

### 'Enable Automatic Syncing' Checkbox
When enabled, this option ensures that whenever FacetWP settings are updated on the main site, a request is automatically sent to the subsite to sync and update its FacetWP settings accordingly.

### 'Select Pages' Checkbox
This setting allows you to specify which pages should retrieve and display FacetWP-filtered data from the remote site. When selected, the plugin will automatically apply remote FacetWP data to the chosen pages.

---

## **Neighbourhood Pages (Preselected Facets)**
Neighbourhood Pages allow you to **preselect FacetWP filters** for a specific page. This ensures that a user **always sees filtered results** for that page without being able to change the predefined filters.

### **How It Works**
1. **Each page can have preselected FacetWP filters.**
2. **A meta box is added to the WordPress page editor** where the admin can select preselected facet values.
3. **When a Neighbourhood Page loads, it automatically applies the preselected facet values.**
4. **Users cannot modify or remove these preselected facets from the UI.**

### **How to Set Up a Neighbourhood Page**
1. **Edit a page** in WordPress.
2. Locate the **"Preselected Facet Filters"** meta box (on the right side).
3. **Select the default values** for each facet.
4. Save the page.

Now, when users visit this page, **the selected FacetWP filters will be automatically applied**.

---

## **Caching (Transients)**
FacetWP Remote Data **caches responses from the remote site** using WordPress transients. This reduces the number of API requests and improves performance.

### **Transient Caching for Remote Site Data**
- When fetching FacetWP-filtered data or posts data, the plugin **stores the response in a transient**.
- The transient key is dynamically generated based on the **query arguments** or **post id**.
- Cached data **expires after 10 minutes**, after which a fresh request is made.

#### **Skipping Cache (Forcing a New API Request)**
You can bypass the cache and force a fresh request using the `facetwp_remote_data_skip_cache` filter:
```php
add_filter( 'facetwp_remote_data_skip_cache', '__return_true' );
```

---

## Template Customization
FacetWP Remote Data provides a flexible templating system that allows you to modify the output by copying the template file into your theme, customizing it via a filter, or both.

### **Listing Page Templating**
FacetWP Remote Data provides a template for rendering filtered listing results.

#### **How It Works**
- **Default Template Location:**
  ```
  [plugin root]/templates/facet-wp-remote-data-listing-template.php
  ```

- **Theme Override:**
  ```
  [your-theme]/facet-wp-remote-data/facet-wp-remote-data-listing-template.php
  ```

- **Filter-Based Override:**
  ```php
  add_filter( 'facet_wp_remote_data_listing_template_path', function( $template_path ) {
      return get_stylesheet_directory() . '/custom-templates/custom-facetwp-template.php';
  });
  ```

#### **How to Override the Listing Template**
1. **Copy the default template** from `[plugin root]/templates/facet-wp-remote-data-listing-template.php`.
2. **Paste it into your theme** under `[your-theme]/facet-wp-remote-data/`.
3. The `$properties_data` variable contains the properties data.
4. **Customize as needed.**

---

### **Property Page Templating**
FacetWP Remote Data also provides a **property detail page template** that loads content dynamically based on a property ID.

#### **How It Works**
- The **property page template** is responsible for displaying individual properties.
- It loads dynamically when the URL contains `?id=<property_id>`.

- **Default Template Location:**
  ```
  [plugin root]/templates/facet-wp-remote-data-property-template.php
  ```

- **Theme Override:**
  ```
  [your-theme]/facet-wp-remote-data/facet-wp-remote-data-property-template.php
  ```

- **Filter-Based Override:**
  ```php
  add_filter( 'facet_wp_remote_data_property_template_path', function( $template_path ) {
      return get_stylesheet_directory() . '/custom-templates/custom-property-template.php';
  });
  ```

#### **How to Override the Property Template**
1. **Copy the default template** from `[plugin root]/templates/facet-wp-remote-data-property-template.php`.
2. **Paste it into your theme** under `[your-theme]/facet-wp-remote-data/`.
3. The `$property_data` variable contains the property data.
4. **Customize as needed.**

#### **Available Shortcodes**
FacetWP Remote Data provides the following shortcodes to enhance property pages:

1. `[property_google_map]` - Display Google Map with Property Location

This shortcode displays a Google Map with a **pinned property location** and the property's price.

**Example Usage:**
```php
echo do_shortcode(
    sprintf(
        '[property_google_map location="%s" price="%s"]',
        $property['address'],
        sprintf( '$%sK', floor( $property['price'] / 1000 ) )
    )
);
```
**Parameters:**
| Parameter | Description |
|-----------|-------------|
| `location` | The property address to be pinned on the map. |
| `price` | The formatted price of the property displayed on the map marker. |

---

2. `[property_payment_calculator]` - Mortgage Payment Calculator

This shortcode renders a mortgage payment calculator with **predefined values** based on property details.

**Example Usage:**
```php
echo do_shortcode(
    sprintf(
        '[property_payment_calculator price="%d" default_down_payment="%.2f" default_down_payment_percentage="%.2f" default_length_of_mortgage="%d" default_interest_rate="%.2f"]',
        (int) $property_price,
        (float) $default_down_payment,
        (float) $default_down_payment_percentage,
        (int) $default_length_of_mortgage,
        (float) $default_interest_rate
    )
);
```
**Parameters:**
| Parameter | Description |
|-----------|-------------|
| `price` | The total price of the property (integer). |
| `default_down_payment` | The default down payment amount (float). |
| `default_down_payment_percentage` | The down payment percentage (float). |
| `default_length_of_mortgage` | The mortgage length in years (integer). |
| `default_interest_rate` | The interest rate for the mortgage (float). |

---

## **Loading Scripts into Templates**
FacetWP Remote Data provides an extendable way to enqueue JavaScript files for both **listing pages** and **property pages**.

### **How It Works**
The plugin fires **two actions** when loading templates:
- `facet_wp_property_page_load` → Fires when rendering a property page.
- `facet_wp_listing_page_load` → Fires when rendering a listing page.

Use these hooks to enqueue JavaScript files dynamically.

### **How to Enqueue Scripts**
To load custom JavaScript for **property pages**, add:
```php
add_action( 'facet_wp_property_page_load', function( $template_path, $template_vars ) {
    wp_enqueue_script(
        'facet-wp-property-script',
        get_stylesheet_directory_uri() . '/assets/js/facet-wp-property.js',
        ['jquery'],
        filemtime(get_stylesheet_directory() . '/assets/js/facet-wp-property.js'),
        true
    );
}, 10, 2 );
```

To load JavaScript for **listing pages**, use:
```php
add_action( 'facet_wp_listing_page_load', function( $template_path, $template_vars ) {
    wp_enqueue_script(
        'facet-wp-listing-script',
        get_stylesheet_directory_uri() . '/assets/js/facet-wp-listing.js',
        ['jquery'],
        filemtime(get_stylesheet_directory() . '/assets/js/facet-wp-listing.js'),
        true
    );
}, 10, 2 );
```

---

## Important Note
Although this plugin uses custom templates to display results, you **must add a listing** to the page (ideally using a shortcode).

You can use the default listing template that comes with the FacetWP plugin — while this template itself won’t be used (as it gets overridden by the plugin’s custom templates), it is still necessary to ensure that **FacetWP facets are displayed**.

If no listing template is present on the page, **FacetWP will not render any facets**, even if they have been added.

---
