FacetWP

https://facetwp.com/help-center/
Admin
FacetWP is a WordPress plugin that provides advanced filtering and faceted search capabilities for...
Tokens:246,984
Snippets:1,320
Trust Score:9.9
Update:1 year ago
Show doc for...
Tokens:
Raw
### FacetWP Shortcode Output Example

Source: https://facetwp.com/help-center/developers/how-facetwp-works

This example shows the HTML output generated by a FacetWP shortcode. This creates a placeholder element that JavaScript populates with the actual facet interface after the page loads.

```html
<div class="facetwp-facet facetwp-facet-make facetwp-type-checkboxes" data-name="make" data-type="checkboxes"></div>
```

--------------------------------

### FacetWP Filter Example - Basic Usage

Source: https://facetwp.com/help-center/developers/hooks/querying-hooks/facetwp_facet_orderby

A basic PHP example showing the structure of a facet array in FacetWP. This is illustrative and not directly actionable without context, but demonstrates the 'name', 'type', and 'source' properties.

```php
$facet = [
  'name' => 'my_facet',
  'type' => 'checkboxes',
  'source' => 'tax/category',
  // ...
];
```

--------------------------------

### FacetWP Shortcode Example

Source: https://facetwp.com/help-center/developers/hooks/querying-hooks/facetwp_query_args

This is an example of a FacetWP shortcode. It specifies a template named 'publications' and includes a custom attribute 'project' with values 'housing' and 'architecture'. This shortcode can be used to configure FacetWP's display.

```text
[facetwp template="publications" project="housing,architecture"]
```

--------------------------------

### FacetWP URL Examples with Query Strings

Source: https://facetwp.com/help-center/developers/the-facetwp-url

Demonstrates various FacetWP URL constructions based on user interactions with facets. This includes single facet selection, multiple facet selections, pagination, sorting, and multiple choices within a single facet. The examples illustrate how query variables are appended to the base URL.

```URL
https://facetwp.com/demo/recipes-demo/
```

```URL
?_recipe_categories=cake
```

```URL
?_paged=2
```

```URL
?_sortby=title_a_z
```

```URL
?_recipe_categories=cake&_flavors=almond
```

```URL
?_sortby=title&_paged=2
```

```URL
?_flavors=almond%2Clemon
```

--------------------------------

### Check WP-CLI Installation

Source: https://facetwp.com/help-center/using-facetwp-with/wp-cli

Verifies that WP-CLI is correctly installed on your server. The `wp --info` command outputs details about your WP-CLI installation, including its version and the directory it's located in, confirming its readiness for use.

```bash
wp --info
```

--------------------------------

### PHP: Add link to specific builder items (external URL)

Source: https://facetwp.com/help-center/developers/hooks/output-hooks/facetwp_builder_item_value

This example extends the functionality of adding links to builder items by allowing you to link to an external website. It constructs a URL using a base external path and the post ID. Remember to replace 'my-item-name' with the name of your builder item and 'https://my-other-website.com/products/' with your desired external URL.

```php
// replace 'my-item-name' with the name of your builder item

add_filter( 'facetwp_builder_item_value', function( $value, $item ) {

  if ( $item['settings']['name'] == 'my-item-name' ) {

    return '<a href="https://my-other-website.com/products/' . get_the_ID() . '" target="_blank" rel="nofollow noopener">' . $value . '</a>';

  }

  return $value;

}, 10, 2 );
```

--------------------------------

### Basic WP_Query Arguments Setup in PHP

Source: https://facetwp.com/help-center/developers/hooks/querying-hooks/facetwp_query_args

This example demonstrates how to initialize a basic WP_Query argument array in PHP. It sets the post type to 'post' and specifies the number of posts per page. This array can then be further modified by hooks like facetwp_query_args.

```php
$query_args = [
  'post_type' => 'post',
  'posts_per_page' => 15
  // ...
];
```

--------------------------------

### Ruleset Logic Example

Source: https://facetwp.com/help-center/add-on-features-and-extras/conditional-logic

A pseudo-code representation of how rulesets function, demonstrating conditional logic with AND/OR operators and ELSE outcomes. This illustrates the core decision-making process within the add-on.

```pseudo-code
if ( condition#1 == true AND / OR condition#2 == true ) {
  do action#1
  AND
  do action#2
} else {
  do the opposite / do nothing
}
```

--------------------------------

### Style Radio Facet as Tabs (CSS Example)

Source: https://facetwp.com/help-center/faq/is-there-a-button-tab-or-toggle-switch-facet-type

This CSS example demonstrates how to style a Radio facet's choices to appear as tabs. It modifies the default presentation to create a tabbed interface, suitable for single-selection facets where distinct sections or categories need to be highlighted. The styling aims for a clean, tab-like visual separation.

```css
.facet-type-radio .facet-choices label {
    display: inline-block;
    padding: 10px 20px;
    margin-right: 5px;
    border-bottom: 2px solid transparent;
    cursor: pointer;
}

.facet-type-radio .facet-choices input[type="radio"]:checked + label {
    border-bottom-color: #007bff;
    font-weight: bold;
}
```

--------------------------------

### Document Ready Handler with fUtil

Source: https://facetwp.com/help-center/developers/javascript-reference/using-futil

This example demonstrates how to execute code when the document is fully loaded and ready using the fUtil library. It wraps the code in an immediately invoked function expression (IIFE) to ensure proper scope, passing fUtil as the '$' argument.

```javascript
(function($) {
  $(function() {
    console.log('document ready');
  });
})(fUtil);
```

--------------------------------

### FacetWP Indexer Row Data Parameters Example

