Jump to main content Jump to doc navigation

The bdListings snippet can be used to present search results, a generic listing overview and more.

Snippet Properties

General Properties

Property Name Description Default Value
limit Maximum number of results, or 0 for all listings. 0
offset Optional offset (for use with pagination, you can use getPage for that). 0
sort JSON string to allow sorting on multiple factors with different directions. Fields you can use in this property and &sortby are: - id
- title
- description
- keywords
- price
- createdon
- publisheduntil
- featured
- companyname
- contactinfo
- address
- phone
- email
- neighborhood
- zip
- city
- country
- website
- latitude
- longitude
- category_name
- category_description
- subcategory_name (may not exist)
- subcategory_description (may not exist)
- target_name (may not exist)
- pricegroup_display (may not exist)
{"city": "ASC", "neighborhood": "ASC", "companyname": "ASC" }
sortby When &sort is empty or not a valid JSON string (hint: use &sort=`` to overrule the default), you can define a property to sort on with this. title
sortdir `[ASC DESC]` When &sort is empty or not a valid JSON string you can define ascending or descending sort order with this property.
activeOnly `[1 0]` If 1 (true) will only show active items.
featuredOnly `[1 0]` If 1 (true) will only show featured items.
where Optional JSON encoded limits.
acceptUrlParams `[1 0]` Allow specific url params (see acceptedUrlParams) to override properties you set in the snippet call / default values.
acceptedUrlParams Comma separated list of properties that are allowed to override what's set in the snippet call or default values. query, keyword, target, pricegroup, city, category, subcategory, sort, listings
redirectResource Required if using click tracking. The Resource ID to use as redirect resource. See bdRedirect as well. 39
rowSeparator Separator to use between listings. a line break (\n)
imageSeparator Separator to use between images of a listing. a line break (\n)
emptyValue A value (hint: could be a chunk tag) to display when there are no results.

No listings found :(

(bdlistings.noresults lexicon key)
trackViews `[1 0]` When 1, the snippet will increment the "views" field for listings in the displayed result set. Can be useful if you have certain lists you don't want to influence the view count. Added in 1.1.1-pl.

Filtering Properties

Property Name Description
query Full-text search that uses a loose match against the title and description of a listing.
keyword Full-text search that uses a loose match against the keyword field.
target ID of a target as defined in the component to match against.
pricegroup ID of a price group as defined in the component to match against.
city Loose match against the city field.
category Either the category name (exact match) or ID to filter on. As of 1.1.2 this will also search subcategories (name or ID).
subcategory Either the subcategory name (exact match) or ID to filter on.
listings If you want to show only a specific set of listings, this can be a comma separated list of their IDs.

Tip: by default each of these are accepted as URL properties (or POST values) so they are great to offer as filtering options to your site visitor.

Templating Chunks


Wraps around all the individual items.



Accepted properties:

  • wrapper: all individual items contained in their tplRow chunk, separated by the rowSeparator separator.
  • total: the total amount of items in the result set.


Used to output a single listing.


        [[+redirect_url:notempty=`<a href="[[+redirect_url]]">[[+title]]</a>`:default=`[[+title]]`]]
    [[+images:notempty=`<p>[[+primaryimage:notempty=`<img src="[[+primaryimage:phpthumbof=`w=300&h=200`]]" alt="[[+title]]" /><br />`]] [[+images]]</p>`]]
    <p>In [[+city]] - [[+neighborhood]] - [[+companyname]] - <a href="[[+redirect_url]]">[[+companyname]]</a></p>
    [[+googlemap_url:notempty=`<a href="[[+googlemap_url]]" title="View on Google Maps"><img src="[[+googlemap_static]]" alt="Google Maps"></a>`]]

There's a lot of placeholders you can use there, and some properties have a direct influence on their value. Especially think of the redirect_url (which is influenced by &redirectResource) and the googlemap_static placeholder which is a link generated based on the staticMap* properties (see further below).


  • title
  • description
  • keywords
  • price
  • pricegroup / pricegroup_id (id)
  • pricegroup_display
  • category / category_id (id)
  • category_name
  • category_description
  • subcategory / subcategory_id (id)
  • subcategory_name
  • subcategory_description
  • target / target_id (id)
  • target_name
  • createdon (use with strtotime and date output modifiers)
  • publisheduntil (use with strtotime and date output modifiers)
  • active (1/0)
  • featured (1/0)
  • extended (1/0)
  • companyname
  • contactinfo
  • address
  • phone
  • email
  • neighborhood
  • zip
  • city
  • country
  • website
  • latitude
  • longitude
  • clicks
  • views
  • googlemap_static: url to a static google map image (based on your map snippet properties, see further below). Empty if no lat/long is set.
  • googlemap_url: url to maps.google.com/maps?q=LATITUDE,LONGITUDE. Empty if no lat/long is set.
  • redirect_url: url to the &redirectResource resource with the "lid" property and the listing ID as its value, used to redirect to the website set for the listing while tracking clicks. Empty if no website is set.
  • images: filled with individual images templated with the tplImage chunk, separated by the imageSeparator property.
  • primaryimage: if you have an image marked as primary, this will have the link (so not the tplImage tpl) to the image. If you don't have an image marked as primary it will attempt to use the first image.
  • primaryimagepath: path to the image set in primaryimage.

tplImage (lower L then upper i)

Used to wrap around images inside a listing. (not used for the primaryimage property in the tplRow chunk)


<img src="[[+image:phpthumbof=`w=150&h=150&zc=1`]]" alt="[[+caption]]" />


  • image
  • imagepath
  • caption
  • sortorder
  • listing (id)
  • primary (1|0)

Static Map Properties

In the tplRow chunk there's a googlemap_static placeholder. That's a simple image showing a map with the listing centered with a marker. The following properties influence its behavior, and I would suggest reading up on the Google Maps Static API if you are looking for more in-depth explanation of what goes on behind the scenes.

Property Name Description Default Value
staticMapWidth Width of the image to generate. 150
staticMapHeight Height of the image to generate. 150
staticMapZoom Zoom level (1-23, depending on location) 12
staticMapType Type of map to show. hybrid
staticMapMarkerColor Color (some textual, otherwise hex) for the marker. red
staticMapMarkerLabel Text on the marker. Limited to 1 upper character or number. A
staticMapMarkerSize `[tiny small
staticMapMarkerIcon Optionally an icon to use instead of the marker. Consult the Google Maps Static API for detailed usage and what you need to encode or not. An example could be: http://chart.apis.google.com/chart?chst=d_map_pin_icon&chld=cafe%7C996600
staticMapMarkerIconShadow ["true" or "false", actual text so NOT 1 or 0] To use shadow or not when using a custom icon. true


Last 5 listings, simple list format:

<h3>Lastest 5 Ads</h3>
<ul id="latest_ads">
[[!bdListings? &sort=`{"createdon":"DESC"}`  &tplRow=`bdl.listings.list` &limit=`5`]]

bdl.listings.list chunk, pointing to resource 14 (search results page which has an uncached bdListings call on it and accepts URL parameters) with the listing ID as filter, meaning it will only show the one listing.

  <a href="[[~14? &listings=`[[+id]]`]]" title="[[+title]]">[[+title]]</a>

Support the team building MODX with a monthly donation.

The budget raised through OpenCollective is transparent, including payouts, and any contributor can apply to be paid for their work on MODX.



$0 per month—let's make that $500!

Learn more