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 danlapteacru/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_type',
'compare_type' => '',
'fields' => 'both',
'format' => '',
]);$builder
->addDropdown('dropdown', [
'label' => 'Dropdown',
'source' => 'post_type',
'label_any' => 'Any',
'parent_term' => '',
'modifier_type' => 'off',
'modifier_values' => '',
'hierarchical' => 'no',
'orderby' => 'count',
'count' => '10',
]);$builder
->addFselect('fselect', [
'label' => 'fSelect',
'source' => 'post_type',
'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' => 'post_type',
'label_any' => 'Any',
'modifier_type' => 'off',
'modifier_values' => '',
'orderby' => 'count',
'soft_limit' => '5',
]);$builder
->addNumberRange('number_range', [
'label' => 'Number Range',
'source' => 'post_type',
'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_type',
'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' => 'post_type',
'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_type',
'compare_type' => '',
'prefix' => '',
'suffix' => '',
'reset_text' => 'Reset',
'format' => '0,0',
'step' => '1',
]);$builder
->addSort('sort', [
'label' => 'Sort',
'type' => 'sort',
'default_label' => 'Sort by',
'sort_options' => [
[
'label' => 'post_title',
'name' => 'post_title',
'orderby' => [
[
'key' => 'title',
'order' => 'ASC',
'type' => 'CHAR',
],
],
],
],
]);$builder
->addRating('star_rating', [
'label' => 'Star Rating',
'source' => 'post_type',
]);$builder
->addUserSelections('user_selections', [
'label' => 'User Selections',
]);TODO: Add available options.
If you don't want to use the second parameter of the add method, you can use the following shortcut functions:
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)You can find a full reference of how to add a template with PHP on the official FacetWP documentation.
You can add a template by using the addTemplate method.
Example:
$builder
->addTemplate('course', [
'name' => 'course',
'label' => 'Course',
'type' => 'course',
'query_array' => [
'post_type' => 'course',
'post_status' => 'publish',
'posts_per_page' => 10,
'orderby' => 'title',
'order' => 'asc'
],
'query' => '<?php
return [
\'post_type\' => \'course\',
\'post_status\' => \'publish\',
\'posts_per_page\' => 10,
\'orderby\' => \'title\',
\'order\' => \'asc\',
];',
'modes' => [
'display' => 'visual',
'query' => 'advanced'
],
'_code' => true
],
]);Attention! The query key should contain a PHP code string. If you prefer to use a PHP array, utilize the setQuery helper function instead.
Here are some available declarative shortcut functions for the addTemplate method:
$builder
->addTemplate('course')
->setLabel('Course')
->setQuery([
'post_type' => 'course',
'post_status' => 'publish',
'posts_per_page' => 10,
'orderby' => 'title',
'order' => 'asc',
])
->setQueryObj([
'post_type' => 'course',
])
->setModes([
'display' => 'visual',
'query' => 'advanced',
])If you dont want to specify the query or query_obj keys, you can use the setPostType and setPostsPerPage methods to define the post_type and posts_per_page arguments.
Example:
$builder
->addTemplate('course')
->setPostType('course')
->setPostsPerPage(9)If setLabel is not set, or the addTemplate arguments do not contain the label key, then the label will be generated from the template name/key.
If setModes is not set, or the addTemplate arguments do not contain the modes key, then the default modes will be used:
[
'display' => 'visual',
'query' => 'advanced',
]You can use the addFacet method to add a custom/3rd party addon facet.
addFacet(string $name, string $type, array $args = [])
Example:
$builder
->addFacet('myFacetName', 'checkbox', [
'label' => 'My Facet Label',
]);If you want to use a facet type which is not defined in the ALLOWED_FACET_TYPES constant, you can use the addAllowedFacetType method or danlapteacru/facetwp-builder/allowed_facet_types hook to add it.
You can use the following hooks to modify the FacetWP Builder:
You can use this hook to add custom facet types to the FacetWP Builder.
You can use this hook to modify the facets array before it is returned.
You can use this hook to modify the facet key before it is used to check if facet type exists.
You can use this hook to modify the templates array before it is returned.
| Examples |
|---|
| Add Facets |
| Add a custom facet |
| Add Template |
use DanLapteacru\FacetWpBuilder\FacetsBuilder;
$builder = new FacetsBuilder();
$builder
->addSearch('search')
->setLabel('Search')
->setPlaceholder('Search placeholder')
->setAutoRefresh(true)
->build();use DanLapteacru\FacetWpBuilder\FacetBuilder;
use DanLapteacru\FacetWpBuilder\Facets\Checkbox;
use DanLapteacru\FacetWpBuilder\FacetsBuilder;
$facet = new FacetBuilder(static::FACET_NAME, Checkbox::TYPE);
$facet
->setLabel('Search')
->setPlaceholder('Search placeholder')
->setAutoRefresh(true);
$facetArray = $facet->build();
FacetsBuilder::addFacetWpHook($facetArray);use DanLapteacru\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',
])
->build();FacetWP Builder is created by Dan Lapteacru.
Full list of contributors can be found here.
FacetWP Builder is released under the MIT License.