Source: https://facetwp.com/help-center/developers/hooks/indexing-hooks/facetwp_indexer_row_data

This snippet illustrates the structure of the `$params` array passed to the `facetwp_indexer_row_data` hook. It includes default values for indexing and facet-specific configuration, which can be useful for understanding how to programmatically influence the indexing process.

```php
$params = [
  'defaults' => [
    'post_id'               => 123,
    'facet_name'            => 'facet_1',
    'facet_source'          => 'tax/category',
    'facet_value'           => '',
    'facet_display_value'   => '',
    'term_id'               => 0,
    'parent_id'             => 0,
    'depth'                 => 0,
    'variation_id'          => 0,
  ],
  'facet' => [
    'label'     => 'Facet 1',
    'name'      => 'facet_1',
    'type'      => 'checkboxes',
    'source'    => 'tax/category',
    // ...
  ]
];
```

--------------------------------

### Example of Marker Content HTML/PHP

Source: https://facetwp.com/help-center/facets/facet-types/map-legacy

This snippet demonstrates how to structure HTML and PHP code to define the content displayed in an info window when a map marker is selected. It assumes the availability of variables like 'post_title', 'post_id', and 'location_address'.

```html+php
<div>
    <h3><?php echo $post_title; ?></h3>
    <p><strong>Address:</strong> <?php echo $location_address; ?></p>
    <a href="<?php echo get_permalink($post_id); ?>">View details</a>
</div>
```

--------------------------------

### FacetWP Loaded Event Example

Source: https://facetwp.com/help-center/changelog

This code demonstrates how to use the `facetwp-loaded` event in JavaScript. This event fires once FacetWP has finished loading all its facets and data, providing a reliable point to execute custom scripts that depend on the initial state of FacetWP.

```javascript
document.addEventListener('facetwp-loaded', function() {
    console.log('FacetWP has loaded completely!');
    // Initialize custom scripts or perform actions after FacetWP is ready
});
```

--------------------------------

### Using Dynamic Tags in HTML (Template Example)

Source: https://facetwp.com/help-center/listing-templates/listing-builder

Demonstrates how to use dynamic tags within HTML builder items to display post data, specifically custom field values. The example shows wrapping a 'photo_url' custom field value within an anchor tag.

```html
<a href="{{ photo-url }}">{{ photo-url }}</a>
```

--------------------------------

### Use FacetWP Shortcode in PHP

Source: https://facetwp.com/help-center/listing-templates/listing-builder

This example shows how to display a FacetWP shortcode within PHP templates using the `do_shortcode()` function. This allows for the dynamic insertion of FacetWP listings with specified attributes like 'template' and 'project'.

```php
echo do_shortcode('[facetwp template="publications" project="housing"]');
```

--------------------------------

### Change Directory

Source: https://facetwp.com/help-center/using-facetwp-with/wp-cli

The `cd` command allows you to navigate between directories in your server's file system. This is essential for moving into your WordPress installation directory, where WP-CLI commands must be executed.

```bash
cd public_html
```

```bash
cd path/to/your/wp/folder
```

```bash
cd ..
```

--------------------------------

### Display FacetWP Facet using PHP and Shortcode

Source: https://facetwp.com/help-center/listing-templates/using-wordpress-blocks

Examples of how to display a FacetWP facet in PHP. The first method uses the FacetWP function directly, while the second uses the WordPress do_shortcode function. Both require the FacetWP plugin to be active and a facet named 'my_facet_name' to be configured.

```php
echo facetwp_display( 'facet', 'my_facet_name' );

// Or

echo do_shortcode('[facetwp facet="my_facet_name"]');
```

--------------------------------

### Style the User Selections Facet (CSS)

Source: https://facetwp.com/help-center/facets/facet-types/user-selections

Provides CSS to style the User Selections facet, including margins, padding, borders, and colors for individual selections. This example demonstrates how to style each facet selection with a distinct appearance.

```css
add_action( 'wp_footer', function() {

  ?>

  <style>
 
      .facetwp-selections ul {

          margin: 20px 0;

      }
 
      .facetwp-selections li {

          display: inline-block;

          margin: 0 6px 6px 0;

          padding: 8px 10px;

          list-style-type: none;

          border: 1px solid #ddd;

          border-radius: 3px;

      }
 
      .facetwp-selections .facetwp-selection-value {

          color: #6233ca;

      }
 
      .facetwp-selections .facetwp-selection-value:hover {

          text-decoration: underline;

      }
 
      .facetwp-selections .facetwp-selection-label + .facetwp-selection-value {

          margin-left: 4px;

      }
 
      .facetwp-selections .facetwp-selection-value:last-child {

          margin-right: 0;

      }
 
  </style>

  <?php

}, 100 );
```

--------------------------------

### Style Highlighted Search Terms with CSS (XML/HTML)

Source: https://facetwp.com/help-center/using-facetwp-with/searchwp

This example shows the HTML structure for highlighted search terms generated by SearchWP, which uses a `<mark>` element with the class 'searchwp-highlight'. It is followed by a CSS rule to customize the background color of these highlighted terms.

```xml
<mark class="searchwp-highlight">search terms</mark>
```

```php-template
add_action( 'facetwp_scripts', function() {

  ?>

  <style>

    .searchwp-highlight {

      background: #ffa07a; /* light orange-red */

    }

  </style>

  <?php

}, 100 );
```

--------------------------------

### Enabling FacetWP Indexing for Out-of-Stock Products

Source: https://facetwp.com/help-center/index

