Merge pull request #44 from alexplusde/docs

Umfangreiche Ergänzungen der Docs

docs/00_intro.md

@@ -0,0 +1,96 @@
+# Veranstaltungskalender, Terminbuchung, Terminanfragen, Anmeldungen und Teilnehmerlisten für REDAXO 5 auf YForm-Basis
+
+![web_banner_redaxo_addon_events](https://user-images.githubusercontent.com/3855487/204768716-fa9f5a97-c1de-421a-aea0-2a0ce8658813.png)
+
+Mit diesem Addon können Termine anhand von YForm und YOrm im Backend verwaltet und im Frontend ausgegeben werden. Auf Wunsch auch mehrsprachig.
+
+**Beispiele**
+
+![event](https://user-images.githubusercontent.com/3855487/180771758-d4a2e4ba-3034-4e96-8e1d-4cc5333de615.png)
+
+![event_date](https://user-images.githubusercontent.com/3855487/180771781-0f2cc875-3561-47e2-a3bb-50752177afa3.png)
+
+![event_settings](https://user-images.githubusercontent.com/3855487/180771783-1973c380-79af-42d6-9b14-babcc4378b3c.png)
+
+![event_category](https://user-images.githubusercontent.com/3855487/180771784-2baad1bb-052e-4dbf-aa64-ef93e1892875.png)
+
+## Features
+
+* Vollständig mit **YForm** umgesetzt: Alle Features und Anpassungsmöglichkeiten von YForm verfügbar
+* Einfach: Die Ausgabe erfolgt über [`rex_sql`](https://redaxo.org/doku/master/datenbank-queries) oder objektorientiert über [YOrm](https://github.com/yakamara/redaxo_yform_docs/blob/master/de_de/yorm.md)
+* Flexibel: **Zugriff** über die [YForm Rest-API](https://github.com/yakamara/redaxo_yform/blob/master/docs/plugins.md#restful-api-einf%C3%BChrung)
+* Sinnvoll: Nur ausgewählte **Rollen**/Redakteure haben Zugriff
+* Bereit für **mehrsprachige** Websites: Reiter für Sprachen auf Wunsch anzeigen oder ausblenden
+* Bereit für mehr: Vorbereitet für das [JSON+LD-Format](https://jsonld.com/event/), ICS-Format
+* Bereit für viel mehr: Kompatibel zum [URL2-Addon](https://github.com/tbaddade/redaxo_url)
+* Mächtig: Datenbank-Struktur für **Anmeldeformulare** und einfache Teilnehmerlisten vorbereitet
+
+> **Tipp:** Events arbeitet hervorragend zusammen mit den Addons [`yform_usability`](https://github.com/FriendsOfREDAXO/yform_usability/) und [`yform_geo_osm`](https://github.com/FriendsOfREDAXO/yform_geo_osm)
+
+> **Steuere eigene Verbesserungen** dem [GitHub-Repository von events](https://github.com/alexplusde/events) bei. Oder **unterstütze dieses Addon:** Mit einer [Spende oder Beauftragung unterstützt du die Weiterentwicklung dieses AddOns](https://github.com/sponsors/alexplusde)
+
+## RESTful API (dev)
+
+Die [Rest-API](https://github.com/yakamara/redaxo_yform/blob/master/docs/plugins.md#restful-api-einf%C3%BChrung) ist über das REST-Plugin von YForm umgesetzt.
+
+### Einrichtung
+
+Zunächst das REST-Plugin von YForm installieren und einen Token einrichten. Den Token auf die jeweiligen Endpunkte legen:
+
+```php
+    /v2.0/event/date
+    /v2.0/event/category
+    /v2.0/event/location
+```
+
+### Endpunkt `date`
+
+**Auslesen:** GET `example.org/rest/v2.0/event/date/?token=###TOKEN###`
+
+**Auslesen einzelner Termin**  GET `example.org/rest/v0.dev/event/date/7/?token=###TOKEN###` Termin  der `id=7`
+
+### Endpunkt `category`
+
+**Auslesen:** GET `example.org/rest/v2.0/event/category/?token=###TOKEN###`
+
+**Auslesen einzelne Kategorie**  GET `example.org/rest/v0.dev/event/category/7/?token=###TOKEN###` Termin  der `id=7`
+
+### Endpunkt `location`
+
+**Auslesen:** GET `example.org/rest/v2.0/event/location/?token=###TOKEN###`
+
+**Auslesen einzelner Standort**  GET `example.org/rest/v0.dev/event/location/7/?token=###TOKEN###` Termin  der `id=7`
+
+## Import
+
+### Import von ICS-Kalendern (dev)
+
+Events kommt mit einem eigenen Cronjob zum importieren von ics-Kalendern aus dem Internet. Das Cronjob-Addon aufrufen, einen neuen Cronjob anlegen und den Instruktionen folgen.
+
+## Export
+
+## Export eines einzelnen Termins als ics-Datei (dev)
+
+Events kommt mit einer eigenen rex_api-Schnittstelle für den Export von einzelnen Terminen. `?rex-api-call=events_ics_file&id=2` aufrufen, um eine ICS-Datei anhand des Termins mit der `id=2` zu erzeugen.
+
+## Lizenz
+
+MIT Lizenz, siehe [LICENSE.md](https://github.com/alexplusde/events/blob/master/LICENSE.md)  
+
+## Autoren
+
+**Alexander Walther**  
+<http://www.alexplus.de>  
+<https://github.com/alexplusde>  
+
+**Michael Schuler**
+<https://github.com/191977>
+
+**Projekt-Lead**  
+[Alexander Walther](https://github.com/alexplusde)
+
+## Credits
+
+events basiert auf: [YForm](https://github.com/yakamara/redaxo_yform)  
+Danke an [Gregor Harlan](https://github.com/gharlan) für die Unterstützung
+Danke an den Kulturkeller e.V. für die Beauftragung für die Weiterentwicklung

docs/00_settings.md

@@ -0,0 +1,25 @@
+# Einstellungen der Events Addon
+
+## Währung
+
+Einstellung für die Währung, die in den Events verwendet wird.
+
+## Register Name
+
+Einstellung für den Namen, der in den Registrierungsformularen angezeigt wird.
+
+## Timezone API Code
+
+Einstellung für den API-Code, der für die Zeitzone verwendet wird. Weitere Informationen finden Sie unter [Google Maps Timezone API](https://developers.google.com/maps/documentation/timezone/intro?hl=de).
+
+## Default Organizer Name
+
+Einstellung für den Namen des Standardorganisators, der für die Events verwendet wird.
+
+## Editor
+
+Einstellung für den Editor, der für die Bearbeitung der Events verwendet wird.
+
+## Empty Message
+
+Einstellung für die Nachricht, die angezeigt wird, wenn keine Termine vorhanden sind.

docs/01_event_date.md

@@ -0,0 +1,34 @@
+
+# Die Klasse `event_date`
+
+Typ `rex_yform_manager_dataset`. Greift auf die Tabelle `rex_event_date` zu.
+
+## Beispiel-Ausgabe eines Termins
+
+```php
+dump(event_date::get(3)); // Termin mit der id=3
+```
+
+## Zusätzliche Methoden
+
+| Methode                       | Beschreibung                                                                                                                         |
+|-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
+| `getName()`                   | Titel der Veranstaltung                                                                                                              |
+| `getDescription()`            | Beschreibungstext                                                                                                                    |
+| `getTeaser()`                 | Unformatierter Teaser-Text                                                                                                           |
+| `getCategory()`               | holt die passende Kategorie als `event_category`-Dataset.                                                                            |
+| `getLocation()`               | holt den passenden Veranstaltungsort als `event_location`-Dataset.                                                                   |
+| `getOfferAll()`               | holt die passenden Angebote / Preise als `event_offer`-Dataset                                                                       |
+| `getImage()`                  | gibt den Bild-Dateinamen aus dem Medienpool zurück                                                                                   |
+| `getMedia()`                  | gibt ein REDAXO-Medienobjekt des Bildes zurück                                                                                       |
+| `getIcs()`                    | gibt eine ICS-Datei zur Veranstaltung zurück                                                                                         |
+| `getDescriptionAsPlaintext()` | gibt die Veranstaltungsbeschreibung als Plaintext zurück                                                                             |
+| `getIcsStatus()`              | gibt den Status zurück, wie er im ICS-Format erwartet wird.                                                                          |
+| `getUid()`                    | gibt eine UID zurück, wie sie im ICS-Format erwartet wird. Wenn es die UID noch nicht gibt, wird sie automatisch erzeugt.            |
+| `getJsonLd()`                 | gibt den JSON-LD-Code zur Veranstaltung zurück                                                                                       |
+| `getStartDate()`              | gibt ein DateTime-Objekt zurück mit dem korrekten Startdatum in Abhängigkeit von den gewählten Optionen (ganztägig)                  |
+| `getEndDate()`                | gibt ein DateTime-Objekt zurück mit dem korrekten Enddatum, sofern vorhanden, in Abhängigkeit von den gewählten Optionen (ganztägig) |
+
+```php
+dump(event_date::get(3)->getCategory()); // Kategorie des Termins mit der id=3
+```

docs/02_event_category.md

@@ -0,0 +1,91 @@
+# Klasse event_category
+
+Die `event_category` Klasse repräsentiert eine Kategorie eines Events. Diese Klasse erweitert die
+`rex_yform_manager_dataset` Klasse und bietet spezifische Funktionen und Eigenschaften, die für die Verwaltung von
+Event-Kategorien notwendig sind.
+
+```php
+$eventCategory = new event_category();
+```
+
+## Methoden
+
+### getName()
+
+Gibt den Namen der Kategorie zurück.
+
+```php
+$name = $eventCategory->getName();
+```
+
+### getImage()
+
+Gibt das Bild der Kategorie zurück.
+
+```php
+$image = $eventCategory->getImage();
+```
+
+### getMedia()
+
+Gibt das rex_media Objekt des Bildes zurück.
+
+```php
+$media = $eventCategory->getMedia();
+```
+
+### getIcon()
+
+Gibt das Icon der Kategorie zurück.
+
+```php
+$icon = $eventCategory->getIcon();
+```
+
+### getPrice()
+
+Gibt den Preis der Kategorie zurück.
+
+```php
+$price = $eventCategory->getPrice();
+```
+
+### getUrl()
+
+Gibt die URL der Kategorie zurück.
+
+```php
+$url = $eventCategory->getUrl();
+```
+
+### getDateWhere($whereRaw)
+
+Gibt eine Sammlung von Event-Daten zurück, die auf einem bestimmten Kriterium basieren.
+
+```php
+$dates = $eventCategory->getDateWhere('startDate > NOW()');
+```
+
+### getRelatedDates($whereRaw)
+
+Gibt eine Sammlung von verwandten Event-Daten zurück.
+
+```php
+$relatedDates = $eventCategory->getRelatedDates('startDate > NOW()');
+```
+
+### getAttributes()
+
+Gibt ein Array von Attributen zurück.
+
+```php
+$attributes = $eventCategory->getAttributes();
+```
+
+### hasAttribute($needle)
+
+Überprüft, ob ein bestimmtes Attribut vorhanden ist.
+
+```php
+$hasAttribute = $eventCategory->hasAttribute('attributeName');
+```

docs/03_event_location.md

@@ -0,0 +1,84 @@
+# Dokumentation der `event_location` Klasse
+
+Die `event_location` Klasse repräsentiert einen Veranstaltungsort. Sie erbt von der `rex_yform_manager_dataset` Klasse und bietet zusätzliche Methoden zur Interaktion mit den Veranstaltungsorten.
+
+```php
+// Erstellt einen neuen Veranstaltungsort
+$location = new event_location();
+$location->setValue('name', 'Konzerthalle');
+$location->save();
+```
+
+## Methoden
+
+### `getFormattedAddress()`
+
+Gibt die formatierte Adresse zurück.
+
+```php
+$formattedAddress = $location->getFormattedAddress();
+```
+
+### `getName()`
+
+Gibt den Namen des Veranstaltungsorts zurück.
+
+```php
+$name = $location->getName();
+```
+
+### `getZip()`
+
+Gibt die Postleitzahl des Veranstaltungsorts zurück.
+
+```php
+$zip = $location->getZip();
+```
+
+### `getLocality()`
+
+Gibt die Ortschaft des Veranstaltungsorts zurück.
+
+```php
+$locality = $location->getLocality();
+```
+
+### `getCity()`
+
+Gibt die Stadt des Veranstaltungsorts zurück.
+
+```php
+$city = $location->getCity();
+```
+
+### `getCountryCode()`
+
+Gibt den Ländercode des Veranstaltungsorts zurück.
+
+```php
+$countryCode = $location->getCountryCode();
+```
+
+### `getLatLng()`
+
+Gibt die geographischen Koordinaten des Veranstaltungsorts zurück.
+
+```php
+$latLng = $location->getLatLng();
+```
+
+### `getLat()`
+
+Gibt den Breitengrad des Veranstaltungsorts zurück.
+
+```php
+$lat = $location->getLat();
+```
+
+### `getLng()`
+
+Gibt den Längengrad des Veranstaltungsorts zurück.
+
+```php
+$lng = $location->getLng();
+```

docs/04_event_date_offer.md

@@ -0,0 +1,62 @@
+# Dokumentation der `event_date_offer` Klasse
+
+Die `event_date_offer` Klasse repräsentiert ein Angebot für ein bestimmtes Event-Datum. Sie erbt von der `rex_yform_manager_dataset` Klasse und bietet zusätzliche Methoden zur Interaktion mit den Angeboten eines Event-Datums.
+
+```php
+// Erstellt ein neues Angebot für ein Event-Datum
+$offer = new event_date_offer();
+$offer->setValue('event_date_id', $eventDateId);
+$offer->setValue('price', $price);
+$offer->setValue('avaialabiility', $price);
+$offer->save();
+```
+
+## Methoden
+
+### `getUrl()`
+
+Gibt die URL des Angebots zurück.
+
+```php
+$url = $offer->getUrl();
+```
+
+### `getStatus()`
+
+Gibt den Status des Angebots zurück.
+
+```php
+$status = $offer->getStatus();
+```
+
+### `getPrice()`
+
+Gibt den Preis des Angebots zurück.
+
+```php
+$price = $offer->getPrice();
+```
+
+### `getCurrency()`
+
+Gibt die Währung des Angebots zurück.
+
+```php
+$currency = $offer->getCurrency();
+```
+
+### `getPriceFormatted()`
+
+Gibt den formatierten Preis des Angebots zurück.
+
+```php
+$priceFormatted = $offer->getPriceFormatted();
+```
+
+### `getAvailability()`
+
+Gibt die Verfügbarkeit des Angebots als schema.org kompatiblen Wert zurück.
+
+```php
+$availability = $offer->getAvailability();
+```