=== 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.6
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Real estate listings for agents and property managers — filterable grids, galleries and maps that work on install. No API keys, no MLS required.

== 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.

Location maps are included and work the day you install: they run on OpenStreetMap, so there's no Google account to create, no API key to paste in, and no billing setup. Type the address and the pin lands on the map by itself — drag it to fine-tune.

**[See the live demo](https://vieww.com.au/properties/)** · **[Documentation](https://vieww.com.au/docs/)**

**What your visitors get:**

* A filterable property grid — search by type, status, location and minimum bedrooms
* A polished page for every property — hero image, status badge, features at a glance, full description and photo gallery with lightbox
* A contact-agent sidebar on every listing so enquiries land straight in your inbox
* Status badges — For Sale, Sold, Under Offer, Leased — each with its own colour

**What you get:**

* A dedicated Properties section in your WordPress admin, separate from posts and pages
* All the details that matter — price, bedrooms, bathrooms, parking, land size, building size, and address
* Group properties your way — by type (house, apartment), status (for sale, sold, leased) and location
* Your own currency symbol and area units (m² or sq ft), your own colours and contact text
* Drop-in shortcodes for grids, search forms, details and feature bars
* Every template can be overridden from your theme — designers and developers stay in control

**Part of the Vieww suite**

Vieww plugins share one philosophy: everything you need ships in the box, your data stays in your own WordPress install, and nothing is sent back to us. Also available: [Vieww Directory](https://wordpress.org/plugins/vieww-directory/) and [Vieww Events Calendar](https://wordpress.org/plugins/vieww-events-calendar/). More at [vieww.com.au](https://vieww.com.au/).

== 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 ==

= Do I need a Google Maps API key? =

No. Property maps run on OpenStreetMap and work as soon as you activate the plugin. There's no Google account to create, no API key to paste in, and no billing setup.

= Do I need an MLS feed? =

No. Vieww Property Listings is built for agents and agencies that enter their own listings — you don't need an MLS feed, a syndication service, or a six-month implementation to put properties on your site.

= 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 to my data if I remove the plugin? =

It's yours. Everything lives in your own WordPress database, and deleting the plugin removes its data cleanly — posts, details, categories and settings all go with it, with no orphaned tables left behind. Deactivating (rather than deleting) keeps all your data intact.

= 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.6 =
* FIX: Property Details and Gallery Images were invisible when adding or editing a property. WordPress 6.7 and later place these sections in a "Meta Boxes" panel at the bottom of the editor that starts collapsed, so the screen looked empty unless you happened to drag the panel open. The panel now opens by default at a sensible height, with the block editor left in place above it — nothing about writing property descriptions changes. If you prefer the panel closed, collapse it and your choice is remembered.

= 2.5.5 =
* IMPROVEMENT: Hardened plugin start-up against name clashes with other plugins. The `viewwpl()` helper is now only defined if nothing else has claimed the name, and the plugin starts itself up through its own class either way, so a clash can no longer take the site down with a fatal error.
* IMPROVEMENT: WordPress.org listing rewritten — live demo and documentation links, Vieww-suite cross-links, Google-Maps-API-key, MLS and data-ownership FAQs, benefit-led short description and feature lists.
* FIX: Geocoding now shares its Nominatim rate-limit transient (`vieww_nominatim_last_call`) with Vieww Directory and Vieww Events Calendar again. The 2.5.0 prefix rename had renamed this key to `viewwpl_nominatim_last_call`, so each plugin kept its own 1 request/second budget and two plugins geocoding at once could exceed the OpenStreetMap usage policy.

= 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.

== Support ==

For support, please use the WordPress.org support forums for this plugin.