This example illustrates how to enable the 'Index out-of-stock products' setting in FacetWP via its WooCommerce settings. This is crucial for ensuring that products with zero stock are included in facet results.

```php
add_filter( 'facetwp_settings_facetwp_woocommerce', function( $settings ) {
    $settings['index_out_of_stock_products'] = true;
    return $settings;
} );
```

--------------------------------

### Use FacetWP with WooCommerce [products] Shortcode

Source: https://facetwp.com/help-center/using-facetwp-with/woocommerce/using-facetwp-with-the-woocommerce-products-shortcode

This is an example of how to use the WooCommerce [products] shortcode with FacetWP enabled. By adding the `facetwp` attribute to the shortcode, you activate the integration provided by the previously included PHP code. This allows FacetWP to manage the product display.

```shortcode
[products facetwp]
```

--------------------------------

### Example HTML usage of dynamic tags

Source: https://facetwp.com/help-center/developers/hooks/output-hooks/facetwp_builder_dynamic_tag_value

Demonstrates how to use custom and built-in dynamic tags within an HTML element in FacetWP's Listing Builder. It shows how to apply a post type and taxonomy terms as CSS classes to a `<div>` element.

```xml
<div class="{{ post:type }} {{ resource_type }}"></div>

```

--------------------------------

### Define FacetWP Data Sources

Source: https://facetwp.com/help-center/developers/hooks/advanced-hooks/facetwp_facet_sources

This code snippet demonstrates how to define custom data sources for FacetWP facets. It includes examples for posts, taxonomies, and custom fields, showing how to structure the `$sources` array with labels and choices.

```PHP
add_filter( 'facetwp_facet_sources', function( $sources ) {

  $sources['custom_fields']['choices']['cf/my_data'] = 'my_data';

  return $sources;

});
```

--------------------------------

### PHP: Example facetwp_render_output $output array structure

Source: https://facetwp.com/help-center/developers/hooks/output-hooks/facetwp_render_output

This code snippet demonstrates the structure of the `$output` array that can be modified using the `facetwp_render_output` filter. It shows arrays for facets, template HTML, settings, and pager/sort information. This is useful for understanding what data is available for manipulation.

```php
$output = [

  'facets' => [

    'the_facet_name' => 'HTML output',

    'another_facet' => 'HTML output',

  ],

  'template' => 'HTML string',

  'settings' => [

    'the_facet_name' => [

      'setting1' => 'value'

    ]

  ],

  'pager' => 'HTML output',

  'sort' => 'HTML output',

];
```

--------------------------------

### PHP: Modify facetwp_render_output Slider facet start setting

Source: https://facetwp.com/help-center/developers/hooks/output-hooks/facetwp_render_output

This example demonstrates how to use the `facetwp_render_output` filter to modify the 'start' setting of a Slider facet named 'price'. It sets the initial range for the slider to display items between 500 and 1000. This is useful for pre-filtering results on initial page load.

```php
add_filter( 'facetwp_render_output', function( $output, $params ) {

  $output['settings']['price']['start'] = [ 500, 1000 ];

  return $output;

}, 10, 2 );
```

--------------------------------

### Enable Strict Query Detection by Default

Source: https://facetwp.com/help-center/changelog

For new installations, 'Strict query detection' is now enabled by default to ensure more accurate filtering and prevent potential issues with complex query setups.

```php
// This is a default setting change. To enable it manually:
// FacetWP()->settings->set( 'strict_query_detection', 1 );
// FacetWP()->settings->save();
```

--------------------------------

### Get Active Facet Info in JavaScript (FacetWP)

Source: https://facetwp.com/help-center/developers/javascript-reference/js-objects-and-functions

This JavaScript example demonstrates how to retrieve the name and type of the currently active facet within the `facetwp-refresh` event. This information is available only during the refresh process and can be used for conditional logic.

```javascript
add_action( 'facetwp_scripts', function() {
  ?>
    <script>
      document.addEventListener('facetwp-refresh', function() {
        if (null !== FWP.active_facet) {
          let facet = FWP.active_facet;
          let facet_name = facet.attr('data-name');
          let facet_type = facet.attr('data-type');
          console.log(facet_name);
          console.log(facet_type);
        }
      });
    </script>
  <?php
} );
```

--------------------------------

### Facet Settings and Selected Values Structure (PHP)

Source: https://facetwp.com/help-center/developers/hooks/querying-hooks/facetwp_search_query_args

This example displays the structure of the `$params` array passed to the `facetwp_search_query_args` hook. It contains details about the facet's configuration (e.g., name, label, type, search engine) and the currently selected values or search keyword.

```php
$params = [
  'facet' => [
    'name' => 'my_search_facet',
    'label' => 'my search facet',
    'type' => 'search',
    'search_engine' => '', // empty for "WP Default"
    'placeholder' => 'Type keywords',
    'auto_refresh' => 'yes',
    'operator' => 'or',
    'selected_values' => 'used keyword',
    'enable_relevance' => 'yes',
  ],
  'selected_values' => 'used keyword'
];
```

--------------------------------

### Modify FacetWP Map Marker Content with JavaScript

Source: https://facetwp.com/help-center/facets/facet-types/map/advanced-map-customizations/customize-advanced-markers

This JavaScript code snippet demonstrates how to hook into the 'facetwp_map/marker/content' filter to customize the content of map markers. It provides examples for using PNG images, SVG images (both URLs and inline SVG), and arbitrary HTML for markers. Ensure you have FacetWP and its relevant add-ons installed.

