=== Matrix: Belize real estate listings for WordPress ===
Contributors: hominly
Tags: real-estate, listings, belize, idx, property
Requires at least: 5.2
Tested up to: 7.1.1
Requires PHP: 7.4
Stable tag: 1.7.1
License: GPLv3
License URI: https://www.gnu.org/licenses/gpl-3.0.html

Import and keep in sync the property listings published on matrixbelize.com, on any WordPress theme. Organised by district, town and village.

== Description ==

Matrix brings the listings published on <a href="https://matrixbelize.com/" target="_blank">matrixbelize.com</a> into your own WordPress website and keeps them up to date automatically.

* **Listings from matrixbelize.com.** There is no separate MLS account and no MLS token. You connect with a Matrix API key from your own matrixbelize.com account.
* **Built for Belize.** Filter by district, town or village. Prices are imported as listed on matrixbelize.com (Belize dollars).
* **Works with any WordPress theme.** A built-in standalone mode renders its own property search, listing cards, map search, single-property pages and agent profiles, placed with shortcodes, Gutenberg blocks or Elementor widgets.
* **Automatic sync.** Changed listings are picked up every hour.
* **Your own pages.** Listings are imported into your WordPress database as native content, so they live on your own domain.
* **Photos are not copied.** Images are served from matrixbelize.com, so your server is not filled with photo files.

This plugin is free to install. What it can do depends on your matrixbelize.com plan: you need an active plan that includes the plugin. Each plan sets how many websites can use it.

Matrix is based on the open source MlsImport plugin (GPLv3) and is distributed under the same license.

== Installation ==

1. Create or sign in to your account at https://matrixbelize.com and get a plan that includes the plugin.
2. Open My Profile > MLS > MLS plugin sites, type a label and click Generate API key. Copy the key right away: it is shown only once.
3. Upload the plugin zip in WordPress under Plugins > Add New > Upload Plugin, then activate it.
4. A new "Matrix" menu appears and the setup wizard opens. Paste your API key and click Save API key, select "Matrix listings" under Your MLS and click Save MLS.
5. In the Field Mapping step choose which details to import.
6. In the Import Configuration step pick the districts, towns or villages, status and price range you want, then run the test import.

The full step-by-step guide, with pictures, is at https://matrixbelize.com/mls/help

== Frequently Asked Questions ==

= Do I need an MLS account or an MLS token? =
No. The only source is the listings published on matrixbelize.com. Your Matrix API key identifies your account.

= Where do I get the API key? =
On matrixbelize.com under My Profile > MLS > MLS plugin sites. You can create up to five keys and revoke any of them at any time.

= How many websites can I use it on? =
That depends on your plan. Each WordPress website that signs in uses one slot. To move to a new domain, remove the old site on the same page on matrixbelize.com.

= Which themes does it work with? =
Any theme. The built-in standalone mode renders its own search, listings, maps and property pages.

= Which listings are imported? =
All listings published on matrixbelize.com, filtered by the districts, towns or villages, status, price range and other options you choose in an Import Task.

= Does it show state or ZIP code? =
No. Belize does not use them, so they are not shown.

= I get "Invalid or revoked matrixbelize.com API key". =
Copy the key again, without extra spaces. If you lost it, revoke it and create a new one on matrixbelize.com.

