=== Motendo Widget ===
Contributors: danielajeto
Tags: motendo, widget, ogłoszenia, shortcode, json
Requires at least: 5.0
Tested up to: 6.7
Requires PHP: 7.4
Stable tag: 1.2
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Motendo Widget pozwala wyświetlać ogłoszenia z serwisu Motendo.com w postach, stronach i sidebarze.

== Description ==
Motendo Widget to wtyczka WordPress umożliwiająca wyświetlanie ogłoszeń z serwisu [Motendo.com](https://www.motendo.com). Wersja 1.2 wprowadza szereg usprawnień, które zwiększają wydajność, bezpieczeństwo oraz elastyczność rozwiązania. Nowe funkcjonalności obejmują:

* **Nowa architektura obiektowa i przestrzeń nazw:** Kod został przepisany na model obiektowy, co poprawia organizację oraz zmniejsza ryzyko konfliktów z innymi wtyczkami.
* **Mechanizm cache’owania:** Wyniki zapytań do API są przechowywane w transients, co zmniejsza liczbę zapytań do zewnętrznego serwisu i poprawia szybkość działania.
* **Wykorzystanie http_build_query():** Budowanie URL do API odbywa się teraz za pomocą funkcji http_build_query(), co zwiększa czytelność kodu i bezpieczeństwo przesyłanych danych.
* **Output buffering oraz oddzielenie logiki prezentacji:** Renderowanie HTML odbywa się przy użyciu output buffering, co ułatwia modyfikację szablonów i wprowadzanie filtrów.
* **Dodanie hooków i filtrów:** Dzięki nowym filtrom (np. `motendo_widget_output` czy `motendo_widget_transient_expiration`) deweloperzy mogą łatwo rozszerzać funkcjonalność wtyczki.
* **Ulepszony panel ustawień:** Rozbudowano opcje konfiguracyjne w panelu administracyjnym, m.in. dodano możliwość konfiguracji cache’owania i timeoutu zapytań.
* **Poprawiona obsługa błędów API:** Wtyczka lepiej radzi sobie z błędami zewnętrznego API, wyświetlając przyjazne komunikaty użytkownikowi.

== External Services ==
Ta wtyczka łączy się z zewnętrznym API dostarczanym przez Motendo.com w celu pobierania danych ogłoszeń. Oto szczegóły dotyczące tej usługi:

* **Adres API:**  
  Wtyczka wykonuje zapytania do API pod adresem:  
  `https://www.motendo.com/widget/`

* **Wysyłane parametry:**  
  W zapytaniu wysyłane są następujące parametry:
  - `source` – określa rodzaj wyszukiwania (np. `latesearch` lub `latest`).
  - `limit` – liczba ogłoszeń do wyświetlenia.
  - `lang` – język ogłoszeń (np. `pl`, `en`, `de`, `ua`).
  - `format` – format danych zwracanych przez API (`json` lub `html`).
  - `phrase` – fraza wyszukiwania (jeśli nie zostanie podana, wykorzystywane są tagi wpisu).
  - `user_id` – opcjonalnie, identyfikator użytkownika dla pobierania spersonalizowanych danych.

* **Cel przesyłanych danych:**  
  Parametry te są wykorzystywane do pobrania odpowiednich ogłoszeń, które następnie są prezentowane na stronie. Żadne dane osobowe użytkownika nie są zapisywane przez wtyczkę; przesyłane dane służą jedynie do określenia treści wyświetlanych ogłoszeń.

* **Linki do regulaminów i polityki prywatności:**  
  Użytkownicy powinni być świadomi, że korzystanie z tej usługi odbywa się zgodnie z warunkami i polityką prywatności serwisu Motendo.com. Prosimy o zapoznanie się z:
  - [Regulaminem Motendo.com](https://www.motendo.com/regulamin/) 
  - [Polityką prywatności Motendo.com](https://www.motendo.com/polityka-prywatnosci/) 

* **Usługa a dane użytkownika:**  
  Przy każdym ładowaniu widgetu wykonywane jest zapytanie do API, co umożliwia dynamiczne pobieranie aktualnych ogłoszeń. Dane przesyłane są wyłącznie w celu pobrania treści ogłoszeń i nie są wykorzystywane do innych celów.

== Installation ==
1. Pobierz plik ZIP z wtyczką i rozpakuj go.
2. Wgraj folder `motendo-widget` do katalogu `/wp-content/plugins/`.
3. W panelu administracyjnym WordPress przejdź do sekcji **Wtyczki** i aktywuj wtyczkę "Motendo Widget".
4. Skonfiguruj ustawienia wtyczki w menu **Ustawienia > Motendo Widget**.

== Frequently Asked Questions ==

= Jak używać shortcode? =
Wstaw następujący shortcode w treści wpisu lub strony:
[motendo_widget source="latesearch" limit="3" phrase="rolnicze" lang="pl" format="json"]

Parametry shortcode:
* **source** (domyślnie `latesearch`) - Źródło danych:
  - `latesearch` – Szukanie na podstawie frazy.
  - `latest` – Ostatnie ogłoszenia.
* **limit** (domyślnie `3`) – Liczba ogłoszeń do wyświetlenia.
* **phrase** (domyślnie pusty) – Fraza wyszukiwania. Jeśli pusta, używane są tagi wpisu (tylko dla `latesearch`).
* **lang** (domyślnie `pl`) – Język ogłoszeń. Dostępne opcje: `pl`, `en`, `de`, `ua`.
* **format** (domyślnie `json`) – Format wyświetlania:
  - `json` – Widget generowany dynamicznie z danych JSON.
  - `html` – Wyświetlenie widgetu w iframe.
* **user_id** (opcjonalnie) – ID użytkownika, dla którego mają być pobierane spersonalizowane dane.

= Jak automatycznie wstawić widget pod każdym wpisem? =
Przejdź do **Ustawienia > Motendo Widget** i włącz opcję "Wyświetl pod każdym postem".

= Czy mogę wyświetlić widget w sidebarze? =
Tak, wtyczka zawiera widżet o nazwie "Motendo Widget", który można dodać do sidebara w panelu **Wygląd > Widgety**.

== Screenshots ==
1. Ustawienia wtyczki w panelu administracyjnym.
2. Wyświetlanie ogłoszeń w treści wpisu.
3. Widget w sidebarze.

== Changelog ==

= 1.2 =
* Przepisana architektura wtyczki na model obiektowy z zastosowaniem przestrzeni nazw.
* Wdrożono mechanizm cache’owania wyników zapytań do API przy użyciu transients.
* Zmodyfikowano budowanie URL do API z użyciem http_build_query().
* Rozdzielono logikę generowania HTML od logiki biznesowej przy pomocy output buffering.
* Dodano filtry i hooki umożliwiające rozszerzenie funkcjonalności (np. `motendo_widget_output`, `motendo_widget_transient_expiration`).
* Ulepszono panel ustawień w panelu administracyjnym oraz widżet, w tym lepszą obsługę błędów API i timeoutu zapytań.
* Zaktualizowano obsługę parametru `user_id`.
* Domyślny obraz (blank.jpg) jest teraz dołączony lokalnie (w katalogu `assets/img/`), aby wyeliminować zewnętrzne zależności.

= 1.1 =
* Dodano obsługę parametru `user_id` w API.
* Poprawiono funkcję automatycznego wstawiania widgetu pod każdym postem.
* Rozbudowano ustawienia w panelu administracyjnym.

= 1.0 =
* Pierwsze wydanie wtyczki.
* Obsługa shortcode oraz widżetu.
* Wyświetlanie ogłoszeń na podstawie frazy lub tagów.

== Upgrade Notice ==
= 1.2 =
Aktualizacja do wersji 1.2 jest wysoce zalecana. Wersja ta wprowadza nowe funkcje, w tym mechanizm cache’owania, nową architekturę obiektową, ulepszoną obsługę błędów oraz rozszerzone możliwości konfiguracyjne, co znacząco poprawia wydajność i elastyczność wtyczki.

== License ==
Motendo Widget jest dystrybuowany na licencji GPLv2 lub nowszej. Aby uzyskać więcej informacji, odwiedź [https://www.gnu.org/licenses/gpl-2.0.html](https://www.gnu.org/licenses/gpl-2.0.html).
