Download the PHP package apcdatanalytics/rets-rabbit without Composer

Rets Rabbit Craft CMS Plugin

This plugin allows you to connect to the Rets Rabbit API(v2) in order to display your listings in a clean and intuitive way.

Installation

Requirements

The Rets Rabbit plugin requires at least php 7.0 in accordance with minimum Craft 3 PHP requirements.

Documentation

You can interact with the Rets Rabbit API through the PropertiesVariable & OpenHousesVariable.

Open Houses

1. craft.retsRabbit.openHouses.find - Single open house lookup
2. craft.retsRabbit.openHouses.query - Run a raw RESO query

find(int $id, object $resoParams, bool $useCache = false, int $cacheDuration)

$id - The MLS id of the open house you want to fetch from the API.

$resoParams - You may pass valid RESO parameters to help filter the API results for a single open house. This can help speed up the response time if you specifically select the fields you will need from the API by using the $select parameter.

$useCache - Specify if you want the results cached.

$cacheDuration - Specify how long you would like the results cached for in seconds. The default is one hour.

query(object $resoParams, bool $useCache = false, int $cacheDuration)

$resoParams - You may pass valid RESO parameters to help filter the API results for a single open house. This can help speed up the response time if you specifically select the fields you will need from the API by using the $select parameter.

$useCache - Specify if you want the results cached.

$cacheDuration - Specify how long you would like the results cached for in seconds. The default is one hour.

Properties

1. craft.retsRabbit.properties.find - Single listing lookup
2. craft.retsRabbit.properties.query - Run a raw RESO query
3. craft.retsRabbit.properties.search - Perform a search using a saved query from a search form.

find(int $id, object $resoParams, bool $useCache = false, int $cacheDuration)

$id - The MLS id of the property you want to fetch from the API.

$resoParams - You may pass valid RESO parameters to help filter the API results for a single listing. This can help speed up the response time if you specifically select the fields you will need from the API by using the $select parameter.

$useCache - Specify if you want the results cached.

$cacheDuration - Specify how long you would like the results cached for in seconds. The default is one hour.

query(object $resoParams, bool $useCache = false, int $cacheDuration)

$resoParams - You may pass valid RESO parameters to help filter the API results for a single listing. This can help speed up the response time if you specifically select the fields you will need from the API by using the $select parameter.

$useCache - Specify if you want the results cached.

$cacheDuration - Specify how long you would like the results cached for in seconds. The default is one hour.

search(int $id, object $overrides, bool $useCache = false, int $cacheDuration)

$id - The id of the saved search parameters usually pulled from a url segment.

$overrides - You may pass in the following RESO parameters to help tailor your query search: $select, $orderby, $top.

$useCache - Specify if you want the results cached.

$cacheDuration - Specify how long you would like the results cached for in seconds. The default is one hour.

Note: If you want to paginate your search results you will need to use our special rrPaginate tag.

Search Form

At some point your site will need to have a search form where users enter in search criteria. We've created a markup DSL for your search HTML which will allow you to create beautiful forms for your users.

Required Fields

Your search form must have the following two inputs.

1. actionInput("rets-rabbit/properties/search)"
2. redirectInput("search/results/{searchId}")

Note: Your redirect input must have the {searchId} term in it so that the controller endpoint which handles the form POST can redirect you to the results page with the saved search's id in the url.

We believe that the following three search types should cover the vast majority of search form use cases.

1. Single field for a single value
2. Single field for multiple values
3. Multiple fields for a single value

Search Form DSL

Next, let's dive into creating a search form. In general our markup DSL follows a simple pattern:

<input name="{fieldName}(operator)" value="">.

Single Field - Single Value

This will create a query clause that looks like the following:

Single Field - Multiple Values

This will create a query clause that looks like the following:

Multiple Fields - Single Value

This will create a query clause which looks like the following:

Note: By default, each input is treated as an independent {and} clause which are strung together to create a valid RESO query.

Example Search Form

The following example contains markup which will generate a form having the following capabilities:

• Run a contains search against the fields: StateOrProvince, City, PostalCode
• Run a range search (ge and/or le) against ListPrice
• Run a range search (ge) against the fields: BathroomsFull and BedroomsTotal
• Run a multi value contains search against: ExteriorFeatures
• Run a multi value contains search against: InteriorFeatures

We used Bulma.io in this example, but the above markup will generate something like the following.

Search Form

Search Pagination

Because the Rets Rabbit plugin fetches data from an outside data source, it's not possible to use the native Craft pagination tag. We still believe it is very important to have the ability to paginate your results, so we created a special rrPaginate tag which works and looks like the native paginate tag in many ways.

Parameters

• searchCriteria - An instance of SearchCriteriaModel
• pageInfo - craft\web\twig\variables\Paginate just like with the native pagination tag
• viewModel - A view model instance containing possible search results or errors from the API

SearchCriteria

The main difference in our rrPaginate tag compared to the native paginate tag is that it expects a SearchCriteriaModel as the first parameter. You can get an instance of a search criteria model in the following manner.

Once you have an instance of the criteria model, you can build your query in a fluent way by chaining method calls on that criteriaModel object above.

Methods: A SearchCriteriaModel has the following methods available for building a paginated search query.

• forId($searchId) - (required) Pass in the search id, usually from the url
• select(...$fields) - Pass in a list of fields you specifically want from the API
• limit($limit) - (required) How many results per page
• orderBy($field, $dir) - Order the results
• countBy($cacheType) - Specify the type of total results query for the API to run. Valid values are either 'exact' or 'estimated'. Uses 'estimated' by default.

Complete Example

We used Bulma.io in this example, but the above markup will generate something like the following.

Pagination

Other Variables

Aside from PropertiesVariable & OpenHousesVariable, there are a couple of other variables you have access to in your templates.

• SearchesVariable - craft.retsRabbit.searches

SearchesVariable

This template variable has the following methods:

1. exists

bool exists(int $id)

This method checks if a given search id exists. This method is useful for checking if a search exists before trying to execute it which will provide more predictable error handling.