```javascript
add_action( 'facetwp_scripts', function() {
  ?>
  <script>
    document.addEventListener('facetwp-refresh', function() {
      if ('undefined' !== typeof FWP && 'undefined' !== typeof FWP.hooks) {
        FWP.hooks.addFilter('facetwp_map/marker/content', function( content, args, PinElement ) {
          // Example 1: Use a PNG image URL
          content = document.createElement('img');
          content.src = 'https://developers.google.com/maps/documentation/javascript/examples/full/images/beachflag.png';
          content.className = "my-png-marker"; // set a custom class

          // Example 2: Use an SVG image URL
          content = document.createElement('img');
          content.src = 'https://yourdomain.com/path/to/your/image.svg';
          content.className = "my-svg-marker"; // set a custom class

          // Example 3: Use an inline SVG
          const markerSvgString = '<svg xmlns="http://www.w3.org/2000/svg" width="45" viewBox="0 0 384 512" class="my-svg-marker"><path d="M215.7 499.2C267 435 384 279.4 384 192C384 86 298 0 192 0S0 86 0 192c0 87.4 117 243 168.3 307.2c12.3 15.3 35.1 15.3 47.4 0zM192 128a64 64 0 1 1 0 128 64 64 0 1 1 0-128z" /></svg>';
          const parser = new DOMParser();
          const markerSvg = parser.parseFromString(markerSvgString, 'image/svg+xml').documentElement;
          content = markerSvg;

          // Example 4: Use arbitrary HTML
          const priceTag = document.createElement("div");
          priceTag.className = "price-tag-marker"; // set a custom class
          priceTag.textContent = "$2.5M"; // set a fixed text
          content = priceTag;

          return content;
        });
      }
    });
  </script>
  <?php
}, 100 );
```

--------------------------------

### Re-index FacetWP for All Sub-sites in a Multi-site Install

Source: https://facetwp.com/help-center/using-facetwp-with/wp-cli

This command iterates through all sub-site URLs in a WordPress multi-site installation and runs the FacetWP index command for each. It uses WP-CLI's site list command and xargs for efficient execution. Ensure WP-CLI is installed and configured for multi-site.

```bash
wp site list --field=url | xargs -n1 -I % wp --url=% facetwp index
```

--------------------------------

### Custom Query Arguments with Dev Mode (PHP)

Source: https://facetwp.com/help-center/listing-templates/listing-builder

This example illustrates how to define custom query arguments for a FacetWP listing using PHP in Dev mode. This allows for fine-grained control over which posts are fetched, their order, and filtering conditions, suitable for developers needing custom query logic.

```php
$query_args = [
    'post_type' => ['post', 'page'],
    'posts_per_page' => 20,
    'orderby' => 'date',
    'order' => 'DESC',
    'meta_query' => [
        [
            'key' => 'custom_field_name',
            'value' => 'some_value',
            'compare' => '='
        ]
    ]
];

// This would typically be part of the Listing Builder's Query tab in Dev mode.
```

--------------------------------

### Load Google Maps API with Places Library (JavaScript)

Source: https://facetwp.com/help-center/facets/facet-types/map/advanced-map-customizations

This JavaScript snippet illustrates how to load the Google Maps JavaScript API, specifically including the Places library, which is required for the Proximity facet. This is typically used when you are managing the API loading yourself and need to ensure all necessary components are included. The example includes a placeholder for your API key.

```javascript
<script src="https://maps.googleapis.com/maps/api/js?libraries=places&amp;key=AIzaSyBFbgc6KDTw2tlcFO3fYHx91fFHtaUDpYs&amp;v=quarterly"></script>
```

--------------------------------

### Customize Date Placeholder Texts in PHP

Source: https://facetwp.com/help-center/facets/facet-types/date-range

This PHP code snippet demonstrates how to modify the placeholder texts for date fields within FacetWP. It uses the `gettext` filter to translate default labels like 'Date', 'Start date', and 'End date' to include the expected date format (e.g., 'Date (dd-mm-yyyy)' or 'Date (mm-dd-yyyy)'). This helps guide users on the correct input format based on the `monthfirst` setting.

```php
add_filter( 'gettext', function( $translated_text, $text, $domain ) {

  if ( 'fwp-front' == $domain ) {

    // Use with monthfirst = false
    if ( 'Date' == $translated_text ) {
      $translated_text = 'Date (dd-mm-yyyy)';
    } elseif ( 'Start date' == $translated_text ) {
      $translated_text = 'Start date (dd-mm-yyyy)';
    } elseif ( 'End date' == $translated_text ) {
      $translated_text = 'End date (dd-mm-yyyy)';
    }

    // Use with monthfirst = true
//  if ( 'Date' == $translated_text ) {
//    $translated_text = 'Date (mm-dd-yyyy)';
//  } elseif ( 'Start date' == $translated_text ) {
//    $translated_text = 'Start date (mm-dd-yyyy)';
//  } elseif ( 'End date' == $translated_text ) {
//    $translated_text = 'End date (mm-dd-yyyy)';
//  }

  }

  return $translated_text;
}, 10, 3 );
```

--------------------------------

### Fix Plugin Install Notice Wrong Add-on Name

Source: https://facetwp.com/help-center/changelog

Corrects an error in the admin notice for plugin installation, ensuring the correct add-on name is displayed (e.g., 'Multilingual' instead of 'WPML').

```php
// This is a text correction within FacetWP's admin notification system.
```

--------------------------------

### Style Info Window Content with Custom CSS Class (PHP/HTML)

Source: https://facetwp.com/help-center/facets/facet-types/map

This example shows how to wrap custom info window content in a div with a specific class for CSS styling. It combines PHP for dynamic content generation (post title and excerpt) with HTML structure. This approach allows for targeted styling of the info window's elements.

