Merge pull request #32 from alexplusde/new-docs

Ausführlichere Doku und Hilfe für alle Rubriken
FriendsOfREDAXO · Dec 16, 2023 · b6fc05d · b6fc05d
2 parents 2319f2c + d9e55a5
commit b6fc05d
Show file tree

Hide file tree

Showing 15 changed files with 309 additions and 350 deletions.
diff --git a/README.md b/README.md
@@ -26,151 +26,6 @@ Im REDAXO-Installer das Addon `neues` herunterladen und installieren. Anschließ
 
 ![image](https://user-images.githubusercontent.com/3855487/209792457-b6f824dc-7fd8-4295-a7c7-2eab046d19c7.png)
 
-
-## Nutzung im Frontend
-
-### Die Klasse `neues_entry`
-
-Typ `rex_yform_manager_dataset`. Greift auf die Tabelle `rex_neues_entry` zu.
-
-#### Alle Einträge erhalten
-
-```php
-$entries = neues_entry::query()->find(); // YOrm-Standard-Methode zum Finden von Einträgen, lässt sich mit where(), Limit(), etc. einschränken und Filtern.
-$entries = neues_entry::findOnline(); // Alle Online-Einträge
-$entries = neues_entry::findByCategory($category_id [, $status]) // Alle Einträge einer Kategorie
-```
-
-#### Beispiel-Ausgabe einer News
-
-```php
-$entry = neues_entry::get(3); // News mit der id=3
-// dump($entry);
-
-echo $entry->getName();
-echo $entry->getAuthor();
-echo $entry->getDomain();
-echo $entry->getTeaser();
-echo $entry->getImage();
-echo $entry->getMedia();
-echo $entry->getDescriptionAsPlaintext();
-echo $entry->getDescription();
-echo $entry->getExternalUrl();
-echo $entry->getExternalLabel();
-echo $entry->getPublishDate();
-echo $entry->getPublishDateTime();
-echo $entry->getFormattedPublishDate($format); // IntlDateFormatter::FULL
-echo $entry->getFormattedPublishDateTime($format); // [IntlDateFormatter::FULL, IntlDateFormatter::SHORT]
-echo $entry->getStatus();
-echo $entry->getUrl(); // opt. URL-Schlüssel angeben
-```
-
-```php
-$categories = neues_entry::get(3)->getCategories();
-// dump($categories);
-
-foreach($categories as $category) {
-// ...
-}
-```
-
-### Die Klasse `neues_category`
-
-Typ `rex_yform_manager_dataset`. Greift auf die Tabelle `rex_neues_category` zu.
-
-#### Beispiel-Ausgabe einer Kategorie
-
-```php
-$category = neues_category::get(3); // News-Kategorie mit der id=3
-// dump($category);
-
-echo $category->getName();
-
-$entries =  $category->getEntries();
-
-foreach($entries as $entry) {
-    echo $entry->getName();
-// ...
-}
-```
-
-## URL2-Profile
-
-### News-Einträge mit einer Domain
-
-Mit der Methode `getUrl()` kann die URL des aktuellen News-Eintrags geholt werden. Dazu muss URL2 installiert sein und ein Profil mit dem Schlüssel `neues-entry-id` angelegt sein.
-
-Beispiel:
-
-![sunstrom de_redaxo_index php_page=url_generator_profiles func=edit id=1 list=5fa6c979(Surface Pro 7)](https://user-images.githubusercontent.com/3855487/209814035-f194a7d6-ae9a-463c-979a-7d8b542d239c.png)
-
-### News-Einträge im Kontext von YRewrite und Multidomains / mehreren Sprachen
-
-Die Methode `getUrl("neues-entry-id-domain-x")` erlaubt optional als Parameter anstelle von `neues-entry-id`. Somit lassen sich weitere Profile mit Filter je Domain erstellen und diese mit einem eigenen definitierten Schlüssel übergeben.
-
-## Nutzung im Backend: Die Terminverwaltung
-
-## RESTful API
-
-Die [Rest-API](https://github.com/yakamara/redaxo_yform/blob/master/docs/05_rest.md) 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:
-
-```
-    /neues/3/entry
-    /neues/3/category
-    /neues/3/location
-```
-
-### Endpunkt `entry`
-
-**Auslesen:** GET `example.org/rest/neues/3/date/?token=###TOKEN###`
-
-**Auslesen einzelner Termin**  GET `example.org/rest/neues/3//entry/7/?token=###TOKEN###` Eintrag der `id=7`
-
-### Endpunkt `category`
-
-**Auslesen:** GET `example.org/rest/neues/3/category/?token=###TOKEN###`
-
-**Auslesen einzelne Kategorie**  GET `example.org/rest/neues/3/category/7/?token=###TOKEN###` Eintrag der `id=7`
-
-### Endpunkt `location`
-
-**Auslesen:** GET `example.org/rest/neues/3/location/?token=###TOKEN###`
-
-**Auslesen einzelner Standort**  GET `example.org/rest/neues/3/location/7/?token=###TOKEN###` Eintrag  der `id=7`
-
-## Import
-
-### Import via CSV
-
-Neues basiert auf YForm. Importiere deine Einträge bequem per CSV, wie du es von YForm kennst.
-
-## Export
-
-### Export via CSV
-
-Neues basiert auf YForm. Exportiere deine Einträge bequem per CSV, wie du es von YForm kennst.
-
-
-## Editor für Textfeld "Inhalt" einbinden
-
-- Installiere den Editor deiner Wahl (zum Beispiel *redactor*)
-- lege im Editor dein Wunschprofil an
-- nach dem Speichern erscheint die Profilübersicht in *Redactor*
-- hier den Wert kopieren, der in der Spalte `Selektor` steht
-- im Hauptmenü unter `Aktuelles` >`Einstellungen` bei `Editor` den kopierten Eintrag einfügen - achte darauf, dass der Name ohne den Punkt davor eingefügt wird
-
-**Beispiel**  
-Im Redactor wurde das Profil mit dem Namen *Mein-Redactor-Profil* angelegt. Dann steht bei `Selector`: `.redactor-editor--Mein-Redactor-Profil`  
-In den Addon-Einstellungen von diesem Addon hier, muss dann bei Editor der Eintrag so aussehen: `class="redactor-editor--Mein-Redactor-Profil"`
-
-Für den Editor CK5 ist es: `class="form-control cke5-editor" data-profile="default" data-lang="de"`
-
-
-
 ## Lizenz
 
 MIT Lizenz, siehe [LICENSE.md](https://github.com/alexplusde/neues/blob/master/LICENSE)  
@@ -181,6 +36,10 @@ MIT Lizenz, siehe [LICENSE.md](https://github.com/alexplusde/neues/blob/master/L
 <http://www.alexplus.de>
 <https://github.com/alexplusde>
 
+**Paul Götz**  
+<http://www.alexplus.de>
+<https://github.com/schorschy>
+
 **Projekt-Lead**  
 [Alexander Walther](https://github.com/alexplusde)
 

diff --git a/docs/01_a_intro.md b/docs/01_a_intro.md
diff --git a/docs/01_b_import_export.md b/docs/01_b_import_export.md
@@ -0,0 +1,11 @@
+# Import
+
+## Import via CSV
+
+Neues basiert auf YForm. Importiere deine Einträge bequem per CSV, wie du es von YForm kennst.
+
+## Export
+
+## Export via CSV
+
+Neues basiert auf YForm. Exportiere deine Einträge bequem per CSV, wie du es von YForm kennst.
diff --git a/docs/01_c_migration.md b/docs/01_c_migration.md
@@ -0,0 +1,53 @@
+# Migration von REDAXO `FOR News Manager 3` und `alexplusde\Neues` v3 zu `FriendsOfREEAXO\Neues` v4
+
+## Warum der Wechsel?
+
+Das FOR-Addon News-Manager befindet sich nicht mehr in aktiver Entwicklung. Es wurde nur noch bis Ende 2022 gewartet. Potentielle Sicherheitslücken werden nicht mehr geschlossen.
+
+Um die Lücke zu schließen, wird das Addon `Neues` von @alexplus_de zu FriendsOfREDAXO gespendet. Die Weiterentwicklung des Neues ist gesichert. Es wird ständig an die neuesten REDAXO-Versionen angepasst und erweitert.
+
+Ein wesentlicher Vorteil gegenüber dem News Manager ist die Unterstützung von YForm. Damit lassen sich die News-Einträge und Kategorien komfortabel verwalten und erweitern, viele Funktionen von YForm und YOrm können genutzt werden.
+
+Wir danken Alex für die Bereitschaft, das Addon in die Hände von FriendsOfREDAXO zu geben, Alex bleibt Projekt-Lead des Addons. Sowie @schorschy @skerbis und @eace für die Unterstützung bei der Entwicklung.
+
+## Funktions-Parität und Unterschiede
+
+Was | News Manager `3.0.3` | Neues `^4.0`
+--- | --- | ---
+Letzte Weiterentwicklung und Wartung | ❌ 28. Dez. 2022 | ✅ aktuell
+REDAXO Core-Version | ab `^5.4` | ab `^5.15`
+PHP-Version | ab `^5.6` | ab `^7.2`
+Addon-Abhängigkeiten | URL ab `^2` | URL ab `^2`, YForm ab `^4`, YForm Field ab `^2`
+Position im Backend | `Addons > News Manager` | `Aktuelles` (oben)
+News-Übersicht | ✅ `News Manager > "News anlegen"` | ✅ `Aktuelles > Einträge`
+Kategorien | ✅ `News Manager > "Kategorien"` | ✅ `Aktuelles > Kategorien`
+Kommentare | ✅ als Plugin: `News Manager > "Kommentare"` | ❌ nein
+Autoren | ❌ nein | `Aktuelles > Autoren`
+Mehrsprachigkeit | ✅ `News Manager > (Sprache auswählen)` | ✅ `Aktuelles > Sprachen`
+Dokumentation | ✅ als Plugin | ✅ `Aktuelles > Hilfe`
+Einstellungen | ❌ nein | ✅ `Aktuelles > Einstellungen`
+WYSIWYG-Editor | ✅ ausschließlich `redactor2` | ✅ frei wählbar (`cke5`, `redactor`, `markitup`, `tinymce`)
+Backend-Sprachen | `de,en,es,se` | `de,en,es,se`
+RSS | ✅ ja | 🚧 in Arbeit
+Fertige Fragmente | ✅ ja | 🚧 in Arbeit
+Multi-Domain-Unterstützung | ❌ über Umwege | ✅ ja
+YOrm-Model | ❌ nein | ✅ ja (News-Einträge, Kategorien, Autoren, Sprachen)
+CSV-Import | ❌ nein | ✅ ja (via YForm)
+CSV-Export | ❌ nein | ✅ ja (via YForm)
+RESTful API | ❌ nein | ✅ ja (via YForm)
+
+## Migration von News Manager zu Neues 4
+
+1. Backup der Datenbank und des Dateisystems
+2. `Neues` installieren (`YForm`, `YForm Field`, `URL` müssen bereits installiert und aktiviert sein)
+3. Bestehende News-Einträge und Kategorien in Neues importieren
+4. Module, Templates und URL-Profile anpassen
+5. `News Manager` deinstallieren.
+
+## Migration von Neues 3 zu Neues 4
+
+Der Wechsel von Neues 3 zu 4 sollte vergleichsweise einfach vonstatten gehen. Im Zuge des Versionswechsels wurden lange verschobene, jedoch notwendige kleine Änderungen vorgenommen, die zwingend beachtet werden müssen:
+
+1. Vereinheitlichung von Methodennamen
+
+2. Vereinheitlichung von Datenbankfeldern und Feldnamen
diff --git a/docs/02_settings.md b/docs/02_settings.md
@@ -0,0 +1,15 @@
+# Einstellungen
+
+## Editor für Textfeld "Inhalt" einbinden
+
+* Installiere den Editor deiner Wahl (zum Beispiel *redactor*)
+* lege im Editor dein Wunschprofil an
+* nach dem Speichern erscheint die Profilübersicht in *Redactor*
+* hier den Wert kopieren, der in der Spalte `Selektor` steht
+* im Hauptmenü unter `Aktuelles` >`Einstellungen` bei `Editor` den kopierten Eintrag einfügen - achte darauf, dass der Name ohne den Punkt davor eingefügt wird
+
+**Beispiel**  
+Im Redactor wurde das Profil mit dem Namen *Mein-Redactor-Profil* angelegt. Dann steht bei `Selector`: `.redactor-editor--Mein-Redactor-Profil`  
+In den Addon-Einstellungen von diesem Addon hier, muss dann bei Editor der Eintrag so aussehen: `class="form-control redactor-editor--Mein-Redactor-Profil"`
+
+Für den Editor CK5 ist es: `class="form-control cke5-editor" data-profile="default" data-lang="de"`
diff --git a/docs/03_neues_entry.md b/docs/03_neues_entry.md
@@ -0,0 +1,46 @@
+# Die Klasse `neues_entry`
+
+Kind-Klasse von `rex_yform_manager_dataset`, damit stehen alle Methoden von YOrm Datasets zur Verfügung. Greift auf die Tabelle `rex_neues_entry` zu.
+
+> Es werden nachfolgend zur die durch dieses Addon ergänzte Methoden beschrieben. Lerne mehr über YOrm und den Methoden für Querys, Datasets und Collections in der [YOrm Doku](https://github.com/yakamara/yform/blob/master/docs/04_yorm.md)
+
+## Alle Einträge erhalten
+
+```php
+$entries = neues_entry::query()->find(); // YOrm-Standard-Methode zum Finden von Einträgen, lässt sich mit where(), Limit(), etc. einschränken und Filtern.
+$entries = neues_entry::findOnline(); // Alle Online-Einträge
+$entries = neues_entry::findByCategory($category_id [, $status]) // Alle Einträge einer Kategorie
+```
+
+## Beispiel-Ausgabe einer News
+
+```php
+$entry = neues_entry::get(3); // News mit der id=3
+// dump($entry);
+
+echo $entry->getName();
+echo $entry->getAuthor();
+echo $entry->getDomain();
+echo $entry->getTeaser();
+echo $entry->getImage();
+echo $entry->getMedia();
+echo $entry->getDescriptionAsPlaintext();
+echo $entry->getDescription();
+echo $entry->getExternalUrl();
+echo $entry->getExternalLabel();
+echo $entry->getPublishDate();
+echo $entry->getPublishDateTime();
+echo $entry->getFormattedPublishDate($format); // IntlDateFormatter::FULL
+echo $entry->getFormattedPublishDateTime($format); // [IntlDateFormatter::FULL, IntlDateFormatter::SHORT]
+echo $entry->getStatus();
+echo $entry->getUrl(); // opt. URL-Schlüssel angeben
+```
+
+```php
+$categories = neues_entry::get(3)->getCategories();
+// dump($categories);
+
+foreach($categories as $category) {
+// ...
+}
+```
diff --git a/docs/04_neues_category.md b/docs/04_neues_category.md
@@ -0,0 +1,21 @@
+# Die Klasse `neues_category`
+
+Kind-Klasse von `rex_yform_manager_dataset`, damit stehen alle Methoden von YOrm Datasets zur Verfügung. Greift auf die Tabelle `rex_neues_category` zu.
+
+> Es werden nachfolgend zur die durch dieses Addon ergänzte Methoden beschrieben. Lerne mehr über YOrm und den Methoden für Querys, Datasets und Collections in der [YOrm Doku](https://github.com/yakamara/yform/blob/master/docs/04_yorm.md)
+
+## Beispiel-Ausgabe einer Kategorie
+
+```php
+$category = neues_category::get(3); // News-Kategorie mit der id=3
+// dump($category);
+
+echo $category->getName();
+
+$entries =  $category->getEntries();
+
+foreach($entries as $entry) {
+    echo $entry->getName();
+// ...
+}
+```