The template, located in the page-templates/agents_list.php directory of the WpResidence theme, is responsible for displaying a list of agents in a grid format. This template includes functionality for pagination and dynamic column sizing, making it a versatile tool for showcasing your real estate agents.
Template Structure and Functionality
Let’s break down the template file step by step:
1. Template Declaration
The file begins with a template declaration:
/**
* Template Name: Agents list
* MILLDONE
* src page-templates\agents_list.php
* This template displays a list of agents in a grid format.
* It includes functionality for pagination and dynamic column sizing.
*
* @package WpResidence
* @subpackage Templates
* @since WpResidence 1.0
*/
This declaration allows WordPress to recognize this file as a selectable page template in the WordPress admin area.
2. Plugin Dependency Check
The template checks for the required WpResidence Core Plugin:
if (!function_exists('wpestate_residence_functionality')) {
wp_die(
__('This page requires the WpResidence Core Plugin. Please activate it from the plugins menu.', 'wpresidence'),
__('Plugin Activation Required', 'wpresidence'),
array('back_link' => true)
);
}
This check ensures that the necessary functionality is available before proceeding with the page rendering.
3. Header and Theme Options
The template loads the header and retrieves theme options:
get_header();
wp_suspend_cache_addition(true);
$wpestate_options = get_query_var('wpestate_options');
The wp_suspend_cache_addition(true) function is used to temporarily suspend cache additions for performance reasons. The theme options are retrieved using get_query_var('wpestate_options').
4. Column Class Calculation
The template calculates the appropriate column class:
$agent_unit_col_class = wpestate_get_agent_column_class($wpestate_options);
This function is located in libs/agent_functions.php within the theme structure. It determines the column width for agent cards based on the theme options.
5. Agent Unit Template Selection
The template selects which agent unit template to use:
$agent_unit = wpestate_agent_card_selector();
This function, also located in libs/agent_functions.php, chooses the appropriate agent card template based on theme settings.
6. Main Content Area
The main content area is structured as follows:
<div class="row wpresidence_page_content_wrapper">
<?php get_template_part('templates/breadcrumbs'); ?>
<div class="<?php echo esc_attr($wpestate_options['content_class']); ?>">
<?php get_template_part('templates/ajax_container'); ?>
<?php while (have_posts()) : the_post();
if (esc_html(get_post_meta($post->ID, 'page_show_title', true)) != 'no') : ?>
<h1 class="entry-title"><?php the_title(); ?></h1>
<?php endif; ?>
<div class="single-content"><?php the_content(); ?></div>
<?php endwhile; ?>
<div id="listing_ajax_container_agent" class="row">
<?php
$args = array(
'cache_results' => false,
'post_type' => 'estate_agent',
'paged' => $paged,
'posts_per_page' => 10
);
$agent_selection = new WP_Query($args);
while ($agent_selection->have_posts()): $agent_selection->the_post();
include(locate_template($agent_unit));
endwhile;
?>
</div>
<?php wpestate_pagination($agent_selection->max_num_pages, $range = 2); ?>
</div>
<?php include get_theme_file_path('sidebar.php'); ?>
</div>
This section includes breadcrumbs, an AJAX container, the page title and content, the agents listing, pagination, and the sidebar.
Extending Functionality
Here are some ways to extend the functionality of this template:
1. Customizing the Agent Query
To modify the agent query, you can create a custom function and use the pre_get_posts action. Add this to your child theme’s functions.php file:
function custom_agent_query($query) {
if (!is_admin() && $query->is_main_query() && is_page_template('page-templates/agents_list.php')) {
$query->set('posts_per_page', 12);
$query->set('orderby', 'title');
$query->set('order', 'ASC');
}
}
add_action('pre_get_posts', 'custom_agent_query');
2. Adding Custom Fields to Agent Cards
To add custom fields to agent cards, you can create a custom agent unit template. Copy the existing template (e.g., agent_unit.php) to your child theme and modify it:
// In your custom agent unit template
<div class="agent_custom_field">
<?php echo esc_html(get_post_meta(get_the_ID(), 'agent_custom_field', true)); ?>
</div>
Then, update the wpestate_agent_card_selector() function to use your custom template:
function custom_agent_card_selector($template) {
return get_stylesheet_directory() . '/custom_agent_unit.php';
}
add_filter('wpestate_agent_card_selector', 'custom_agent_card_selector');
3. Customizing Pagination
To customize the pagination, you can override the wpestate_pagination() function. Add this to your child theme’s functions.php file:
function custom_wpestate_pagination($pages = '', $range = 2) {
// Your custom pagination code here
}
remove_action('wpestate_pagination', 'wpestate_pagination', 10);
add_action('wpestate_pagination', 'custom_wpestate_pagination', 10, 2);
CSS Classes and Styling
The main CSS classes used in this template are:
.agent_unit: Main class for agent cards. Styles are inscss/agent_cards/_agent_unit.scss.
To customize the appearance of agent cards, you can add custom CSS to your child theme’s style.css file:
.agent_unit {
border: 1px solid #e0e0e0;
border-radius: 8px;
transition: box-shadow 0.3s ease;
}
.agent_unit:hover {
box-shadow: 0 4px 8px rgba(0,0,0,0.1);
}
Related Functions and Their Locations
wpestate_get_agent_column_class(): Located inlibs/agent_functions.php. Determines the column class for agent cards.wpestate_agent_card_selector(): Located inlibs/agent_functions.php. Selects the appropriate agent card template.wpestate_pagination(): Located inlibs/general_functions.php. Handles pagination for the agent list.
Actions and Filters Guide
The agents_list.php template in the WpResidence theme has been enhanced with several actions and filters. These additions allow developers to customize and extend the functionality of the agents list page without directly modifying the core template file. This guide explains each new action and filter, providing examples of how to use them.
Actions
1. wpresidence_before_agents_list_content
This action runs before the main agents list content.
Usage:
add_action('wpresidence_before_agents_list_content', 'my_custom_before_content');
function my_custom_before_content() {
echo '<div class="custom-before-content">Custom content before agents list</div>';
}
2. wpresidence_after_agents_list_page_content
This action runs after the page content but before the agents list.
Usage:
add_action('wpresidence_after_agents_list_page_content', 'my_custom_after_page_content');
function my_custom_after_page_content() {
echo '<div class="custom-after-page-content">Custom content after page content</div>';
}
3. wpresidence_before_agents_loop
This action runs before the agent loop starts.
Usage:
add_action('wpresidence_before_agents_loop', 'my_custom_before_loop');
function my_custom_before_loop() {
echo '<div class="custom-before-loop">Custom content before agent loop</div>';
}
4. wpresidence_after_agents_loop
This action runs after the agent loop ends.
Usage:
add_action('wpresidence_after_agents_loop', 'my_custom_after_loop');
function my_custom_after_loop() {
echo '<div class="custom-after-loop">Custom content after agent loop</div>';
}
5. wpresidence_after_agents_list_content
This action runs after the entire agents list content.
Usage:
add_action('wpresidence_after_agents_list_content', 'my_custom_after_content');
function my_custom_after_content() {
echo '<div class="custom-after-content">Custom content after agents list</div>';
}
Filters
1. wpresidence_agents_per_page
This filter allows modifying the number of agents displayed per page.
Usage:
add_filter('wpresidence_agents_per_page', 'my_custom_agents_per_page');
function my_custom_agents_per_page($per_page) {
return 12; // Change the number of agents per page to 12
}
2. wpresidence_agents_query_args
This filter allows modifying the query arguments for fetching agents.
Usage:
add_filter('wpresidence_agents_query_args', 'my_custom_agents_query_args');
function my_custom_agents_query_args($args) {
$args['orderby'] = 'title';
$args['order'] = 'ASC';
return $args;
}
3. wpresidence_custom_agent_template
This filter allows using a custom template for each agent card.
Usage:
add_filter('wpresidence_custom_agent_template', 'my_custom_agent_template');
function my_custom_agent_template($template) {
return get_stylesheet_directory() . '/custom-agent-template.php';
}
Practical Examples
Adding a Search Form Before the Agents List
You can use the wpresidence_before_agents_list_content action to add a search form:
add_action('wpresidence_before_agents_list_content', 'add_agent_search_form');
function add_agent_search_form() {
echo '<form class="agent-search-form" method="get">';
echo '<input type="text" name="agent_search" placeholder="Search agents...">';
echo '<input type="submit" value="Search">';
echo '</form>';
}
Modifying Agent Query Based on Search
You can use the wpresidence_agents_query_args filter to modify the query based on the search:
add_filter('wpresidence_agents_query_args', 'modify_agent_query_args');
function modify_agent_query_args($args) {
if (isset($_GET['agent_search']) && !empty($_GET['agent_search'])) {
$args['s'] = sanitize_text_field($_GET['agent_search']);
}
return $args;
}
Adding Custom Content After Each Agent
You can create a custom agent template and use the wpresidence_custom_agent_template filter:
add_filter('wpresidence_custom_agent_template', 'custom_agent_template');
function custom_agent_template($template) {
return get_stylesheet_directory() . '/custom-agent-template.php';
}
In your custom-agent-template.php:
<?php
// Include the original template
include(get_template_directory() . '/templates/agent_card_templates/agent_unit.php');
// Add custom content
echo '<div class="custom-agent-content">';
echo 'Custom content for ' . get_the_title();
echo '</div>';
?>
These actions and filters provide powerful ways to customize the agents list page in the WpResidence theme. By using these hooks, you can add new features, modify existing functionality, and tailor the agents list to your specific needs without altering the core theme files.