```php
<div class="infowindow">
  <h3>
    <a href="<?php the_permalink(); ?>" title="<?php the_title_attribute(); ?>">
      <?php the_title(); ?>
    </a>
  </h3>
  <?php the_excerpt(); ?>
</div>
```

--------------------------------

### Use Font Awesome Webfont Icons for FacetWP Ratings

Source: https://facetwp.com/help-center/facets/facet-types/rating

This example illustrates how to leverage Font Awesome webfont icons for FacetWP's star rating functionality. It assumes Font Awesome v6 webfonts and CSS are already installed and operational. The code sets a "solid face-smile" icon as the base and a "regular face-smile" icon for the ghost state. This approach replaces custom SVG or Unicode icons with readily available icon font characters.

```php
// This is a conceptual example assuming FontAwesome webfonts are loaded.
// The actual filter hook and logic would be similar to the SVG example,
// but instead of SVG markup, it would return Font Awesome classes or codes.

// Example placeholder (actual implementation would involve returning FontAwesome markup or classes):
add_filter( 'facetwp_ratings_icon', function( $icon, $is_disabled, $facet ) {
    if ( $facet['name'] === 'my_font_awesome_facet' ) {
        if ( $is_disabled ) {
            // Example for a ghost icon using Font Awesome (e.g., 'far fa-smile')
            // In a real scenario, you might return a string like '<i class="far fa-smile"></i>'
            $icon = '<i class="fas fa-face-smile-ghost"></i>'; // Placeholder, actual FontAwesome class needed
        } else {
            // Example for a solid icon using Font Awesome (e.g., 'fas fa-smile')
            // In a real scenario, you might return a string like '<i class="fas fa-smile"></i>'
            $icon = '<i class="fas fa-face-smile"></i>'; // Placeholder, actual FontAwesome class needed
        }
    }
    return $icon;
}, 10, 3 );

// Note: Ensure Font Awesome CSS and fonts are correctly enqueued in your theme.
```

--------------------------------

### Link Entire Post Block with HTML in FacetWP

Source: https://facetwp.com/help-center/listing-templates/listing-builder

This HTML snippet demonstrates how to create a clickable block for each post in a listing. It uses FacetWP's dynamic tags like `{{ post:url }}` and custom dynamic tags for featured images and excerpts.

```html
<a href="{{ post:url }}">

  <span class="post-title">{{ post:title }}</span>

  <span class="featured-image">{{ my-featured-image-item }}</span>

  <span class="excerpt">{{ my-excerpt-item }}</span>

</a>
```

--------------------------------

### FacetWP Date Formatting Examples

Source: https://facetwp.com/help-center/facets/facet-types/date-range

These examples demonstrate how to use PHP datetime formats in the 'Display format' setting for the Date Range facet to control how dates appear in the input fields.

```php
// Day (2 digits)
$format = 'd'; // Example output: 18

// Month number (2 digits)
$format = 'm'; // Example output: 01

// Year (full)
$format = 'Y'; // Example output: 2021
```

```php
// Specific examples
$format1 = 'Y-m-d'; // Example output: 2021-01-18
$format2 = 'F j, Y'; // Example output: January 18, 2021
$format3 = 'j M Y'; // Example output: 18 Jan 2021
```

--------------------------------

### Import FacetWP Facets and Listing Templates

Source: https://facetwp.com/help-center/add-on-features-and-extras/back-up-or-move-facets-and-listing-templates

This section outlines the steps to import previously exported facets and listing templates into FacetWP. Users need to paste the backed-up code into the provided field and can optionally choose to overwrite existing items. After importing, the new or updated facets and templates will be available in the overview.

```PHP
Settings > FacetWP > Settings
```

--------------------------------

### PHP: Change date format from custom field

Source: https://facetwp.com/help-center/developers/hooks/output-hooks/facetwp_builder_item_value

This example demonstrates how to reformat a date string obtained from a custom field. It converts the input date string into a specific 'd-m-Y' format using PHP's `date_create` and `date_format` functions.

```php
add_filter( 'facetwp_builder_item_value', function( $value, $item ) {

  if ( 'date-field' == $item['settings']['name'] ) {

    $value = date_create( $value );

    $value = date_format( $value, "d-m-Y" );

  }

  return $value;

}, 10, 2 );
```

--------------------------------

### Define Post Query Arguments with PHP

Source: https://facetwp.com/help-center/listing-templates/listing-builder/using-the-listing-builder-in-dev-mode

This PHP code defines query arguments for fetching posts. It specifies the post type, status, ordering criteria (alphabetically by title), and the number of posts per page. This is used in FacetWP's 'Query Arguments' box in Dev mode.

```php
<?php

return [

  'post_type' => [

    'post'

  ],

  'post_status' => [

    'publish'

  ],

  'orderby' => [

    'title' => 'ASC'

  ],

  'posts_per_page' => 15

];

?>
```

--------------------------------

### FacetWP Advanced Hooks Reference

Source: https://facetwp.com/help-center/add-on-features-and-extras/back-up-or-move-facets-and-listing-templates

Advanced hooks for internationalization, script and asset management, facet type and source definitions, and general facet handling within FacetWP.

