=== Tuziemia Oferty ===
Contributors: tuziemiapl
Tags: real estate, land, listings, property, plots
Requires at least: 6.2
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Embed land-for-sale listings from tuziemia.pl on your blog, by location (TERYT) or by offer links. Gutenberg block and shortcode, SEO-friendly.

== Description ==

Official plugin of **tuziemia.pl**, a Polish portal with free land-for-sale listings and land analyses. It lets real estate agents and bloggers embed a responsive section of current land listings from tuziemia.pl on their own site.

Two modes:

1. **By location (TERYT)** - pick a voivodeship, then county, then municipality from a list, and the plugin fetches matching, up-to-date listings.
2. **Selected offers (links)** - paste the URLs of specific tuziemia.pl offers and the plugin shows exactly those.

Listings are added with the **"Tuziemia Oferty" block** in the block editor (with a live preview and a settings panel) or with the **`[tuziemia_oferty]` shortcode**.

Adding listings on tuziemia.pl is free - add your offers at https://tuziemia.pl and show them on your site with this plugin.

= Features =

* Cascading location picker (16 voivodeships, 380 counties, 2479 municipalities) - the TERYT dataset is bundled with the plugin, so choosing a location needs no external request.
* Link mode for individual offers.
* Responsive card grid (1-4 columns), dark mode.
* Sorting (newest / price / area); filters: KOWR pre-emption, State Forests, archived offers, free-text search.
* Optional seller contact details, description, location, date added, section heading, custom button label.
* Configurable offer-title template (static text + placeholders).
* Response caching (1 hour by default) with a one-click cache clear.
* Fully translatable (text domain: `tuziemia-oferty`).

= Offer title template =

In *Settings -> Tuziemia Oferty -> Offer title template* you decide how each offer heading looks (it is also used for the image `alt` text and for the schema.org data).

* Type static text normally.
* Insert variables in braces: `{lokalizacja}`, `{gmina}`, `{powiat}`, `{wojewodztwo}`, `{powierzchnia}`, `{cena}`, `{cena_za_ha}`, `{numer_dzialki}`.
* A fragment in square brackets `[ ... ]` is shown only when the variable inside it has a value, so no empty brackets or dangling dashes are left.

Default: `Działka na sprzedaż[ - {lokalizacja}][ ({powierzchnia})]`

= SEO =

* **Server-side rendering** - offer HTML is in the page source, not loaded by JavaScript, so search engines can read it.
* **schema.org structured data (JSON-LD)** - the list is output as an `ItemList` of `Product` / `Offer` (price in `PLN`, area in hectares, location, availability). Can be turned off in the settings.
* **Semantic HTML** - each offer is an `<article>` with an `<h3>` heading, a `<time datetime>` element and a descriptive image `alt`.
* **Followed links** to tuziemia.pl by default (can be switched to `nofollow`).
* **Performance** - no front-end JavaScript, a small plugin-scoped stylesheet, lazy-loaded images.

= Shortcode =

`[tuziemia_oferty teryt="1407032" limit="12" columns="3" sort="createdAt"]`

`[tuziemia_oferty urls="https://tuziemia.pl/oferta/140703_2.0015.702, https://tuziemia.pl/oferta/240208_2.0002.2899"]`

Attributes: `teryt`, `urls`, `limit`, `columns`, `sort` (`createdAt|price|area`), `sort_desc`, `kowr`, `lasy`, `archiwum`, `search`, `heading`, `show_description`, `show_meta`, `show_contact`, `cta`.

== External services ==

This plugin relies on the external service **tuziemia.pl** (a portal with free land-for-sale listings and land analyses) to fetch offer data for display.

* **When:** when a page or post that contains this plugin's block or shortcode is rendered (the result is cached, 1 hour by default), and in the block editor while previewing.
* **What is sent:** only the query parameters entered by the site administrator - the TERYT code (voivodeship / county / municipality) or the parcel identifier extracted from a provided link, plus sorting and filtering parameters. The plugin does **not** send any visitor personal data or credentials.
* **Endpoints called:** `https://tuziemia.pl/api/offers` and `https://tuziemia.pl/api/offer-details`.
* Service provider: tuziemia.pl.
* Terms of service: https://tuziemia.pl/regulamin
* Privacy policy: https://tuziemia.pl/polityka-prywatnosci

The service base URL can be changed with the `tuziemia_oferty_api_base` filter or the `TUZIEMIA_OFERTY_API_BASE` constant.

== Installation ==

1. Upload the `tuziemia-oferty` folder to `wp-content/plugins/` (or install the ZIP via *Plugins -> Add New*).
2. Activate the plugin.
3. (Optional) Set defaults in *Settings -> Tuziemia Oferty*.
4. Add the "Tuziemia Oferty" block in the editor, or the `[tuziemia_oferty]` shortcode in your content.

== Frequently Asked Questions ==

= Where do the listings come from? =
From tuziemia.pl, where anyone can add a land listing for free and check land price analyses and transaction data.

= Are the listings up to date? =
Yes. Responses are cached (1 hour by default) - you can shorten the cache time or clear it manually in the plugin settings.

= Is the plugin SEO-friendly? =
Yes - it renders content server-side, adds schema.org (JSON-LD) markup, uses semantic headings and descriptive `alt` attributes, and links to tuziemia.pl are followed by default.

= How do I find a municipality's TERYT code? =
In the block you pick it from a list (voivodeship -> county -> municipality). In the shortcode you pass the 7-digit code, e.g. `1407032`.

= Where do I get a link to a single offer? =
Copy the offer page URL from tuziemia.pl, e.g. `https://tuziemia.pl/oferta/140703_2.0015.702`.

= Does the plugin slow down the site? =
Data is fetched server-side and cached, so visitors do not wait for external requests after the first load. There is no front-end JavaScript.

== Screenshots ==

1. Offers grid on the site (3 columns).
2. Block panel - TERYT location picker.
3. Block panel - link list mode.
4. Plugin settings screen.

== Changelog ==

= 1.0.0 =
* First release: block and shortcode, TERYT mode and link mode, caching, settings, bundled TERYT dataset, schema.org structured data and SEO optimisations.

== Upgrade Notice ==

= 1.0.0 =
First release.
