Dynamic Query Block
Overview
The Dynamic Query Block (registered as "Posts Query" in the block inserter) is a powerful component in the Phenix Design System that allows you to fetch and display dynamic content from your WordPress database. This server-side rendered block enables you to create custom content listings with flexible grid layouts and slider functionality. The block works by querying posts based on taxonomies and displaying them using template parts from your theme.
Key Features
- Taxonomy-Based Filtering: Query posts by selecting specific taxonomies and terms
- Template Part Integration: Display query results using theme template parts
- Flexible Grid Layout: Configure responsive grid layouts with customizable columns
- Slider Functionality: Convert grid layouts into interactive sliders
- Server-Side Rendering: Content is rendered on the server for optimal performance and SEO
- Pagination Support: Optional pagination for query results
- Search Integration: Support for search queries with proper nonce verification
How to Use
- In the WordPress editor, click the "+" button to add a new block
- Search for "Posts Query" or find it in the "Phenix Blocks" category
- Add the Posts Query block to your page
- Select a template part from your theme to use for displaying each post
- In the Query by Taxonomies panel, select the taxonomies you want to filter by
- For each selected taxonomy, choose specific terms to include in the query
- Enable Grid Mode if you want to display results in a grid layout
- Configure columns and responsive behavior as needed
- Enable the Slider option if you want the grid to function as a slider
Block Settings
Toolbar Controls
Control | Description |
---|---|
HTML Tag | Select the HTML element to use for the wrapper (div, nav, main, aside) |
Template Part | Select a template part from your theme to use for displaying each post |
Grid Mode | Toggle to enable grid layout for query results |
Slider Mode | Toggle to enable slider functionality for grid layouts |
Columns | Set the number of columns for different screen sizes (mobile, tablet, laptop, desktop) |
Sidebar Controls
Query by Taxonomies Panel
Control | Description |
---|---|
Taxonomies Types | Select which taxonomies to use for filtering (categories, tags, custom taxonomies) |
Terms Selection | For each selected taxonomy, choose specific terms to include in the query |
Grid Layout Panel
Control | Description |
---|---|
Grid Properties | Configure responsive grid layout settings |
Alignment | Set alignment options for grid items |
Responsive Columns | Configure different column counts for various screen sizes |
Gap Controls | Set horizontal and vertical spacing between grid items |
Slider Options Panel
Only visible when Slider Mode is enabled:
Control | Description |
---|---|
Slides Per View | Set the number of slides visible at once |
Slides Per Group | Set how many slides to move at once when navigating |
Space Between | Control the gap between slider items |
Navigation | Enable/disable navigation arrows |
Pagination | Enable/disable pagination dots |
Loop | Enable/disable infinite loop |
Autoplay | Enable/disable automatic sliding |
Layout Panel
Control | Description |
---|---|
Display Type | Choose between grid, list, carousel, or masonry layout |
Columns | Set the number of columns for grid and masonry layouts |
Gap | Control the spacing between items |
Aspect Ratio | Set a consistent aspect ratio for item thumbnails |
Item Height | Control the height of items (auto, fixed, or dynamic) |
Responsive Columns | Adjust column count for different screen sizes |
Template Panel
Control | Description |
---|---|
Template | Select from predefined item templates or create a custom one |
Show Thumbnail | Display the featured image for each item |
Thumbnail Size | Select the image size to use |
Show Title | Display the item title |
Show Excerpt | Display the item excerpt or summary |
Excerpt Length | Control the length of excerpts |
Show Meta | Display item metadata (author, date, categories, etc.) |
Show Button | Add a "Read More" or custom action button |
Pagination Panel
Control | Description |
---|---|
Pagination Type | Choose between numbered pagination, load more button, or infinite scroll |
Items Per Page | Set how many items to show before pagination |
Show Page Numbers | Display numbered page links |
Previous/Next | Show previous and next page navigation |
Load More Text | Customize the text for the load more button |
Carousel Panel
When using carousel layout:
Control | Description |
---|---|
Slides Per View | Number of slides visible at once |
Space Between | Gap between slides |
Loop | Enable/disable infinite loop |
Autoplay | Enable/disable automatic sliding |
Navigation | Show/hide navigation arrows |
Pagination | Show/hide pagination dots |
Technical Implementation
The Dynamic Query block is implemented with server-side rendering for optimal performance and SEO. The PHP rendering function handles the query and display of posts:
Query Construction
The block builds WordPress queries based on taxonomy selections:
Taxonomy Filtering: When taxonomies are selected, the block creates a
tax_query
parameter with the selected terms for each taxonomy.Pagination Support: The block supports standard WordPress pagination with the
paged
parameter.Search Integration: When search functionality is enabled, the block can accept search parameters with proper nonce verification.
Template Part Integration
The block uses WordPress template parts for displaying query results:
get_template_part("template-parts/".$block_attributes["template_part"], null, $the_query->the_post());
This approach allows for flexible and reusable templates that can be customized in your theme.
Grid and Slider Functionality
The block supports both grid layouts and slider functionality:
Grid Layout: When
isFlexbox
is enabled, the block renders posts in a responsive grid with configurable columns.Slider Mode: When both
isFlexbox
andslider
are enabled, the grid becomes an interactive slider with navigation controls.
Pagination Implementation
The block supports standard WordPress pagination through the pagination()
function, which can be configured to display:
- Numbered page links
- Previous/Next navigation
- Custom styling for active and inactive pagination items
Implementation Examples
The Dynamic Query block can be used in various ways based on the configuration options available. Below are descriptions of common implementations based on the actual block functionality.
Basic Posts Grid
A grid layout displaying posts from a specific category:
- Configuration:
- Template Part: Select a post card template from your theme
- Grid Mode: Enabled
- Columns: 3 columns on desktop, 2 on tablet, 1 on mobile
- Taxonomies: Category selected with specific terms chosen
Posts Slider
A slider showcasing featured posts:
- Configuration:
- Template Part: Select a post slide template from your theme
- Grid Mode: Enabled
- Slider Mode: Enabled
- Slides Per View: 1
- Navigation: Enabled
- Pagination: Enabled
- Taxonomies: Tag selected with "featured" term chosen
Blog Archive with Pagination
A standard blog layout with pagination:
- Configuration:
- Template Part: Select a blog post template from your theme
- Grid Mode: Enabled for multi-column layout
- Columns: Configure based on desired layout
- Query: Set pagination to true
- Taxonomies: Configure based on desired filtering
Custom Post Type Display
A grid of custom post types filtered by taxonomy:
- Configuration:
- Template Part: Select a custom template for your post type
- Grid Mode: Enabled
- Columns: Configure based on desired layout
- Query: Set post_type to your custom post type
- Taxonomies: Select custom taxonomies associated with your post type
Common Use Cases
Blog Archive
Create a customized blog archive page with taxonomy-based filtering:
- Add the Posts Query block to your page
- Select an appropriate template part for blog posts
- Configure taxonomy filters to show posts from specific categories
- Enable grid mode with responsive columns (3 on desktop, 2 on tablet, 1 on mobile)
- Enable pagination for better user experience
Featured Content Slider
Create a slider showcasing featured content on your homepage:
- Add the Posts Query block to your page
- Select a template part designed for featured content
- Configure taxonomy filters to show only posts with a specific tag (e.g., "featured")
- Enable grid mode and slider mode
- Configure slider options (navigation, pagination, autoplay)
Category-Specific Content Grid
Display posts from specific categories in a responsive grid layout:
- Add the Posts Query block to your page
- Select an appropriate template part for the content type
- In the Query by Taxonomies panel, select the category taxonomy
- Choose specific category terms to include in your query
- Enable grid mode and configure responsive columns
Best Practices
Template Part Selection: Choose or create template parts that are specifically designed for the content you're displaying. This ensures consistent styling and proper data display.
Taxonomy Organization: Plan your taxonomy structure carefully to make filtering more effective. Well-organized taxonomies make it easier to create meaningful content queries.
Responsive Configuration: Always configure responsive column settings appropriate for your content. What looks good on desktop may not work well on mobile devices.
Grid vs. Slider Usage: Use grid layouts for standard content displays and enable slider functionality only when a carousel presentation enhances the user experience.
Server-Side Performance: Remember that this block uses server-side rendering, so complex queries with many taxonomy filters may impact page load times. Keep queries focused and specific.
Template Part Reusability: Create reusable template parts that can work across multiple query blocks for consistency and easier maintenance.
Testing with Real Content: Always test your query configurations with actual content to ensure the display works as expected across different screen sizes.
Related Blocks
- Container Block - For positioning query results within layouts
- Grid Row Block - For creating custom grid layouts with query results
- Taxonomies Query Block - For querying taxonomy terms
- Users Query Block - For querying and displaying user data