```php
// Hook for internationalization strings
add_filter( 'facetwp_i18n', function( $strings ) {
    $strings['my_custom_text'] = 'My Custom Text';
    return $strings;
} );

// Hook to modify FacetWP scripts
add_action( 'facetwp_scripts', function() {
    // Enqueue custom scripts or modify existing ones
    wp_enqueue_script( 'my-custom-script', get_template_directory_uri() . '/js/my-custom-script.js' );
} );

// Hook to modify FacetWP assets
add_filter( 'facetwp_assets', function( $assets ) {
    // Add or modify assets
    $assets['my-custom-asset'] = get_template_directory_uri() . '/css/my-custom-asset.css';
    return $assets;
} );

// Hook to modify asset HTML
add_filter( 'facetwp_asset_html', function( $html, $asset_name ) {
    // Modify HTML for specific assets
    if ( $asset_name === 'my-custom-asset' ) {
        $html = '<link rel="stylesheet" href="' . esc_url( $asset_name ) . '">';
    }
    return $html;
}, 10, 2 );

// Hook to register custom facet types
add_filter( 'facetwp_facet_types', function( $facet_types ) {
    // Add a new facet type
    $facet_types['my_custom_facet'] = [
        'label' => __( 'My Custom Facet', 'your-text-domain' ),
        'render_callback' => 'my_custom_facet_render_callback',
        'args_callback' => 'my_custom_facet_args_callback',
    ];
    return $facet_types;
} );

// Hook to register custom facet sources
add_filter( 'facetwp_facet_sources', function( $facet_sources ) {
    // Add a new facet source
    $facet_sources['my_custom_source'] = [
        'label' => __( 'My Custom Source', 'your-text-domain' ),
        'query_callback' => 'my_custom_source_query_callback',
    ];
    return $facet_sources;
} );

// Hook to modify all facets
add_filter( 'facetwp_facets', function( $facets ) {
    // Modify existing facets or add new ones
    return $facets;
} );
```

--------------------------------

### Limit Words in Listing Builder Item with PHP

Source: https://facetwp.com/help-center/developers/hooks/output-hooks/facetwp_builder_item_value

This example demonstrates how to limit the number of words in a specific Listing Builder item using the `wp_trim_words` function. It appends a custom string after the trimmed text. This is useful for keeping descriptions concise.

```php
add_filter( 'facetwp_builder_item_value', function( $value, $item ) {
  if ( 'my-excerpt' == $item['settings']['name'] ) {
    $length = 8; // set the number of words
    $more =  ' (&hellip;)'; // append an ellipsis between parentheses (…) after the last word
    $value = wp_trim_words( $value, $length, $more );
  } 
  return $value;
}, 10, 2 );
```

--------------------------------

### Display a Template using Shortcode and PHP

Source: https://facetwp.com/help-center/developers/shortcodes-reference

This snippet demonstrates how to display a FacetWP Listing Builder template using either a shortcode or PHP. The shortcode is '[facetwp template="the_template_name"]' and the PHP equivalent is 'echo facetwp_display('template','the_template_name');'. This allows for the integration of custom listing templates into your site.

```shortcode
[facetwp template="the_template_name"]
```

```php
echo facetwp_display('template','the_template_name');
```

--------------------------------

### Example of Script Tag with Attribute (XML)

Source: https://facetwp.com/help-center/using-facetwp-with/cookiebot

This shows the resulting HTML structure of a FacetWP script tag after the PHP filter has been applied, including the added `data-cookieconsent="ignore"` attribute. This is an example of how a script tag will appear when processed by the filter.

```xml
<script data-cookieconsent="ignore" src="https://domain.com/wp-content/plugins/facetwp/assets/js/dist/front.min.js?ver=x.x.x"></script>
```

--------------------------------

### Display Future Event Occurrences from Loop

Source: https://facetwp.com/help-center/using-facetwp-with/the-events-calendar-pro

This PHP code iterates through posts from a `WP_Query` and displays future occurrences of events. It retrieves occurrence IDs, formats start and end dates, and checks if the occurrence start date is after the current time before echoing the event details.

```php
if ( $events_query->have_posts() ) : while ( $events_query->have_posts() ) : $events_query->the_post();

 

  // Get all occurrence IDs for a "parent" event. 

  // This includes the parent event itself, which is also an occurrence.

  $occurrence_ids = tribe_events()->where( 'ID', get_the_ID() )->pluck( 'ID' );

 

  foreach ( $occurrence_ids as $occurrence_id ) {

 

    $start_date = get_post_meta( $occurrence_id, '_EventStartDate', true );

    $start_date_formatted = tribe_get_start_date( $occurrence_id, false, 'F j, Y - H:i' );

    $end_date_formatted = tribe_get_end_date( $occurrence_id, false,'F j, Y - H:i' );

    $title = get_post( $occurrence_id )->post_title;

    $permalink = get_the_permalink( $occurrence_id );

 

    // Only show occurrence if its start date is after "now":

    if ( $start_date > date( 'Y-m-d H:i:s' ) ) {

      echo '<h2><a href="' . $permalink . '">' . $title . '</a></h2>';

      echo '<p>From: ' . $start_date_formatted . ' to '. $end_date_formatted . '</p>';

    }

  }

 

endwhile;

else :

  _e( 'Sorry, no posts matched your criteria.' );

endif;

wp_reset_postdata();
```

--------------------------------

### View FacetWP Debug SQL (JavaScript)

Source: https://facetwp.com/help-center/troubleshooting/using-the-right-query

Retrieve and inspect the SQL query generated by FacetWP using JavaScript in the browser's console. This helps verify if FacetWP is correctly detecting the post type, order, and posts per page.

```javascript
FWP.settings.debug.sql
```

--------------------------------

### Starts With Match for Autocomplete Results (PHP)

Source: https://facetwp.com/help-center/facets/facet-types/autocomplete

