get_listings() is a macro method provided by the Placester Blueprint theme framework. With a single PHP line, you get access to a very flexible list of property listings.

The first step to using the get_listings macro method in your theme is to install the Placester IDX Plugin and add a few lines to the functions.php file. To find out how to do this, review the Custom Theme Quick Start Guide.

Minimum Code Required

Now switch over to the page template you wish to add the listings to and add the following PHP code:


echo PLS_Partials::get_listings();

You should now see a simple view of your listings. Notice that this respects any Global Property Filtering options defined in the Placester Plugin settings.

Arguments for get_listings

As you can see there are 5 listings shown in the default list. To change this we need to add an URL encoded string of arguments. This string can contain one or many values, but for this first example, lets add a single value:


echo PLS_Partials::get_listings(limit=10);

As you can see, our list now has 10 listings instead of 5.

If you want to change how the list is sorted, add a sort_by value to the string. In this example we are sorting by the number of beds in the curated data from the listings feed:


echo PLS_Partials::get_listings(“limit=10&sort_by=cur_data.beds”);

We can keep adding arguments and values to this string to narrow down our list even further. If we want to limit the list to just listings with 2 beds, then use the metadata[beds] key:


echo PLS_Partials::get_listings("limit=10&sort_by=cur_data.baths&metadata[beds]=2");

Possible arguments

At this point, you are probably wondering what arguments and what values are available. Review this document to get [a list of arguments][2]. For arguments like sort_by and metadata, you can look at the raw listings to see what is available for each listing. To see the raw listing, add the following line of PHP:


pls_dump(PLS_Plugin_API::get_listings_list(array('limit'=>1)));

Of course, you only want to use this temporarily. Perhaps a safer way of getting the same info would be this, since it will output the info to the php_error.log file instead of the browser.


error_log(print_r(PLS_Plugin_API::get_listings_list(array('limit'=>1)),true));

Customizing the generated HTML

At this point you can see that things are pretty exciting and very easy. You could make the listings a bit more attractive with some creative CSS. But what if you want to completely customize the HTML output? Well, for that we need to create a hook into the get_listings method.

Lets modify the get_listings code to look like this:


echo PLS_Partials::get_listings("limit=5&context=mycontext");

This adds a context to this particular call to get_listings so that we can refer to it elsewhere in the code. Just above the get_listings call add the following code:


add_filter('pls_listing_mycontext', 'demo_method', 10, 3);
function demo_method($return, $raw, $html) {
  echo "Listing Goes Here";
}

add_filter is a WordPress function that “hooks any named function to a specific filter action”. In this case the filter action we want to hook onto is pls_listing_[your context]. Because we set the context to be mycontext, the actual filter action is pls_listing_mycontext.

The second argument is the name of the function you want hooked on to the filter action.

Next is a priority and 10 is what we usually put in.

Finally, you tell it that demo_method has 3 arguments. Note that demo_method and mycontext are just what I just to use, you can call them whatever you like, just be consistent.

The 3 arguments we need to pass to demo_method are $return, $raw, and $html. The function right now just echoes the string “blah”. When you refresh your browser, you’ll notice that our 5 listings are gone. Instead you see the word blah 5 times. That’s because our demo_method is being used to render the HTML for each listing. Now “Listing Goes Here” isn’t that useful, so let’s change that with some listing info. The listing values are pretty similar to what we saw before, but let’s display the $raw variable in the error log. Just add the following code into the demo_method:


error_log(print_r($raw, true));

echo "Listing Goes Here"

Now we are still displaying the string “Listing Goes Here” for each listing, but the error log shows you the entire raw content for each listing. So now you can easily create something much more interesting. Replace the contents of demo_method with the following code:


function demo_method($return, $raw, $html) {
  error_log(print_r($raw, true));
  $location=$raw['location'];
  $cur_data=$raw['cur_data']; ?>

  <div>
    Address: <?php echo $location&#91;'address'&#93;.', '.$location&#91;'locality'&#93;.', '.$location&#91;'region'&#93;.' '.$location&#91;'postal'&#93; ?>

    <a href="<?php echo $cur_data&#91;'url'&#93; ?>">Click Here to View Property</a> |
    <a href="https://maps.google.com/maps?q=<?php echo $location&#91;'full_address'&#93; ?>&hl=en&z=15">
      View on a map
    </a>
  </div>

Notice that the listings still show a lot of great information and you can add anything you like from the raw values. And the links to more information are still easily accessible. But you can see we also added a link to display the location of the property in a Google map. If you have another service you like to use which requires latitude and longitude, that information is in the raw feed as well.

For the sake of completion, here is the entire listing of code we added in this document: