=== Vieww Property Listings – Real Estate Plugin for Agents & Property Managers ===
Contributors: jarradnpd
Tags: real estate, real estate plugin, property listings, property management, real estate agent
Requires at least: 5.6
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 2.5.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

A WordPress real estate plugin for agents and property managers. Filterable listings, photo galleries, single-property pages and design controls.

== Description ==

Vieww Property Listings is a WordPress real estate plugin for agents, property managers, holiday-rental owners and small agencies. Publish properties with everything buyers and renters expect — price, bedrooms, bathrooms, parking, land and building sizes, address and photo galleries — and let visitors filter by type, status, location or minimum bedrooms.

Each property gets a polished single-property page with featured image, feature bar, full description, photo gallery with lightbox, and a contact-agent sidebar so enquiries land straight in your inbox. The filterable property grid drops onto any page with a shortcode — perfect for a clean property-listings page on a brochure site, a small agency portfolio, or a holiday-rental hub.

Make it your own with built-in style controls for colours, contact text, currency symbol and area units (m² or sq ft) — so the listings feel like part of your site, not a bolt-on.

**What you get:**

* **A Dedicated Properties Section** — listings live in their own area of your WordPress admin, separate from posts and pages
* **All The Details That Matter** — price, bedrooms, bathrooms, parking, land size, building size, and address
* **Organised Your Way** — group properties by Type (house, apartment, etc.), Status (for sale, sold, leased), and Location
* **Filterable Property Grid** — let visitors search by type, status, location and minimum bedrooms
* **Beautiful Single Property Pages** — featured image, features at a glance, full description, photo gallery with lightbox, and a contact sidebar
* **Match Your Brand** — pick your own colours, contact text, currency symbol and area units (m² or sq ft)
* **Drop-In Shortcodes** — place property grids, details, search forms and feature bars anywhere on your site
* **Mobile Friendly** — responsive layout that looks great on phones, tablets and desktops
* **Designer Friendly** — every template can be overridden from your theme for full design control
* **Secure By Default** — built following WordPress security best practices

== Installation ==

1. Upload the `vieww-property-listings` folder to the `/wp-content/plugins/` directory.
2. Activate the plugin through the 'Plugins' menu in WordPress.
3. Go to **Properties > Getting Started** for a quick-start guide.
4. Go to **Properties > Settings** to customise colours and contact details.
5. Visit **Settings > Permalinks** and click "Save Changes" to flush rewrite rules.
6. Start adding properties via **Properties > Add New**.

== Shortcodes ==

= [vieww_grid] - Property Grid =

Display a filterable grid of property listings.

**Attributes:**

* `per_page` - Number of properties (default: 12)
* `columns` - Grid columns, 2 or 3 (default: 3)
* `show_filters` - Show filter form, yes/no (default: yes)
* `type` - Filter by property type slug
* `status` - Filter by property status slug
* `location` - Filter by location slug
* `bedrooms` - Minimum bedrooms (default: 0)
* `orderby` - Order by: date, price, or title (default: date)
* `order` - Sort direction: ASC or DESC (default: DESC)

**Examples:**

`[vieww_grid per_page="6" columns="2" show_filters="no"]`
`[vieww_grid type="house" status="for-sale" location="brisbane"]`
`[vieww_grid orderby="price" order="ASC" bedrooms="3"]`

= [vieww_details] - Single Property Details =

Display the full details for a specific property including image, features, description, gallery, and contact sidebar.

**Attributes:**

* `id` - Property post ID (default: current post)

**Example:**

`[vieww_details id="42"]`

= [vieww_search] - Search Form =

Display a standalone property search/filter form that submits to the property archive.

**Attributes:**

* `action` - Custom form action URL (default: property archive)

**Example:**

`[vieww_search]`

= [vieww_features] - Feature Bar =

Display the feature bar (bedrooms, bathrooms, parking, land size, building size) for a specific property.

**Attributes:**

* `id` - Property post ID (default: current post)

**Example:**

`[vieww_features id="42"]`

== Template Overrides ==

The plugin provides default templates that work out of the box. To customise them, copy the template file to your theme:

* `single-vieww-property.php` → `your-theme/single-vieww-property.php`
* `archive-vieww-property.php` → `your-theme/archive-vieww-property.php`
* `content-vieww-property-card.php` → `your-theme/vieww-property-listings/content-vieww-property-card.php`
* `content-vieww-property-features.php` → `your-theme/vieww-property-listings/content-vieww-property-features.php`
* `content-vieww-property-gallery.php` → `your-theme/vieww-property-listings/content-vieww-property-gallery.php`
* `content-vieww-property-sidebar.php` → `your-theme/vieww-property-listings/content-vieww-property-sidebar.php`
* `content-vieww-property-filters.php` → `your-theme/vieww-property-listings/content-vieww-property-filters.php`

== Frequently Asked Questions ==

= How do I add a property? =

Go to **Properties > Add New** in your WordPress admin. Fill in the title, description, featured image, and property details (price, bedrooms, etc.). Assign a Property Type, Status, and Location taxonomy term.

= How do I add a gallery to a property? =

In the property editor, add a Gallery block (Gutenberg) or a `[gallery]` shortcode (Classic Editor) to the content area. The plugin will automatically extract the gallery and display it in a lightbox below the description.

= How do I change the colours? =

Go to **Properties > Settings > Colours** tab. Use the colour pickers to set your primary colour, secondary colour, text colour, background colour, and card background.

= How do I change the contact widget text? =

Go to **Properties > Settings > Contact & Display** tab. You can customise the heading, body text, button label, and contact page URL.

= Can I use a different currency? =

Yes. Go to **Properties > Settings > Contact & Display** tab and change the Currency Symbol field. You can also change the area unit (e.g., from m² to sqft).

= How do I display properties on a custom page? =

Use the `[vieww_grid]` shortcode on any page or post. You can filter by type, status, location, and control the number of columns and properties shown.

= Can I put a property search form on my homepage? =

Yes. Use the `[vieww_search]` shortcode on any page. It renders a filter form that submits to the property archive page.

= What happens when I delete the plugin? =

All property data (posts, meta, taxonomy terms, settings) will be permanently deleted when you delete the plugin from the Plugins page. Deactivating the plugin does NOT delete data.

= Is it compatible with page builders? =

Yes. The shortcodes work with any page builder that supports WordPress shortcodes (Elementor, Beaver Builder, WPBakery, etc.).

== External Services ==

This plugin connects to a small number of free, optional external services. Each is described below along with when it is used and what data is sent.

= Google Fonts API =

Used to load web fonts chosen in the Design Settings. Only occurs when a Google Font (as opposed to a system font) is selected in **Properties > Design > Typography**.

* **URL:** https://fonts.googleapis.com
* **When used:** Only when a Google Font is selected in Design Settings (off by default — system fonts are the default)
* **Data sent:** The names of the selected font families (e.g. "Inter", "Poppins"). No personal data or site data is transmitted.
* **Privacy policy:** https://policies.google.com/privacy
* **Terms of service:** https://developers.google.com/terms

If you prefer not to use Google Fonts, simply leave the heading and body font selectors set to a System Font — no external requests will be made.

= Nominatim (OpenStreetMap) geocoding =

Used to convert a property's address into latitude/longitude coordinates so the listing can be shown on the property map. Runs on the server when a property is saved in the WordPress admin, and in the browser when an admin clicks the "Geocode Now" button on a property edit screen.

* **URL:** https://nominatim.openstreetmap.org/search
* **When used:** Only on the admin side — when a property is saved with a new/changed address, or when the "Geocode Now" button is pressed in the Property Details meta box. No lookups run on the front-end.
* **Data sent:** The property's address text and the country string "Australia". No personal data.
* **Privacy policy:** https://osmfoundation.org/wiki/Privacy_Policy
* **Terms of use:** https://operations.osmfoundation.org/policies/nominatim/

Leaving the latitude/longitude fields filled manually in the property edit screen prevents any Nominatim request from being sent for that property on save.

= Photon (komoot.io) address autocomplete =

Used to show a real-time address suggestion dropdown in the admin while typing into the Address field. Selecting a suggestion populates the full address line and coordinates at once.

* **URL:** https://photon.komoot.io/api/
* **When used:** Only on the admin side — while an editor is typing into the Address field of a property. Requests stop if the user stops typing or clicks elsewhere. No lookups run on the front-end.
* **Data sent:** The partial address text the user is typing, plus a geographic bias toward Australia. No personal data, no site data.
* **Privacy policy:** https://www.komoot.com/privacy
* **Service info:** https://photon.komoot.io/

If you prefer not to use Photon autocomplete, simply ignore the suggestions and type the address manually — no suggestions will be acted on unless you click or Enter one.

== Credits ==

This plugin bundles the following GPL-compatible open-source libraries:

* Leaflet (BSD-2-Clause) — https://leafletjs.com
* Leaflet.markercluster (MIT) — https://github.com/Leaflet/Leaflet.markercluster
* Lightbox2 (MIT) by Lokesh Dhakar — https://lokeshdhakar.com/projects/lightbox2/

The full license text for each library is included in its respective `assets/vendor/<library>/LICENSE.txt` file.

== Screenshots ==

1. The property archive — a 3-column responsive grid with type, status, location, bedroom and sort filters.
2. A single property page — hero image, status badge, full address, feature bar, description and contact-agent sidebar with location map.
3. The same archive narrowed by the type filter to "Apartment".
4. Settings screen — contact widget heading and body text, contact button label, contact-page URL, currency symbol and area unit.
5. Design settings — live colour pickers and typography controls for the property archive and single pages.
6. Getting Started screen — quick-start guide, available shortcodes reference and feature overview.

== Changelog ==

= 2.5.4 =
* TESTED: Confirmed compatible with WordPress 7.0.

= 2.5.3 =
* Listing: extended screenshot set from 3 to 6 — adds Settings, Design and Getting Started admin captures. Captions rewritten to match.

= 2.5.2 =
* Listing: added the first set of WordPress.org screenshots (3 captures) and rewrote the screenshot captions to match.

= 2.5.1 =
* Admin: moved inline `<style>` and `<script>` blocks out of the property meta boxes into dedicated enqueued assets (`assets/css/vieww-pl-meta-boxes.css` and `assets/js/vieww-pl-gallery-admin.js`), per WordPress.org coding standards. Translated strings now flow through `wp_localize_script()`.
* Removed legacy `wppl_*` shortcode aliases (`wppl_grid`, `wppl_details`, `wppl_search`, `wppl_features`). Use the `vieww_*` shortcodes instead.
* Header: removed `Plugin URI` while the upstream site SSL is being reconfigured.

= 2.5.0 =
* Internal: renamed PHP constants, classes, functions, options and transients from the legacy `VIEWW_PL_*` / `vieww_pl_*` prefix to `VIEWWPL_*` / `viewwpl_*` for consistency with the wider Vieww plugin suite. No user-visible changes — an automatic one-shot migration on first load preserves settings on upgrade.
* Uninstall: now also removes structured address meta (`_vieww_street`, `_vieww_suburb`, `_vieww_state`, `_vieww_postcode`), design settings, and migration-tracker options when the plugin is deleted.
* Bundled library licenses (Leaflet, Leaflet.markercluster, Lightbox2) included as `LICENSE.txt` files alongside each vendor library, with attribution added to readme.

= 2.4.2 =
* Design Settings split out into its own admin screen and class (`VIEWWPL_Design_Settings`) for clearer separation between functional settings and visual customisation.
* Gallery: improved attachment handling for properties that use the Gutenberg Gallery block alongside the dedicated gallery meta box.
* Various small admin-UI polish fixes on the Properties settings screens.

= 2.3.0 =
* Address fields: split the single Address textarea into Street, Suburb, State, and Postcode for consistency with Vieww Directory and to enable click-to-fill autocomplete.
* Geocoding: structured Nominatim queries now use the four fields directly (no more freeform parsing). Hash-skip key updated so any field change re-triggers a lookup.
* Autocomplete: typing into the Street Address field shows Photon (komoot.io) suggestions; selecting one fills Suburb / State / Postcode / Latitude / Longitude in a single click.
* Fixed: addresses with both a unit keyword AND a slash (e.g. `Unit 5/123 Main St`) no longer lose the street number during geocoding — coordinates now resolve to the actual street, not the suburb centroid.
* Migration: existing `_vieww_address` values are split into the new structured fields on first load. The original value is retained as a display fallback for entries that didn't parse cleanly.

= 2.1.0 =
* Gallery: switched from content-extraction to a dedicated meta box (`_vieww_gallery_ids`). One-time migration preserves existing gallery data.
* Status colours: added per-status badge colour picker in Properties > Statuses.
* Design settings: expanded font picker with Google Fonts (Sans Serif + Serif groups).
* Design settings: updated default colour palette to Vieww brand colours.
* Fixed single property page font sizes (title and price).

= 2.0.0 =
* Renamed plugin from "WP Property Listings" to "Vieww Property Listings" for Vieww brand consistency.
* Post type changed from `property` to `vieww-property`.
* Taxonomies changed to `vieww-property-type`, `vieww-property-status`, `vieww-property-location`.
* Meta keys changed from `_wppl_*` to `_vieww_*`.
* New shortcodes: `vieww_grid`, `vieww_details`, `vieww_search`, `vieww_features`.
* Legacy shortcodes (`wppl_*`) retained as aliases for backwards compatibility.
* Automatic database migration from old plugin data on activation.
* Constants use `VIEWW_PL_*` prefix to avoid collision with other Vieww plugins.

= 1.0.0 =
* Initial release.
* Custom post type with Gutenberg support.
* 3 taxonomies: Property Type, Property Status, Location.
* Meta fields: price, bedrooms, bathrooms, parking, land size, building size, address.
* Filterable property grid with 4 filter dropdowns.
* Single property template with 70/30 layout.
* Gallery with Lightbox2 (bundled locally).
* Settings page with colour palette and contact widget configuration.
* 4 shortcodes: vieww_grid, vieww_details, vieww_search, vieww_features.
* Template override system (theme can override all templates).
* Full internationalisation support.
* Responsive design with 4 breakpoints.
* Uninstall cleanup.

== Upgrade Notice ==

= 2.5.1 =
Admin assets moved out of inline tags into enqueued files. Legacy `wppl_*` shortcode aliases removed — use the `vieww_*` shortcodes.

= 2.5.0 =
Internal prefix rename for Vieww-suite consistency. An automatic one-shot migration preserves all settings on upgrade — no action required.

= 2.0.0 =
Rebranded to Vieww Property Listings. Automatic migration handles all data. Legacy shortcodes continue to work.

= 1.0.0 =
Initial release.
