Skip to content

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

  1. In the WordPress editor, click the "+" button to add a new block
  2. Search for "Posts Query" or find it in the "Phenix Blocks" category
  3. Add the Posts Query block to your page
  4. Select a template part from your theme to use for displaying each post
  5. In the Query by Taxonomies panel, select the taxonomies you want to filter by
  6. For each selected taxonomy, choose specific terms to include in the query
  7. Enable Grid Mode if you want to display results in a grid layout
  8. Configure columns and responsive behavior as needed
  9. Enable the Slider option if you want the grid to function as a slider

Block Settings

Toolbar Controls

ControlDescription
HTML TagSelect the HTML element to use for the wrapper (div, nav, main, aside)
Template PartSelect a template part from your theme to use for displaying each post
Grid ModeToggle to enable grid layout for query results
Slider ModeToggle to enable slider functionality for grid layouts
ColumnsSet the number of columns for different screen sizes (mobile, tablet, laptop, desktop)

Query by Taxonomies Panel

ControlDescription
Taxonomies TypesSelect which taxonomies to use for filtering (categories, tags, custom taxonomies)
Terms SelectionFor each selected taxonomy, choose specific terms to include in the query

Grid Layout Panel

ControlDescription
Grid PropertiesConfigure responsive grid layout settings
AlignmentSet alignment options for grid items
Responsive ColumnsConfigure different column counts for various screen sizes
Gap ControlsSet horizontal and vertical spacing between grid items

Slider Options Panel

Only visible when Slider Mode is enabled:

ControlDescription
Slides Per ViewSet the number of slides visible at once
Slides Per GroupSet how many slides to move at once when navigating
Space BetweenControl the gap between slider items
NavigationEnable/disable navigation arrows
PaginationEnable/disable pagination dots
LoopEnable/disable infinite loop
AutoplayEnable/disable automatic sliding

Layout Panel

ControlDescription
Display TypeChoose between grid, list, carousel, or masonry layout
ColumnsSet the number of columns for grid and masonry layouts
GapControl the spacing between items
Aspect RatioSet a consistent aspect ratio for item thumbnails
Item HeightControl the height of items (auto, fixed, or dynamic)
Responsive ColumnsAdjust column count for different screen sizes

Template Panel

ControlDescription
TemplateSelect from predefined item templates or create a custom one
Show ThumbnailDisplay the featured image for each item
Thumbnail SizeSelect the image size to use
Show TitleDisplay the item title
Show ExcerptDisplay the item excerpt or summary
Excerpt LengthControl the length of excerpts
Show MetaDisplay item metadata (author, date, categories, etc.)
Show ButtonAdd a "Read More" or custom action button

Pagination Panel

ControlDescription
Pagination TypeChoose between numbered pagination, load more button, or infinite scroll
Items Per PageSet how many items to show before pagination
Show Page NumbersDisplay numbered page links
Previous/NextShow previous and next page navigation
Load More TextCustomize the text for the load more button

When using carousel layout:

ControlDescription
Slides Per ViewNumber of slides visible at once
Space BetweenGap between slides
LoopEnable/disable infinite loop
AutoplayEnable/disable automatic sliding
NavigationShow/hide navigation arrows
PaginationShow/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:

  1. Taxonomy Filtering: When taxonomies are selected, the block creates a tax_query parameter with the selected terms for each taxonomy.

  2. Pagination Support: The block supports standard WordPress pagination with the paged parameter.

  3. 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:

php
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:

  1. Grid Layout: When isFlexbox is enabled, the block renders posts in a responsive grid with configurable columns.

  2. Slider Mode: When both isFlexbox and slider 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:

  1. Add the Posts Query block to your page
  2. Select an appropriate template part for blog posts
  3. Configure taxonomy filters to show posts from specific categories
  4. Enable grid mode with responsive columns (3 on desktop, 2 on tablet, 1 on mobile)
  5. Enable pagination for better user experience

Create a slider showcasing featured content on your homepage:

  1. Add the Posts Query block to your page
  2. Select a template part designed for featured content
  3. Configure taxonomy filters to show only posts with a specific tag (e.g., "featured")
  4. Enable grid mode and slider mode
  5. Configure slider options (navigation, pagination, autoplay)

Category-Specific Content Grid

Display posts from specific categories in a responsive grid layout:

  1. Add the Posts Query block to your page
  2. Select an appropriate template part for the content type
  3. In the Query by Taxonomies panel, select the category taxonomy
  4. Choose specific category terms to include in your query
  5. Enable grid mode and configure responsive columns

Best Practices

  1. 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.

  2. Taxonomy Organization: Plan your taxonomy structure carefully to make filtering more effective. Well-organized taxonomies make it easier to create meaningful content queries.

  3. Responsive Configuration: Always configure responsive column settings appropriate for your content. What looks good on desktop may not work well on mobile devices.

  4. Grid vs. Slider Usage: Use grid layouts for standard content displays and enable slider functionality only when a carousel presentation enhances the user experience.

  5. 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.

  6. Template Part Reusability: Create reusable template parts that can work across multiple query blocks for consistency and easier maintenance.

  7. Testing with Real Content: Always test your query configurations with actual content to ensure the display works as expected across different screen sizes.

Released under the MIT License.