This PHP snippet adjusts the Autocomplete facet's SQL query to return results that start with the entered value. Place this in your theme's functions.php and substitute 'my_autocomplete' with your facet's actual name. This implementation maintains the partial match but restricts it to the beginning of the string.

```php
add_filter( 'facetwp_wpdb_sql', function( $sql, $facet ) {
  if ( 'my_autocomplete' == $facet['name'] ) { // Replace 'my_autocomplete' with the name of your Autocomplete facet
    global $wpdb;
    $sql = $wpdb->remove_placeholder_escape( $sql );
    // Modify the LIKE clause to only match the beginning of the string
    // This example assumes the default LIKE clause includes '%value%'
    // A more robust solution might involve parsing the $sql string
    $sql = preg_replace("/ LIKE '(.*)%'", " LIKE '$1%'", $sql);
  }
  return $sql;
}, 10, 2 );
```

--------------------------------

### Style Checkbox Facet as Toggles/Switches (SVG and CSS Example)

Source: https://facetwp.com/help-center/faq/is-there-a-button-tab-or-toggle-switch-facet-type

This example utilizes SVG icons and CSS to transform Checkbox facet choices into toggle switches. It's designed for multiple-selection facets, allowing users to switch options on or off visually. The approach replaces standard checkboxes with custom switch elements for a modern UI.

```css
.facet-type-checkbox .facet-choices label {
    position: relative;
    display: inline-block;
    width: 60px;
    height: 34px;
    margin: 10px 5px;
}

.facet-type-checkbox .facet-choices label input[type="checkbox"] {
    opacity: 0;
    width: 0;
    height: 0;
}

.slider {
    position: absolute;
    cursor: pointer;
    top: 0;
    left: 0;
    right: 0;
    bottom: 0;
    background-color: #ccc;
    transition: .4s;
    border-radius: 34px;
}

.slider:before {
    position: absolute;
    content: "";
    height: 26px;
    width: 26px;
    left: 4px;
    bottom: 4px;
    background-color: white;
    transition: .4s;
    border-radius: 50%;
}

input[type="checkbox"]:checked + .slider {
    background-color: #2196F3;
}

input[type="checkbox"]:checked + .slider:before {
    transform: translateX(26px);
}
```

--------------------------------

### fUtil Library Overview and Methods

Source: https://facetwp.com/help-center/developers/javascript-reference/using-futil

This section details the fUtil JavaScript library, a lightweight helper for FacetWP. It covers common DOM manipulation, event handling, and AJAX methods, serving as a modern JavaScript alternative to jQuery. fUtil is useful for websites that do not require or load jQuery.

```javascript
document.ready handler
$(function() { ... })

// select the document
$()

// get an element
$(selector)
// or
fUtil(selector)

// create a new fUtil instance
$(selector).clone()

// get the number of matching elements (returns int)
$(selector).len()

// add CSS class
$(selector).addClass(val)

// remove CSS class
$(selector).removeClass(val)

// has CSS class
$(selector).hasClass(val)

// toggle CSS class
$(selector).toggleClass(val)

// check for a match (returns bool)
$(selector).is(selector)

// check for a match
$(selector).find(selector)

// get first matching element
$(selector).first()

// get last matching element
$(selector).last()

// get previous matching element
$(selector).prev(selector)

// get next matching element
$(selector).next(selector)

// prepends selected element(s) with a value
$(selector).prepend(val)

// appends selected element(s) with a value
$(selector).append(val)

// get selected element(s) parents
$(selector).parents(selector)

// get selected element(s) closest parents
$(selector).closest(selector)

// remove current element(s)
$(selector).remove()

// adds event listener
$(selector).on('action', callback)

// removes event listener
$(selector).off('action', callback)

// trigger an event
$(selector).trigger('action', callback, extraData)

// set an attribute
$(selector).attr(name, val)

// set data values
$(selector).data(key, val)

// set HTML
$(selector).html(val)

// set text value
$(selector).text(val)

// set input value
$(selector).val(val)

// get all matching DOM nodes (returns array of DOM nodes)
$(selector).nodes

// get first matching DOM node (returns DOM node)
$(selector).nodes[0]

// make an ajax POST
$.post(url, data, settings)

// check if a value or variable exists
$.isset(var)

// loop through an iterable
$.each(items, callback)

Note: For `.each()`, jQuery uses `(key, val)`, but fUtil and native JS both use `(val, key)`. This ordering difference means that you may need to tweak any custom jQuery loops.
```

--------------------------------

### FacetWP Advanced Hooks Reference

Source: https://facetwp.com/help-center/developers/hooks/advanced-hooks/upt_admin_settings_capability

This section covers advanced hooks in FacetWP for internationalization, script and asset management, facet type and source definitions, and general facet handling.

```PHP
facetwp_i18n
facetwp_scripts
facetwp_assets
facetwp_asset_html
facetwp_facet_types
facetwp_facet_sources
facetwp_facets
```

--------------------------------

### Fix Missing Post in FacetWP Query with WP Archive Example (PHP)

Source: https://facetwp.com/help-center/index

This PHP code provides an example of the correct usage of `the_post()` within the WordPress loop for WP archive pages. It illustrates that `the_post()` should be called only once and must be placed within the `while` condition of the loop to ensure all posts are correctly processed and displayed in FacetWP listings.

```php
<?php
/**
 * Example of correct the_post() usage in a WP archive loop.
 * Ensures a single post is not missed in FacetWP listings.
 */
if ( have_posts() ) {
    while ( have_posts() ) {
        the_post();
        // Your post display logic here
    }
}
?>
```

--------------------------------

