Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Schreibkorrekturen & Verbesserungen #167

Merged
merged 15 commits into from
May 9, 2020
Merged

Schreibkorrekturen & Verbesserungen #167

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
c9a4e39
Schreibkorrekturen
May 8, 2020
8a7ed89
Update installer.md
alxndr-w May 8, 2020
b401ab1
Satzanfänge Groß
May 8, 2020
29c54f8
Merge branch 'master' of github.com:crydotsnake/docs
May 8, 2020
f105bc4
Textkorrektur
May 8, 2020
5d696a0
Schreibfehler im Console Befehl gefixt
May 8, 2020
c44b054
Datum im Quickstart Code geändert
May 8, 2020
7072b65
weitere Korrekturen
alxndr-w May 9, 2020
9d126f4
Weitere Verbesserungen & Anpassungen
May 9, 2020
76d984b
Weitere Verbesserungen & Korrekturen
May 9, 2020
ee833a2
„Ein“ durch „ein“ ersetzt.
May 9, 2020
864b434
Auf alten commit geswitcht
May 9, 2020
fd715b0
Merge branch 'master' of github.com:crydotsnake/docs
May 9, 2020
19fb197
Korrekturen und Anpassungen
May 9, 2020
97cbd3d
TODO: AddOn Screenshot hinzugefügt
May 9, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 30 additions & 30 deletions addon-assets.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# Assets

