This document explains the basic concepts and usage instructions for the Divi FilterGrid plugin.
Once the plugin is installed on your Divi WordPress site, the Divi FilterGrid module will become available in the Divi builder and can be added to any layout. The module is just like any other Divi module and has three main tabs to customize the appearance and layout: Content, Design, Advanced.
The Content tab contains the following sections in addition to the default Divi sections (Link, Background, Admin Label):
Post Elements – Here you can decide which post elements to display in each grid item.
- Image & Image Size
- Overlay & Icon
- Meta (author, date, terms, comment count)
- Read More Button
- Custom Fields
- Custom Content
There are also options to control the thumbnail and overlay click action:
- Link to post (default)
- Show image in lightbox
- Show image in lightbox gallery
- Show post in popup
- Open custom lightbox gallery
You can also turn on the Use Custom URLs option to change the click action to a custom field value set in each post.
Query Options – Here you can choose which posts or custom post types will display in the grid. There are three query types to choose from:
- Basic (default) – this is a simple query type that limits the results to posts. If this option is selected, all posts will be displayed. You also have the ability to choose individual categories in a checkbox list just like Divi’s default post modules. If all categories are unchecked (default), all posts from all categories will be displayed. If one or more category is selected, only posts from the checked categories will be displayed.
- Advanced – this query type will allow you to query any custom post type with the option to include specific taxonomies and terms as well as the option to exclude specific taxonomies and terms. Advanced query type documentation.
- Custom – this query type will remove all query options from the module and the query will be controlled by a custom filter added to your functions.php file. Here you can create extremely complex queries that would otherwise be impossible to create from within the module’s settings. Custom query type documentation.
Both the Basic and Advanced query types also offer the following query options:
- Post Number
- Offset Number
- Order (ascending/descending)
- Order By (date, title, slug, random, menu order, last modified date, comment count, parent ID, post type, author, custom field)
- Show Private Posts
- Ignore Sticky Posts
- Remove Current Post
- Empty Results Text
Filter Options – the filter options allow you to turn the top filters on or off as well as choose which filters you would like to display and in which order. By default, the filters will be populated with post categories. You can override this by choosing one or more taxonomy and one or more term you would like to display.
You can also change the default filter, hide the all filter, or change the “All” filter text.
Keep in mind the filters are separate but related to the query. The query options control the results. The filter options control which taxonomies/terms you want to allow users to filter those results by. If you add a post tag to the query exclude options but then add the same tag as a filter, that filter will never display any results when clicked because posts with that tag have been excluded from the query.
* When a filter is clicked, the posts related to that filter are loaded via AJAX. This allows maximum efficiency for the Post Number value you have set in the Query Options section. For example, if the Post Number value is set to 12 (default) and you have 10 filters, that’s equivalent to 120 posts assuming each filter/category contains at least 12 posts. Without AJAX, you would need to load 120 posts when the page is initially loaded which would be extremely inefficient. Instead we are only loading the first 12 posts on page load based on the query options. These are the 12 posts that are displayed under the All filter. When a user clicks on a filter other than All, those posts are loaded via AJAX.
The only exception to this is if you have the cache option explained below turned on or if the total number of posts from a filter are already displayed in the original 12 results. For example, if your first filter is Category One which only contains two posts and those posts are already displayed in the initial 12 results. In this case, AJAX is not activated and those posts are simply pulled from the original results.
Pagination Options – the pagination options allow you to turn pagination on or off. If pagination is on, you have three Pagination Types to choose from:
- Paged (default) – this pagination type will provide a numerical pagination at the bottom of the grid. There are many options with this type including prev/next icon options, prev/next text, number of pages to show before and after the active page, and whether to display first/last page icons and the ability to change those icons as well.
- Load more button – the load more button will replace the numerical pagination at the bottom of the grid. Clicking on the button will display the next 12 posts (or the value you have set in the Post Number input in the Query Options) below the original posts. The button will remain at the bottom of the grid, allowing the user to load more posts until there are not results left.
- Load more on scroll – the load more on scroll is very similar to the load more button, except there is no button. When the user scrolls to the bottom of the first set of posts in the grid, the next set of posts will load below the original. As the user continues to scroll, the next set of posts will continue to load until there are no more results.
* All pagination options use AJAX to load the posts. This means if you define the Post Number in your Query Options to 12 (default), only 12 posts will be queried when the page is initially loaded. Once the pagination is activated, the next set of posts are queried and loaded on the page. This is much more efficient than loading all posts at once and then using a virtual pagination to hide/reveal posts based on the pagination position.
Cache Options – this option allows you to turn on AJAX caching, which can reduce the number of AJAX calls for each user as they traverse through the filters and pages. For more information about this feature, please view the Caching documentation.
The Design tab of the Divi FilterGrid plugin contains all of the typical font, sizing, spacing, etc. sections included in default Divi modules. At the top of this tab, we have also included a Layout Options section with the following:
- Select a Layout – choose between Grid (default), List, Fullwidth, or None layout. If the Grid layout is chosen, you will have a Items Width option with a % value. You can increase/decrease this value to easily change the number of items in each row. The List layout will display the featured image on the left and the title, meta, excerpt, etc. on the right. This options will provide a Image Min Width and Image Max Width option to control how much space the featured image consumes. The None layout will simply stack the post items vertically, allowing you to apply your own CSS to display the posts in a custom layout.
- Select a Skin – Divi FilterGrid comes with several skins that allow you to easily change the appearance of the grid and the items in the grid. The None skin removes all CSS and allows you to apply your own CSS to control the appearance.
- Column Gutter – this options controls the space between each item in the grid and is based on the Grid Font Size which is 10px. The default column gutter is 2em, which is 20px.
- Row Gutter – this options controls the space between each row in the grid and is also based on the Grid Font Size. The default row gutter is 2em, which is 20px.
- Grid Font Size – this options sets the default font size for the entire grid. All font sizes and spacing values are in ems by default. Increasing or decreasing the Grid Font Size is a quick and easy way to modify all of these values with one setting. You can then override individual font sizes using the font settings below this option.
The Advanced tab of the Divi FilterGrid plugin contains all of the typical settings you would find in default Divi modules. Pay special attention to the Custom CSS section and the ability to take advantage of CSS Grid and the ability to change the order of elements within each grid item.