### Integrate FacetWP into WordPress Block Themes (.html) (HTML/Shortcode)

Source: https://facetwp.com/help-center/listing-templates/using-wordpress-blocks

This example shows how to integrate FacetWP facets into a WordPress block theme's .html template file, specifically for a search results page. It involves adding shortcodes for facets and configuring a Query Loop block to use FacetWP. The code represents the structure of a `search.html` file.

```html
<!-- wp:template-part {"slug":"header","tagName":"header"} /-->

 
<!-- wp:group {"tagName":"main","style":{"spacing":{"margin":{"top":"var:preset|spacing|70","bottom":"var:preset|spacing|70"}}},"layout":{"type":"constrained"}} -->

<main class="wp-block-group" style="margin-top:var(--wp--preset--spacing--70);margin-bottom:var(--wp--preset--spacing--70)">

  <!-- wp:query-title {"type":"search","align":"wide","style":{"spacing":{"margin":{"bottom":"var:preset|spacing|50"}}}} /-->

 
 
  <!-- Start pasted Shortcode blocks with facets, and Query Loop block -->

 
  <!-- wp:shortcode -->  [facetwp facet="search"]

  <!-- /wp:shortcode -->

 
  <!-- wp:shortcode -->  [facetwp facet="pager_numbers"]

  <!-- /wp:shortcode -->

 
  <!-- wp:query {"queryId":1,"query":{"perPage":5,"pages":0,"offset":0,"postType":"post","order":"desc","orderBy":"date","author":"","search":"","exclude":[],"sticky":"","inherit":true},"enableFacetWP":true} -->

  <div class="wp-block-query"><!-- wp:post-template -->

    <!-- wp:post-title /-->

 
    <!-- wp:post-excerpt /-->
    <!-- /wp:post-template -->

 
    <!-- wp:query-no-results -->

    <!-- wp:paragraph {"placeholder":"Add text or blocks that will display when a query returns no results."} -->

    <p>No results found.</p>

    <!-- /wp:paragraph -->
    <!-- /wp:query-no-results --></div>

  <!-- /wp:query -->

 
  <!-- End pasted blocks -->

  

</main><!-- /wp:group -->

 
<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->
 

```

--------------------------------

### Add User Selections to Flyout (HTML)

Source: https://facetwp.com/help-center/add-on-features-and-extras/mobile-flyout

This HTML example demonstrates integrating the user selections shortcode within the flyout template. By placing `[facetwp selections="true"]` inside a `facetwp-flyout-tpl` div, user selections will appear above the facets in the flyout.

```html
<!--Add this HTML to your page-->
<div class="facetwp-flyout-tpl">
  [facetwp selections="true"]
  {content}
</div>
```

--------------------------------

### Remove an Existing FacetWP Asset

Source: https://facetwp.com/help-center/developers/hooks/advanced-hooks/facetwp_assets

This code example shows how to remove a specific FacetWP JavaScript asset, such as 'event-manager.js', from being loaded. It utilizes the `facetwp_assets` filter to unset the desired asset key.

```php
add_filter( 'facetwp_assets', function( $assets ) {

  unset( $assets['event-manager.js'] );

  return $assets;

});
```

--------------------------------

### Custom Display Output with Dev Mode (PHP)

Source: https://facetwp.com/help-center/listing-templates/listing-builder

This snippet shows how to create a custom HTML structure for displaying posts within a FacetWP listing using PHP in Dev mode. This provides complete control over the presentation of each item in the listing, going beyond the visual builder's options.

```php
<?php foreach ( FWP()->facet->get_loop()->posts as $post ) : setup_postdata( $post ); ?>
    <article id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
        <h2><a href="<?php the_permalink(); ?>" rel="bookmark"><?php the_title(); ?></a></h2>
        <div><?php the_excerpt(); ?></div>
    </article>
<?php endforeach; wp_reset_postdata(); ?>
```

--------------------------------

### Fix Better Detection/Handling of pre_filtered_post_ids Hooks

Source: https://facetwp.com/help-center/changelog

Enhances FacetWP's ability to detect and correctly handle situations where `facetwp_pre_filtered_post_ids` or `facetwp_filtered_post_ids` hooks are used, improving compatibility with advanced filtering setups.

```php
// This involves checking for the presence and values of these hooks during query execution.
```

--------------------------------

### Remove Specific FacetWP Asset

Source: https://facetwp.com/help-center/developers/hooks/advanced-hooks/facetwp_assets

This example shows how to remove a specific asset, such as 'event-manager.js', from being loaded by FacetWP. It utilizes the `facetwp_assets` filter to unset a particular key from the asset array.

```php
add_filter( 'facetwp_assets', function( $assets ) {

  unset( $assets['event-manager.js'] );

  return $assets;

});
```

--------------------------------

### FacetWP Advanced Hooks

Source: https://facetwp.com/help-center/add-on-features-and-extras

This section covers advanced hooks for internationalization, script and asset management, and facet/template definitions. These are useful for deeper customization and integration.

```PHP
add_filter( 'facetwp_i18n', function( $strings ) {
    // Add or modify translation strings
    $strings['my_custom_text'] = 'My Custom Text';
    return $strings;
} );

add_filter( 'facetwp_scripts', function() {
    // Enqueue custom scripts
    wp_enqueue_script( 'my-custom-script', get_template_directory_uri() . '/js/my-custom-script.js' );
} );

add_filter( 'facetwp_facet_types', function( $facet_types ) {
    // Register a new facet type
    $facet_types['my_custom_facet'] = 'My_Custom_Facet';
    return $facet_types;
} );
```
Tokens:
Raw