== Use of 3rd party services ==
This plugin connects over HTTPS to matrixbelize.com (https://matrixbelize.com/api/v1/mls) to sign in with your API key, and to download the listings you ask it to import. It sends your API key, the address of your website and the import filters you choose, and it receives the listing data.

Automated daily diagnostic report: once per day, a connected installation sends a short diagnostic report to matrixbelize.com. It helps detect problems such as a stopped scheduled task or imports that produce no listings. It contains: an anonymous installation ID, your site URL, plugin, PHP and WordPress versions and the active theme, counts of listings imported, updated and deleted over the last 7 days, sync health, the number of active listings and basic data-completeness percentages, your import-task settings, and onboarding progress. It does not collect any information about your site's visitors. Installations that are not connected send nothing.

== Changelog ==

= 1.7.1 =
* Listing photos now arrive exactly as they show on the website, with the listing's MLS number stamped on the picture (and sized for the web, so they load faster). Existing listings get the numbered photos on the next import.

= 1.7.0 =
* Homes that sold or were taken down are now removed from your website. The daily clean-up works with matrixbelize.com (it was missing a list of listings still on the market), and new Import Tasks no longer protect the Active, Active Under Contract, Coming Soon and Pending statuses. Existing tasks that still had that old default are reset once; tasks you changed yourself are left alone.

= 1.6.6 =
* Listing photos are refreshed on the next import even when the listing itself has not changed, so photos whose web address moved no longer show as empty boxes.
* Listing cards now show the credit line (listing courtesy of, MLS number and listing agent) under each card.

= 1.6.5 =
* The sidebar menu is now called BP MATRIX. The plugin itself keeps the name Matrix everywhere else.

= 1.6.4 =
* Brief rename: the sidebar menu was called BP MATRIX and the plugin name was changed with it (corrected in 1.6.5).

= 1.6.3 =
* The Status pill in the MLS Properties list now follows the listing's status: green for Active, amber for Pending, red for Closed or Sold, grey for the rest (it was always red).

= 1.6.2 =
* The service now lives at matrixbelize.com: the plugin connects to matrixbelize.com, and its links, update checks and messages point there. The older addresses keep working for installs that already use them.

= 1.6.1 =
* Name cleanup: the plugin, its screens, messages, API key wording and the setup guide all use the name Matrix.

= 1.6.0 =
* The plugin is now called Matrix: its name on the Plugins page, the BP MATRIX menu in the WordPress sidebar, and every screen and message. The download is now matrix-x.y.z.zip and installs in the matrix folder.

= 1.5.2 =
* Listing Details now also hides agent information on the website: a listing agent field (name, phone, email, bio, ...) that you switch off is no longer shown on listing pages, even if an earlier import had already saved it.

= 1.5.1 =
* Maps: fixed the "Access blocked: app is not following the tile usage policy" tiles. OpenStreetMap needs to see which website asks for its map tiles; sites that hide it (a strict Referrer-Policy) got blocked. The maps now send it, and the attribution links to OpenStreetMap's copyright page.

= 1.5.0 =
* New: on sites without a real estate theme, a "Listings" page (search and listings grid) is created for you after your first import, with a message that links to it. The setup guide has a new chapter on showing your listings and adding them to your menu.

= 1.4.8 =
* The BP MATRIX menu no longer lists "Matrix" twice: the first item under it is now called Settings.

= 1.4.7 =
* One menu: MLS Properties, Real Estate Agents and Design now sit inside the BP MATRIX menu instead of each having its own menu in the sidebar.

= 1.4.6 =
* Listings now show on the website for themes the plugin does not list (for example Twenty Twenty-Five). The listing addresses are set up automatically, so they no longer answer "not found" until you re-save Permalinks, and on block themes the pages now come with your theme's header and footer.

= 1.4.5 =
* Removed the confusing "My MLS is not on this list" choice from the MLS dropdown: Matrix listings is the only source.

= 1.4.4 =
* Matrix is now the plugin's name. "View version details" now shows only what is new in that release, not the whole history.

= 1.4.3 =
* Listing Details tab: when the API key is connected but no MLS has been added yet, it now says to open Connections and click + Add MLS, instead of showing a confusing token message.

= 1.4.2 =
* The name Matrix now replaces "Hominly" in every screen and message (Matrix API key, Matrix listings, Matrix account).

= 1.4.1 =
* The service now lives at matrixbelize.com: the plugin connects to matrixbelize.com, and its links, update checks and messages point there. The old hominly.com address keeps working for installs that already use it.

= 1.4.0 =
* The plugin is now called Matrix: its name on the Plugins page, the BP MATRIX menu in the WordPress sidebar, screens and messages.

= 1.3.10 =
* A spinning circle now shows on the "Waiting for the import worker to start" line.

= 1.3.9 =
* Removed the "Save & start import" button. Import Tasks work as before: set the parameters, press Publish or Update, then press Start Import.

= 1.3.8 =
* Changelog wording cleanup.

= 1.3.7 =
* Test release for the update flow (Plugins page "Update now" and "View version details"). No other changes.

= 1.3.6 =
* "View version details" on the Plugins page now shows the plugin's description and changelog (it used to open a blank window).

= 1.3.5 =
* Field Options: the City field now reads "City, Town, Village" (also in the category list).

= 1.3.4 =
* Field Options: the County/Parish field is now called District, and the theme's State category is shown as District.

= 1.3.3 =
* The plugin now tells matrixbelize.com its version on every request, so the site shows the right version in your matrixbelize.com account right after an upgrade.

= 1.3.2 =
* Houses imported from matrixbelize.com are now typed "Single Family Home" (the usual house in Belize), also when a listing has no type.

= 1.3.1 =
* Import Task screen wording for Belize: "Select Property Type", "Select For Sale / For Rent", and plain help texts (no more "stored in MLS, for example all caps").

= 1.3.0 =
* Import Tasks: new "Save & start import" button in the Publish box. It saves the task and starts the import in one step, instead of filling the fields, pressing Publish, then pressing Start Import. The old buttons still work.

= 1.2.8 =
* Listings already imported are corrected too: their type and For Sale / For Rent status are re-applied on the next import run even when matrixbelize.com reports them unchanged.

= 1.2.7 =
* Houzez and Real Homes: imported listings now get their property type (Condo, Villa, ...) and For Sale / For Rent status, so they show up in the theme's search form, its For Sale / For Rent tabs and the type filter.

= 1.2.6 =
* Houzez: each listing now carries its currency code (BZD) so prices can show as BZ$ when Houzez multi-currency is set up with that currency.

= 1.2.5 =
* Belize wording: listing titles use {District} instead of {CountyOrParish} (old titles with {CountyOrParish} keep working), and the title help no longer mentions state or postal code.

= 1.2.4 =
* Imported listings now fill the theme's own price, bedrooms, size, ID and address fields (Houzez, Real Homes, WpResidence, Wpestate), so prices show on the site. Existing listings are corrected on the next import run.

= 1.2.3 =
* The author line on the Plugins page now reads just "Matrix".

= 1.2.2 =
* New versions now appear on the Plugins page with WordPress's own "There is a new version ... Update now" link, and the plugin checks matrixbelize.com for releases twice a day without needing a sign-in.

= 1.2.1 =
* The "Congratulations! You've successfully imported properties" message after the test import is now shown in green.
* Clicking the "Your MLS" box on the connection screens now lists every available MLS in a dropdown, without having to type first.

= 1.2.0 =
* Import Tasks now live inside the BP MATRIX menu (second item, right after the settings), instead of a menu of their own.

= 1.1.0 =
* New: an "update available" notice. When a newer version is released, administrators see a dismissible notice with a download button and the upgrade steps.
* Import Tasks now offer only the filters matrixbelize.com listings support: districts, towns and villages (plus the "extra" boxes), status, category, type, price, agent ID, exclude agent ID and listing number. Filters that did nothing (postal code, MLS area, subdivision, office and display flags, and the other exclude lists) are no longer shown.
* New "Exclude agent ID" filter now works with matrixbelize.com listings.

= 1.0.0 =
* First Matrix release. Version numbers follow Matrix's own scheme: MAJOR.MINOR.PATCH.
* Connects only to matrixbelize.com. Sign in with a Matrix API key instead of a username and password.
* New source: "Matrix listings" (listings published on matrixbelize.com). No MLS token needed.
* Places are districts, towns and villages. State and ZIP are not shown.
* Menu renamed to Matrix. Help buttons open the setup guide at https://matrixbelize.com/mls/help
