Create, register, and reuse FacetWP plugin facets/templates using PHP, and keep them in your source code repository. To read more about registering FacetWP facets and templates via PHP, go here: facets documentation and templates documentation.
- Minimum Requirements
- Installation
- Adding/Removing FacetWP Facets and Templates with the Builder
- Composing Custom/3rd Party Addon Facets
- Hooks
- Examples
- Credits
- License
- PHP v8.1
- WordPress v6.1
- FacetWP v4.0
composer require itinerisltd/facetwp-builderIf your project isn't using composer, you can require the autoload.php file.
| Facets | Templates |
|---|---|
| Autocomplete | Add a template |
| Checkbox | |
| Date Range | |
| Dropdown | |
| fSelect | |
| Hierarchy | |
| Number Range | |
| Pager | |
| Proximity | |
| Radio | |
| Reset | |
| Search | |
| Slider | |
| Sort | |
| Star Rating | |
| User Selections |
You can find a full reference of available facets on the official FacetWP documentation.
$builder->addAutocomplete('autocomplete', [
'label' => 'Autocomplete',
'source' => 'post_title',
'placeholder' => 'Placeholder',
]);$builder->addCheckbox('checkbox', [
'label' => 'Categories',
'source' => 'tax/category',
'parent_term' => '',
'hierarchical' => 'no',
'show_expanded' => 'no',
'ghosts' => 'no',
'preserve_ghosts' => 'no',
'operator' => 'and',
'orderby' => 'count',
'count' => '10',
'soft_limit' => '5',
]);$builder->addDateRange('date_range', [
'label' => 'Date Range',
'source' => 'post_date',
'compare_type' => '',
'fields' => 'both',
'format' => '',
]);$builder->addDropdown('dropdown', [
'label' => 'Dropdown',
'source' => 'tax/category',
'label_any' => 'Any',
'parent_term' => '',
'modifier_type' => 'off',
'modifier_values' => '',
'hierarchical' => 'no',
'orderby' => 'count',
'count' => '10',
]);$builder->addFselect('fselect', [
'label' => 'fSelect',
'source' => 'tax/category',
'label_any' => 'Any',
'parent_term' => '',
'modifier_type' => 'off',
'modifier_values' => '',
'hierarchical' => 'no',
'multiple' => 'no',
'ghosts' => 'no',
'preserve_ghosts' => 'no',
'operator' => 'and',
'orderby' => 'count',
'count' => '10',
]);$builder->addHierarchy('hierarchy', [
'label' => 'Hierarchy',
'source' => 'tax/category',
'label_any' => 'Any',
'modifier_type' => 'off',
'modifier_values' => '',
'orderby' => 'count',
'soft_limit' => '5',
]);$builder->addNumberRange('number_range', [
'label' => 'Number Range',
'source' => 'post_meta/price',
'compare_type' => '',
'fields' => 'both',
]);$builder->addPager('pager', [
'label' => 'Pager',
'pager_type' => 'numbers',
'inner_size' => '2',
'dots_label' => '…',
'prev_label' => '« Prev',
'next_label' => 'Next »',
'count_text_plural' => '[lower] - [upper] of [total] results',
'count_text_singular' => '1 result',
'count_text_none' => 'No results',
'load_more_text' => 'Load more',
'loading_text' => 'Loading...',
'default_label' => 'Per page',
'per_page_options' => '10, 25, 50, 100',
]);$builder->addProximity('proximity', [
'label' => 'Proximity',
'source' => 'post_meta/location',
'unit' => 'mi',
'radius_ui' => 'dropdown',
'radius_options' => '10, 25, 50, 100, 250',
'radius_min' => '1',
'radius_max' => '50',
'radius_default' => '25',
'placeholder' => '',
]);$builder->addRadio('radio', [
'label' => 'Radio',
'source' => 'tax/category',
'label_any' => 'Any',
'parent_term' => '',
'modifier_type' => 'off',
'modifier_values' => '',
'ghosts' => 'no',
'preserve_ghosts' => 'no',
'orderby' => 'count',
'count' => '10',
]);$builder->addReset('reset', [
'label' => 'Reset',
'reset_ui' => 'button',
'reset_text' => 'Reset',
'reset_mode' => 'off',
'auto_hide' => 'no',
'reset_facets' => [],
]);$builder->addSearch('search', [
'label' => 'Search',
'search_engine' => '',
'placeholder' => '',
'auto_refresh' => 'no',
]);$builder->addSlider('slider', [
'label' => 'Slider',
'source' => 'post_meta/price',
'compare_type' => '',
'prefix' => '',
'suffix' => '',
'reset_text' => 'Reset',
'format' => '0,0',
'step' => '1',
]);$builder->addSort('sort', [
'label' => 'Sort',
'default_label' => 'Sort by',
'sort_options' => [
[
'label' => 'Title (A-Z)',
'name' => 'title_asc',
'orderby' => [
[
'key' => 'title',
'order' => 'ASC',
'type' => 'CHAR',
],
],
],
],
]);$builder->addRating('star_rating', [
'label' => 'Star Rating',
'source' => 'post_meta/rating',
]);$builder->addUserSelections('user_selections', [
'label' => 'User Selections',
]);Instead of passing all options as an array to the add method, you can chain setter methods on the returned FacetBuilder. All setters transform values automatically (booleans become 'yes'/'no' strings).
setName(string $name)
setLabel(string $label)
setSource(string $source)
setOperator(string $operator)
setOrderby(string $orderby)
setCount(int $count)
setHierarchical(bool $hierarchical)
setShowExpanded(bool $show_expanded)
setGhosts(bool $ghosts)
setPreserveGhosts(bool $preserve_ghosts)
setSoftLimit(int $soft_limit)
setLabelAny(string $label_any)
setMultiple(bool $multiple)
setSearchEngine(string $search_engine)
setPlaceholder(string $placeholder)
setAutoRefresh(bool $auto_refresh)
setStep(int $step)
setPrefix(string $prefix)
setSuffix(string $suffix)
setCompareType(string $compare_type)
setFormat(string $format)
setSourceOther(string $source_other)For custom/arbitrary attributes not in the list above, use setAttr(string $name, mixed $value) directly.
FacetsBuilder exposes the following methods for working with its facet collection:
// Add all facets from another FacetsBuilder or a plain array
$builder->addFacets(array|FacetsBuilder $facets): static
// Retrieve facets
$builder->getFacets(): FacetBuilder[]
$builder->getFacet(string $name): FacetBuilder // throws FacetNotFoundException
// Check existence
$builder->facetExists(string $name): boolCalling build() on the FacetsBuilder compiles the config and — by default — registers facets with FacetWP via the facetwp_facets WordPress filter.
// Register with FacetWP (default)
$builder->build();
// Only build the array, skip WP hook registration
$builder->build(addArrayToWpHook: false);
// Register a pre-built array manually
FacetsBuilder::addFacetWpHook(array $facets): voidNote: calling build() on the FacetBuilder returned by addSearch() / addCheckbox() / etc. builds only that single facet's config array and does not register anything with WordPress. Always call $builder->build() on the FacetsBuilder instance to register.
You can find a full reference of how to add a template with PHP on the official FacetWP documentation.
Use addTemplate(string $name, array $args = []) to add a template. It returns a TemplateBuilder for further configuration.
Example using the array form:
$builder->addTemplate('course', [
'label' => 'Course',
'query_array' => [
'post_type' => 'course',
'post_status' => 'publish',
'posts_per_page' => 10,
'orderby' => 'title',
'order' => 'ASC',
],
'modes' => [
'display' => 'visual',
'query' => 'advanced',
],
]);Attention! The query key must contain a PHP code string. Use the setQuery() helper instead to pass a plain array and have it converted automatically.
setName(string $name)
setLabel(string $label)
setQuery(array $query) // converts array to PHP string automatically
setQueryObj(array $query)
setLayout(array $layout)
setModes(array $modes)
setPostType(string $postType) // throws Exception if post type not found
setPostsPerPage(int $postsPerPage)Example using chainable setters:
$builder
->addTemplate('course')
->setLabel('Course')
->setQuery([
'post_type' => 'course',
'post_status' => 'publish',
'posts_per_page' => 10,
'orderby' => 'title',
'order' => 'ASC',
])
->setModes([
'display' => 'visual',
'query' => 'advanced',
]);
$builder->build();setPostType() and setPostsPerPage() are convenience helpers that update both query and query_obj in one call:
$builder
->addTemplate('course')
->setPostType('course')
->setPostsPerPage(9);
$builder->build();If setLabel() is not called and no label key is passed to addTemplate(), the label is auto-generated from the template name.
If setModes() is not called and no modes key is passed, the following defaults are used:
[
'display' => 'visual',
'query' => 'advanced',
]TemplatesBuilder exposes the following methods for working with its template collection:
// Add all templates from another TemplatesBuilder or a plain array
$builder->addTemplates(array|TemplatesBuilder $templates): static
// Retrieve templates
$builder->getTemplates(): TemplateBuilder[]
$builder->getTemplate(string $name): TemplateBuilder // throws FacetNotFoundException
// Check existence
$builder->templateExists(string $name): bool// Register with FacetWP (default)
$builder->build();
// Only build the array, skip WP hook registration
$builder->build(addTemplatesToWpHook: false);
// Register a pre-built array manually
TemplatesBuilder::addFacetWpHook(array $templates): voidUse addFacet(string $name, string $type, array $args = []) to add a facet with an arbitrary type string.
$builder->addFacet('my_facet', 'checkbox', [
'label' => 'My Facet Label',
]);To use a type not in the built-in ALLOWED_FACET_TYPES constant, register it via the itinerisltd/facetwp-builder/allowed_facet_types filter hook.
Filter the list of allowed facet types. Use this to add support for custom or 3rd-party addon types.
add_filter('itinerisltd/facetwp-builder/allowed_facet_types', function (array $types): array {
$types[] = 'my_custom_type';
return $types;
});Filter the compiled facets array before it is returned by FacetsBuilder::build().
Filter the resolved facet type key before it is validated inside FacetsBuilder::__call(). Useful for aliasing method names to custom type strings.
Filter the compiled templates array before it is returned by TemplatesBuilder::build().
| Examples |
|---|
| Add Facets |
| Add a custom facet |
| Add Template |
use Itineris\FacetWpBuilder\FacetsBuilder;
$builder = new FacetsBuilder();
$builder
->addSearch('search')
->setLabel('Search')
->setPlaceholder('Search placeholder')
->setAutoRefresh(true);
$builder->build();use Itineris\FacetWpBuilder\FacetBuilder;
use Itineris\FacetWpBuilder\Facets\Checkbox;
use Itineris\FacetWpBuilder\FacetsBuilder;
$facet = new FacetBuilder('my_facet', Checkbox::TYPE);
$facet
->setLabel('Categories')
->setSource('tax/category');
$facetArray = $facet->build();
FacetsBuilder::addFacetWpHook($facetArray);use Itineris\FacetWpBuilder\TemplatesBuilder;
$builder = new TemplatesBuilder();
$builder
->addTemplate('course')
->setLabel('Courses')
->setQuery([
'post_type' => 'course',
'post_status' => 'publish',
'posts_per_page' => 8,
'orderby' => 'title',
'order' => 'ASC',
]);
$builder->build();FacetWP Builder is maintained by Itineris, originally created by Dan Lapteacru.
Full list of contributors can be found here.
FacetWP Builder is released under the MIT License.