- [Über](#plugin)
- [Speicherort](#speicherort)
- [Dateien einbinden](#einbinden)
- [Cachebuster](#buster)
- [Javascripte / JS_IMMUTABLE, Async, JS_DEFERED](#javascripte)
- [Sass](#sass)
- [Javascript im Backend / rex:ready](#rexready)
* [Über](#plugin)
* [Speicherort](#speicherort)
* [Dateien einbinden](#einbinden)
+ [Cachebuster](#buster)
+ [Javascripte / JS_IMMUTABLE, Async, JS_DEFERED](#javascripte)
* [Sass](#sass)
* [Javascript im Backend / rex:ready](#rexready)

<a name="ueber"></a>

Expand All @@ -18,42 +18,42 @@ Als Assets bezeichnet man statische Dateien wie CSS-Files, Javascripte, Fonts od

## Speicherort

Assets werden innerhalb von REDAXO im `assets`-Ordner des AddOns abgelegt. Eine Installation, Reinstallation und Update eines AddOns kopiert die Dateien aus `assets` in den öffentlich zugänglichen Ordner `/assets/addons/addonname/`.
Assets werden innerhalb von REDAXO im `assets` -Ordner des AddOns abgelegt. Eine Installation, Reinstallation und Update eines AddOns kopiert die Dateien aus `assets` in den öffentlich zugänglichen Ordner `/assets/addons/addonname/` .

> Werden während der Entwicklung Änderungen an den Dateien innerhalb des AddOn-Ordners durchgeführt, muss ein neuer Kopiervorgang per Reinstallation angestoßen werden.

<a name="einbinden"></a>

## Dateien einbinden

Auf die Dateien eines Addons zeigt die Variable `$this` mittels der Klasse [rex_addon](http://www.redaxo.org/docs/master/class-rex_addon.html).
Auf die Dateien eines AddOns zeigt die Variable `$this` mittels der Klasse [rex_addon](http://www.redaxo.org/docs/master/class-rex_addon.html).

Die Dateien können in der Datei `boot.php` eingebunden werden. Hierfür liefert die Klasse [`rex_view`](http://www.redaxo.org/docs/master/class-rex_view.html) die Methoden `addCssFile` und `addJsFile`.
Die Dateien können in der Datei `boot.php` eingebunden werden. Hierfür liefert die Klasse [ `rex_view` ](http://www.redaxo.org/docs/master/class-rex_view.html) die Methoden `addCssFile` und `addJsFile` .

```php
``` php
//CSS-Datei einbinden
rex_view::addCssFile( /*Pfad zur Datei*/ );

//JS-Datei einbinden
rex_view::addJSFile( /*Pfad zur Datei*/ );
```

Den Pfad zu den Dateien erhält man per `getAssetsUrl`.
Den Pfad zu den Dateien erhält man per `getAssetsUrl` .

```php
``` php
$this->getAssetsUrl('styles.css') // wird zu /assets/addons/addonname/styles.css
```

Beispiel:

```php
``` php
rex_view::addCssFile( $this->getAssetsUrl('styles.css') );
rex_view::addJsFile( $this->getAssetsUrl('script.js') );
```

Es ist auch möglich die Assets nur auf bestimmten Seiten im Backend enzubinden. Hierzu kann das folgende Snippet behilflich sein:

```php
``` php
// Ermitteln welche Backendseite aufgerufen ist:
if (rex::isBackend() && rex_be_controller::getCurrentPage() == 'addonkey/unterseite') {

Expand All @@ -66,32 +66,32 @@ if (rex::isBackend() && rex_be_controller::getCurrentPage() == 'addonkey/unterse

### Cachebuster

REDAXO liefert selbst einen Cachebuster. Eigene Lösungen hierfür sind nicht erforderlich. Der Buster wird automatisch gesetzt. Beispiel: `index.php?asset=../assets/addon/skript.min.js&amp;buster=1566304624`
REDAXO liefert selbst einen Cachebuster. Eigene Lösungen hierfür sind nicht erforderlich. Der Buster wird automatisch gesetzt. Beispiel: `index.php?asset=../assets/addon/skript.min.js&amp;buster=1566304624`

<a name="javascripte"></a>

### Javascripte (JS_IMMUTABLE, Async, JS_DEFERED)

rex_view::addJsFile bietet weitere Funktionen um das Caching sowie das Ladeverhalten der Javascripte zu beinflussen.
rex_view::addJsFile bietet weitere Funktionen um das Caching sowie das Ladeverhalten der Javascripte zu beeinflussen.

Hier ein Beispiel mit allen möglichen Optionen:

```js
``` js
rex_view::addJsFile(
rex_url::addonAssets('my_addon', 'js/myscript.min.js'),
[rex_view::JS_IMMUTABLE => false, rex_view::JS_ASYNC => true, rex_view::JS_DEFERED => true]
rex_url::addonAssets('my_addon', 'js/myscript.min.js'),
[rex_view::JS_IMMUTABLE => false, rex_view::JS_ASYNC => true, rex_view::JS_DEFERED => true]
);
```

<a name="sass"></a>

## Sass

Es ist möglich `.scss` Dateien mit der Klasse `rex_scss_compiler()` zu kompilieren. Es bietet sich an, solche Dateien in einem separaten Ordner anzulegen. Kompilierte Versionen der Dateien sollten bei Bereitstellung des AddOns bereis im Assets-Ordner vorliegen. Die scss-Dateien sollten nur für Anpassungen oder Fehlerbehebungen durch REDAXO neu kompiliert werden.
Es ist möglich `.scss` Dateien mit der Klasse `rex_scss_compiler()` zu kompilieren. Es bietet sich an, solche Dateien in einem separaten Ordner anzulegen. Kompilierte Versionen der Dateien sollten bei Bereitstellung des AddOns bereits im Assets-Ordner vorliegen. Die scss-Dateien sollten nur für Anpassungen oder Fehlerbehebungen durch REDAXO neu kompiliert werden.

Der nachfolgend kommentierte Code für die `boot.php` zeigt, wie man die Kompilierung bei aktiviertem DEBUG-Mode ausführt.
Der nachfolgend kommentierte Code für die `boot.php` zeigt, wie man die Kompilierung bei aktiviertem Debug-Modus ausführt.

```php
``` php
// Befinden wir uns im Backend und ist ein User angemeldet?
if (rex::isBackend() && rex::getUser())
{
Expand All @@ -118,23 +118,23 @@ if (rex::isBackend() && rex::getUser())

## Javascript im Backend / Das Event: rex:ready

Da REDAXO im Backend PJAX nutzt, verwendet es ein eigenes Event um den ready-Status zu liefern. Daher sollte anstelle des JQuery-`document:ready` Events das `rex:ready` event als Auslöser für eigene Skripte verwendet werden.
Das `rex:ready`-Event greift auch, wenn PJAX nicht im Einsatz ist und kann daher immer verwendet werden.
Da REDAXO im Backend PJAX nutzt, verwendet es ein eigenes Event um den ready-Status zu liefern. Daher sollte anstelle des JQuery- `document:ready` Events das `rex:ready` event als Auslöser für eigene Skripte verwendet werden.
Das `rex:ready` -Event greift auch, wenn PJAX nicht im Einsatz ist und kann daher immer verwendet werden.

Anwendung:

```js
``` js
$(document).on('rex:ready', function() {
// eigener Code
// eigener Code
});
```

Beispiel:

Das findet sich so zum Beispiel im be_style-Plugin. `container` ist immer der Container, der ausgetauscht wurde. Initial bei document:ready ist es der <body>.
Das findet sich so zum Beispiel im be_style-Plugin. `container` ist immer der Container, der ausgetauscht wurde. Initial bei `document:ready` ist es der `<body>` .

```js
$(document).on('rex:ready', function (event, container) {
``` js
$(document).on('rex:ready', function(event, container) {
container.find('.selectpicker').selectpicker();
});
```
99 changes: 73 additions & 26 deletions addon-entwicklung.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,30 +2,30 @@

* [Minimale Erfordernisse](#anker-minimal)
* [package.yml](#anker-package-yml)
* [Erforderliche Angabe](#anker-yaml-required)
* [Optionale Angabe](#anker-yaml-optional)
+ [Erforderliche Angabe](#anker-yaml-required)
+ [Optionale Angabe](#anker-yaml-optional)
* [Optionale Dateien](#anker-files)
* [Weitere nützliche Dateien](#anker-useful-files)
* [Optionale Ordner](#anker-folders)
* [Weitere nützliche Ordner](#anker-useful-folders)
* [Software](#anker-software)
* [Fragen und Antworten](#anker-faq)
* [MarkDown](#anker-faq-markdown)
* [Yaml](#anker-faq-yaml)
+ [MarkDown](#anker-faq-markdown)
+ [Yaml](#anker-faq-yaml)

<a name="anker-minimal"></a>

## Minimale Erfordernisse

Jedes AddOn hat einen eigenen Ordner mit einem einzigartigem und möglichst beschreibendem Namen.

[@TODO:][SCREENSSHOT ORDNER]
![AddOn-Ordner](/assets/v5.2.0-Addon-Entwicklung-Ordner.png)

AddOns werden bei der Installation in REDAXO registriert, dazu sind einige Basisinformationen notwendig.
Diese Basisinformationen werden in der Datei `package.yml` abgelegt. Prinzipiell sind mit dieser Datei
alle Erfordernisse erfüllt, dass REDAXO ein AddOn installieren kann.

[@TODO:][SCREENSSHOT ODER CODE VON PACKAGE.YML]
[@TODO:][SCREENSSHOT ODER CODE VON PACKAGE. YML]

Da in der Datei `package.yml` direkt Referenzen zu Dateien innerhalb des AddOns notiert werden können, können in
der Folge weitere Dateien notwendig werden. Mehr zu erforderlichen und optionalen Angaben in dieser Datei
Expand All @@ -44,7 +44,7 @@ Bei Bedarf können dort weitere Komponenten referenziert werden.

Die einzigen erforderlichen Angaben innerhalb der Datei sind Folgende:

```yaml
``` yaml
package: test
version: '1.0'
```
Expand All @@ -66,60 +66,82 @@ frei, beliebige Datein in einem AddOn bereit zu stellen.
Nachfolgend werden die Dateien und Ordner gelistet, nach denen innerhalb eines installierten AddOns von REDAXO automatisch gesucht wird:

* **help.php**

Ist eine Datei `help.php` im AddOn-Ordner enthalten wird diese automatisch im AddOn-Manager eingebunden und die Ausgabe angezeigt.
Ist die Datei nicht enthalten wird im AddOn-Manager ein Hinweis angezeigt, daß die Datei fehlt.
Es sollten Hinweise zur Funktionalität des AddOns enthalten sein, auch Versionshinweise bzw. Changelog können angezeigt werden.

* **install.php**

Ist eine Datei `install.php` im AddOn-Ordner enthalten wird diese automatisch bei der AddOn-Installation ausgeführt.
Die dort integrierte Funktionalität kann viele Aktionen umfassen und ist dem Entwickler somit vollkommen freigstellt.
Übliche Aktionen umfassen das Erstellen von Ordnern, das Kopieren bzw. Erstellen von Dateien und Datenbankoperationen.

* **install.sql**

Ist eine Datei `install.sql` im AddOn-Ordner enthalten wird diese automatisch bei der AddOn-Installation ausgeführt.
Entwickler sollten sicherstellen, daß möglicherweise vorhandene Daten nicht überschrieben oder gelöscht werden.
Übliche Aktionen sind die Erstellung von Tabellen in der Datenbank, aber es können auch Daten eingefügt werden oder alle erdenklichen SQL-Befehle integriert werden.

* **update.php**

Ist eine Datei `update.php` im AddOn-Ordner enthalten wird diese automatisch bei einem AddOn-Update ausgeführt.
Auslöser für die Anzeige eines verfügbaren Updates ist die Version in der Datei `package.yml` im Vergleich zu der in einem Upload oder Download.

* **uninstall.php**

Ist eine Datei `uninstall.php` im AddOn-Ordner enthalten wird diese automatisch bei der AddOn-Deinstallation ausgeführt.
Übliche Aktionen sind das Löschen von Dateien und Ordnern die zum Cachen angelegt wurden.
Einige AddOns führen beim Deinstallieren auch Datenbankaktionen durch.
Ein Entwickler sollte berücksichtigen, daß ein Löschen von Daten trotz Deinstallation des AddOns ungewünscht sein kann.

* **boot.php**
Ist eine Datei `boot.php` im AddOn-Ordner enthalten wird diese automatisch bei jeder REDAXO Instanz aufgerufen,
sofern das Addon installiert und aktiviert ist.

Ist eine Datei `boot.php` im AddOn-Ordner enthalten wird diese automatisch bei jeder REDAXO Instanz aufgerufen,
sofern das AddOn installiert und aktiviert ist.
Übliche Verwendungen sind die Definition von Variablen und die Einbindung von Dateien.
Funktionell kommt dieser Datei eine hohe Wichtigkeit zu, dennoch ist die Einbindung optional und nicht unbedingt notwendig.

* **README.md**

Der Inhalt der Datei `README.md` wird durch REDAXO im AddOn-Manager ausgegeben, wenn die Datei `help.php` nicht vorhanden ist.
Ausserdem empfiehlt sich diese Datei, wenn das AddOn als Repository auf GitHub gehostet wird.
Außerdem empfiehlt sich diese Datei, wenn das AddOn als Repository auf GitHub gehostet wird.

<a name="anker-useful-files"></a>

## Weitere nützliche Dateien

* **LICENSE.md**

Eine automatische Nutzung durch REDAXO ist nicht gegeben, allerdings empfiehlt sich diese Datei, wenn das AddOn als Repository auf GitHub gehostet wird.
Ausserdem ist natürlich der Zweck der Datei, über die Lizenz des AddOns zu informieren auch innerhalb von REDAXO wichtig,
Außerdem ist natürlich der Zweck der Datei, über die Lizenz des AddOns zu informieren auch innerhalb von REDAXO wichtig,
selbst wenn eine automatische Anzeige nicht vorgesehen ist.

* **CHANGELOG.md**

Eine automatische Nutzung durch REDAXO ist nicht gegeben, allerdings empfiehlt sich diese Datei, wenn das AddOn als Repository auf GitHub gehostet wird.
Ausserdem ist natürlich der Zweck der Datei, über Änderungen zwischen Versionen des AddOns zu informieren auch innerhalb von REDAXO wichtig,
Außerdem ist natürlich der Zweck der Datei, über Änderungen zwischen Versionen des AddOns zu informieren auch innerhalb von REDAXO wichtig,
selbst wenn eine automatische Anzeige nicht vorgesehen ist.

* **config.yml**

Eine Datei "config.yml" kann einfach eingelesen werden und an gewünschter Stelle im AddOn eingebunden werden.
Hier können umfangreiche Definitionen notiert werden, das AddOn "markitup" ist ein gutes Beispiel.
Da das Einlesen der Datei nicht automatisch geschieht, ist die Namensgebung nicht festgelegt. Somit könnt man auch z.B. folgende Dateien anlegen:
Da das Einlesen der Datei nicht automatisch geschieht, ist die Namensgebung nicht festgelegt. Somit könnt man auch z. B. folgende Dateien anlegen:

```
```text
config_frontend.yml
config_backend.yml
```

Der PHP-Code um eine Datei einzulesen lautet beispielsweise:

```php


``` php
$markItUpButtons = rex_file::getConfig(rex_path::addon('markitup', 'config.yml'));
```
```


<a name="anker-folders"></a>

Expand All @@ -138,10 +160,14 @@ Nachfolgend werden die Dateien und Ordner gelistet, nach denen innerhalb eines i
## Software

* Editoren
* **Frei verfügbare Markdown-Editoren:**
+ **Frei verfügbare Markdown-Editoren:**

@TODO
* **Kommerzielle Markdown-Editoren:**

+ **Kommerzielle Markdown-Editoren:**

@TODO

@TODO

<a name="anker-faq"></a>
Expand All @@ -152,42 +178,63 @@ Nachfolgend werden die Dateien und Ordner gelistet, nach denen innerhalb eines i
**MarkDown**

* **Welches Dateiformat haben Dateien mit der Endung `.md` ?**

Dateien mit der Endung `md` enhalten Inhalt in der MarkDown-Syntax.
Es handelt sich dabei um normalen Text, der mit einigen wenigen Mitteln für eine formatierte Ausgabe vorbereitet werden kann.
Mehr Details dazu hier: [Wikipedia:Markdown](https://de.wikipedia.org/wiki/Markdown)
Mehr Details dazu hier: [Wikipedia: Markdown](https://de.wikipedia.org/wiki/Markdown)

* Was ist der Unterschied zwischen MarkUp und MarkDown?

@TODO

* Was ist der Unterschied zwischen MarkUp und MarkItUp?

@TODO

* **Warum wird die Markdown-Syntax in so vielen Dateien verwendet, geht das nicht in Text-Dateien?**

MarkDown hat sich zum defacto-Standard entwickelt, da es auf gihub.com verwendet wird, wo auch viele REDAXO-AddOns verwaltet werden.
Auch innerhalb von REDAXO findet das Format in einigen optional installierbaren Editoren Verwendung.
Markdown erlaubt die Integration von Bildern und Hyperlinks, wie auch die lesefreundliche Formatierung von Text, und hat
dem einfachen Text-Format gegenüber eine Menge Vorteile.

* **Warum wird die Markdown-Syntax in so vielen Dateien verwendet, geht das nicht im HTML-Format?**

MarkDown hat sich zum defacto-Standard entwickelt, da es auf gihub.com verwendet wird, wo auch viele REDAXO-AddOns verwaltet werden.
Auch innerhalb von REDAXO findet das Format in einigen optional installierbaren Editoren Verwendung.
Die Bereitstellung von Inhalten per HTML ist durchaus möglich und jedem freigestellt, allerdings tauchen dort Gestaltungsfragen auf,
Die Bereitstellung von Inhalten per HTML ist durchaus möglich und jedem freigestellt, allerdings tauchen dort Gestaltungsfragen auf,
die bei Markdown nicht gegeben sind. HTML ist bei den Optionen umfangreicher aber auch schwieriger zu erlernen.
Das Format Markdown stellt limitierte Bereicherungen für Dateien bereit, die gerne für Standard-Dateien wie README, LICENSE und CHANGELOG
verwendet werden und zuvor üblicherweise als reine Text-Dateien bereitgestellt wurden.

* **Wo gibt es eine Erklärung zum Markdown-Standard?**
Eine Beschreibung in englischer Sprache vom Autor des Standards findet man hier: [MarkDown:Syntax](https://daringfireball.net/projects/markdown/syntax).
[@TODO: besseren Link] Eine deutschsprachige Beschreibung vom REDAXO-Team findet man hier: [MarkDown:Vorlage](https://redaxo.org/doku/master/_vorlage).

Eine Beschreibung in englischer Sprache vom Autor des Standards findet man hier: [MarkDown: Syntax](https://daringfireball.net/projects/markdown/syntax).
[@TODO: besseren Link] Eine deutschsprachige Beschreibung vom REDAXO-Team findet man hier: [MarkDown: Vorlage](https://redaxo.org/doku/master/_vorlage).

* **Wo findet man die Backticks zur Auszeichnung von Kode in Markdown-Dateien?**
* Es handelt sich bei dem Backtick um den französischen Akzent „Gravis“.
Auf einer deutschen Tastatur findet man diesen rechts neben den Ziffern und dem `ß`.
+ Es handelt sich bei dem Backtick um den französischen Akzent „Gravis“.

Auf einer deutschen Tastatur findet man diesen rechts neben den Ziffern und dem `ß` .

Man drückt die Tasten `Umschalten` und die Akzent-Taste gleichzeitig und anschließend die Leerzeichen Taste.
[@TODO: Screenshot Keyboard mit markierten Tasten]
* In manchen Editoren braucht man die Backticks nicht selbst zu schreiben, sondern kann sie über Buttons einfügen.

+ In manchen Editoren braucht man die Backticks nicht selbst zu schreiben, sondern kann sie über Buttons einfügen.

Es gibt auch spezielle Editoren für MarkDown-Dateien.
* Eine etwas umständliche, aber letztendlich einfache Methode ist, das Zeichen in einer Datei abzuspeichern und zu kopieren.

+ Eine etwas umständliche, aber letztendlich einfache Methode ist, das Zeichen in einer Datei abzuspeichern und zu kopieren.

Meistens kann das Zeichen in SQL-Dateien oder fertigen Markdown-Dateien gefunden werden, hier kann das Zeichen natürlich auch kopiert werden, bitteschön: **`**

* **Welche Editoren für Markdown kann das REDAXO-Team empfehlen?**

Siehe unter [Software](#anker-software)

<a name="anker-faq-yaml"></a>
**Yaml**

* **Welches Dateiformat haben Dateien mit der Endung `.yml` ?**

@TODO
Loading