Elementor widgets and templates (beta)

Description #

Easy Property Listings 3.6 adds Elementor widgets for listings and agents, plus two Elementor template types, so you can design single listing pages, listing cards and the listings archive in Elementor. It works with free Elementor 3.5 or later. Elementor Pro is optional and adds Loop Grid support.

This integration is in beta. Widget names, settings and hooks may still change in a later release, so test on a staging site before relying on it.

The code is in lib/page-builders/elementor/, and the archive page wrapper in lib/templates/themes/elementor/archive-page.php.


Widget categories #

EPL adds four categories to the Elementor panel, each marked (Beta):

  • EPL Elements: parts of one listing: Property Title, Heading, Price, Address, Icons, Featured Image, Content, Excerpt, Feature List, Inspection Times, Map, Gallery, Video, Buttons, Status, Custom Field, Taxonomy and Single Extensions.
  • EPL Archive: lists of listings: Listings Results, Listings Loop (the [listing_advanced] shortcode), Listing Search, Pagination, and EPL Listings (only when Elementor's Loop Grid isn't available).
  • EPL Author: the listing's agents: Agents, Author Box, Photo, Name, Position, Contact, Social and Bio.
  • EPL Staff Directory: for the Staff Directory extension: Staff Listings and the same agent widgets.

The listing widgets show the current listing: the one being viewed, or the current item in a loop. In the Elementor editor there's no current listing, so EPL fills them with a sample listing (see epl_elementor_preview_listing_id). Agent widgets find the listing's agents with epl_elementor_agent_id.


Template types #

EPL adds two template types under Templates > Saved Templates > Add New. Both are designed with the EPL widgets and have a Preview Listing ID setting for the editor canvas. They don't use Elementor Pro's display conditions; EPL decides where they show.

  • EPL Single Listing (epl-single): replaces the listing body on single listing pages. Its Apply To Listing Types setting limits it to some listing types; leave it empty for all types.
  • EPL Listing Card (epl-loop-card): one listing's card in a grid. It's only used where a widget picks it (Listings Results, Listings Loop and EPL Listings); there's no site-wide card. EPL installs a ready-made card called EPL Card the first time someone who can edit theme options (normally an administrator) loads the WordPress admin. It's updated with a new plugin version only if you haven't edited it, and isn't reinstalled if you delete it. See epl_elementor_default_card_id.

There's also an EPL Agent Template type (epl-agent) for the Agents widget's template layout.


How a single listing template is picked #

On the front end of a single listing page (not in the Elementor editor), EPL:

  1. Steps aside if an Elementor Pro Theme Builder Single template applies to the page. Pro wins.
  2. Asks epl_elementor_single_template_id. A non-zero ID is used as is.
  3. Otherwise looks at published EPL Single Listing templates, newest edited first, and only uses templates whose author can edit_theme_options (normally administrators). A template made by an editor or author is ignored, because one template replaces every listing page.
  4. Prefers a template that lists this listing type in Apply To Listing Types, otherwise the newest one with that setting empty.
  5. Asks epl_elementor_single_template_enabled, which can turn it off for this page.
  6. Prints the template in place of EPL's normal listing body, inside <div class="epl-elementor-single-template">. The theme's header, footer and EPL's single template file still load.

Archive page and the Listings Results widget #

Under Easy Property Listings > Settings > Elementor Templates, turn on Use An Elementor Page As The Archive and choose a Listings Archive Page. You can also choose a page per listing type, and whether the page is used for search results and for location and feature pages. EPL then shows that page, inside the theme's header and footer, wherever it would show its archive, search or taxonomy template. It only swaps the template file: the main query, pagination and page URL stay as they are. See epl_archive_page_id.

The page needs the Listings Results widget (called EPL Archive Results in the settings help). It's an Elementor wrapper for the [listing_results] shortcode: it loops through the listings the visitor is actually looking at, with the sorter, grid/list switch and pagination options. Its Listing Card control picks an EPL Listing Card, or "EPL Built-in Card" for EPL's PHP loop template. Add Listing Search above it and Pagination below it as needed. In the editor there's no real archive query, so it shows up to six recent listings as a preview.

Elementor Pro's Theme Builder Archive templates still win when one applies to the request.


Elementor Pro #


What EPL protects #

  • A sample listing ID from the URL or a filter is only used for a published listing, or one the user can edit (epl_elementor_preview_listing_id). A preview URL or Elementor AJAX request only counts as the editor for users who can edit_posts.
  • The Custom Field widget won't show protected meta (keys starting with _), or a street address or price the listing hides (epl_elementor_meta_blocked_keys).
  • Single listing templates are only used from authors who can edit_theme_options.
  • The archive page must be a published page without a password.
  • The Listings Loop widget only renders a published Loop Item or EPL Listing Card template.

Turning it off #

Return false from epl_elementor_enabled in a must-use plugin and EPL loads none of the integration. Listings go back to EPL's normal PHP templates.

add_filter( 'epl_elementor_enabled', '__return_false' );

Hooks #

Loading

Templates

Queries

Widgets