danlapteacru / facetwp-builder
An Advanced FacetWP Builder for facets and templates.
Installs: 2
Dependents: 0
Suggesters: 0
Security: 0
Stars: 1
Watchers: 1
Forks: 0
Open Issues: 0
Type:package
Requires
- php: ^8.1
- itinerisltd/itineris-wp-coding-standards: ^1.0
README
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
Minimum Requirements
- PHP v8.1
- WordPress v6.1
- FacetWP v4.0
Installation
composer require danlapteacru/facetwp-builder
If your project isn't using composer, you can require the autoload.php file.
Adding/Removing FacetWP Facets and Templates with the Builder
Table of Contents
| 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 |
Facet Types
You can find a full reference of available facets on the official FacetWP documentation.
Autocomplete
$builder ->addAutocomplete('autocomplete', [ 'label' => 'Autocomplete', 'source' => 'post_title', 'placeholder' => 'Placeholder', ]);
Checkboxes
$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', ]);
Date Range
$builder ->addDateRange('date_range', [ 'label' => 'Date Range', 'source' => 'post_type', 'compare_type' => '', 'fields' => 'both', 'format' => '', ]);
Dropdown
$builder ->addDropdown('dropdown', [ 'label' => 'Dropdown', 'source' => 'post_type', 'label_any' => 'Any', 'parent_term' => '', 'modifier_type' => 'off', 'modifier_values' => '', 'hierarchical' => 'no', 'orderby' => 'count', 'count' => '10', ]);
fSelect
$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', ]);
Hierarchy
$builder ->addHierarchy('hierarchy', [ 'label' => 'Hierarchy', 'source' => 'post_type', 'label_any' => 'Any', 'modifier_type' => 'off', 'modifier_values' => '', 'orderby' => 'count', 'soft_limit' => '5', ]);
Number Range
$builder ->addNumberRange('number_range', [ 'label' => 'Number Range', 'source' => 'post_type', 'compare_type' => '', 'fields' => 'both', ]);
Pager
$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', ]);
Proximity
$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' => '', ]);
Radio
$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', ]);
Reset
$builder ->addReset('reset', [ 'label' => 'Reset', 'reset_ui' => 'button', 'reset_text' => 'Reset', 'reset_mode' => 'off', 'auto_hide' => 'no', 'reset_facets' => [], ]);
Search
$builder ->addSearch('search', [ 'label' => 'Search', 'search_engine' => '', 'placeholder' => '', 'auto_refresh' => 'no', ]);
Slider
$builder ->addSlider('slider', [ 'label' => 'Slider', 'source' => 'post_type', 'compare_type' => '', 'prefix' => '', 'suffix' => '', 'reset_text' => 'Reset', 'format' => '0,0', 'step' => '1', ]);
Sort
$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', ], ], ], ], ]);
Star Rating
$builder ->addRating('star_rating', [ 'label' => 'Star Rating', 'source' => 'post_type', ]);
User Selections
$builder ->addUserSelections('user_selections', [ 'label' => 'User Selections', ]);
TODO: Add available options.
Shortcut functions
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)
Templates
You can find a full reference of how to add a template with PHP on the official FacetWP documentation.
Add a template
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)
Default Label
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.
Default Modes
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',
]
Composing Custom/3rd Party Addon Facets
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.
Hooks
You can use the following hooks to modify the FacetWP Builder:
danlapteacru/facetwp-builder/allowed_facet_types
You can use this hook to add custom facet types to the FacetWP Builder.
danlapteacru/facetwp-builder/facets
You can use this hook to modify the facets array before it is returned.
danlapteacru/facetwp-builder/facet_key
You can use this hook to modify the facet key before it is used to check if facet type exists.
danlapteacru/facetwp-builder/templates
You can use this hook to modify the templates array before it is returned.
Examples
Table of Contents
| Examples |
|---|
| Add Facets |
| Add a custom facet |
| Add Template |
Add Facets
use DanLapteacru\FacetWpBuilder\FacetsBuilder; $builder = new FacetsBuilder(); $builder ->addSearch('search') ->setLabel('Search') ->setPlaceholder('Search placeholder') ->setAutoRefresh(true) ->build();
Add a custom facet
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);
Add Template
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();
Credits
FacetWP Builder is created by Dan Lapteacru.
Full list of contributors can be found here.
License
FacetWP Builder is released under the MIT License.