Quickstart
==========

Sinn und Zweck
--------------

realURL2 übernimmt die Aufgabe, aus einer Artikel-ID und einer Sprach-ID eine
ansprechende URL zu erzeugen, die insbes. die Struktur der Seite repräsentiert.

Zu diesem Zweck werden vor dem Namen eines Artikels in der URL (z. B.
``team.html``) alle Kategorien eingefügt. Liegt der Artikel "Team" also in der
Kategorie

::

  (Root) > Unternehmen > Wir über uns

so wird die erzeugte URL wie folgt aussehen:

::

  /unternehmen/wir-ueber-uns/team.html

Über eine entsprechende Server-Konfiguration (mod_rewrite) wird beim
Aufrufen dieser URL (die auf eine gar nicht existierende Datei zeigt) die
``index.php`` von SallyCMS aufgerufen. realURL2 kümmert sich dann um das
Erkennen und Übersetzen der Adresse in den eigentlichen Artikel. Von dieser
Übersetzung bekommt SallyCMS selbst gar nichts mit.

Installation
------------

Da das AddOn zwei Abhängigkeiten hat, müssen diese ebenfalls installiert und
aktiviert werden, bevor realURL2 genutzt werden kann.

#. Kopieren Sie die drei AddOn-Verzeichnisse nach **sally/addons/**.
#. Loggen Sie sich im Backend ein und gehen Sie auf die AddOn-Seite.
#. Installieren Sie die AddOns nun in der folgenden Reihenfolge:

   #. Developer Utils
   #. Global Settings
   #. realURL2

#. Überprüfen Sie die Einstellungen, indem Sie der Anleitung im :doc:`userguide`
   folgen.
#. Sie sind fertig! Nun sollten in ihrem Frontend bereits saubere URLs
   erscheinen.

Nutzung
-------

Die Hinweise zur Bedienung wurden in den :doc:`userguide` ausgelagert.

Aliase
------

Zu jedem Artikel (und jeder Kategorie) kann ein Alias angegeben werden (auf der
Metadaten-Seite von Artikeln im Backend). Dabei gilt folgende einfache
Konvention:

**foo**
  ersetzt den automatisch erzeugten Namen durch **foo**.

**/foo**
  erzeugt eine Kurz-URL, d.h. dass statt ``example.com/cat1/cat2/foo``
  nun ``example.com/foo`` erzeugt wird. Dies gilt auch für alle darin
  enthaltenen Artikel.

**//foo.com**
  wechselt die Domain auf ``foo.com``, es wird für diesen Teilbaum
  der Struktur die Domain ``foo.com`` verwendet.

Ein Alias darf **höchstens 256 Zeichen** lang sein. Eine längere und
langweiligere Erklärung gibt es am Ende dieser Seite.

Multi-Domain-System
-------------------

realURL2 wurde implementiert, um eine native Lösung für Projekte zu haben, die
das Umleiten einzelner Kategorien auf andere Domains unterstützt. Die dafür
notwendige Konfiguration integriert sich nahtlos in die Funktionen für
Alias-Namen.

Mehr Informationen gibt es auf der :doc:`Multi-Domain-System-Seite <domains>`.

Begrifflichkeiten
-----------------

*Startartikel*
  Der Startartikel ist derjenige Artikel, der beim Aufruf einer Kategorie
  angezeigt wird. Meist heißt er wie die Kategorie und ist in der Liste der
  Artikel der erste. Wir meinen also nichts anderes als das, was SallyCMS unter
  dem Startartikel versteht. Nicht zu verwechseln mit dem Seitenstartartikel,
  der den Artikel für die URL ``"/"`` angibt.

*Fragment*
  An einer erzeugten Adresse sind der eigentliche Artikel sowie alle Kategorien
  in seinem Pfad beteiligt. Jedes Element trägt zur URL ein sog. "Fragment"
  bei, das (wenn nicht anders angegeben) dem Namen des Elements entspricht.
  Fragmente können beliebig geändert werden und über spezielle Eingaben
  Einfluss auf die URL-Erzeugung nehmen. Fragmente dürfen höchstens 64 Zeichen
  umfassen.

*Alias-Name*
  Wenn für ein Fragment eine andere Bezeichnung als der Artikelname angegeben
  wird, spricht man von einem Alias-Namen. Zum Beispiel könnte der Artikel
  "Unternehmen" den Alias-Namen "wir-ueber-uns" erhalten.

*Kurz-URL*
  Eine Kurz-URL ist ein Fragment, das mit einem Schrägstrich beginnt. Damit
  hängt sich der Artikel (und alle Kind-Artikel) in den Root der Website-URLs.
  Beispielsweise könnte die Kategorie ``"Jobs"`` in ``"Unternehmen > Karriere"``
  das Fragment ``"/jobs"`` erhalten. Die für diese Kategorie erzeugten Adressen
  lauten dann nur noch ``http://www.example.com/jobs``.

*Domain-URL*
  Eine Domain-URL ist ein Fragment, das mit zwei Schrägstrichen beginnt und
  damit den Struktur-Teilbaum einer Website auf eine andere Domain zeigen
  lässt. So würde das Fragment ``"//jobs.example.com"`` beim Artikel aus der
  obigen Begriffserklärung dazu führen, dass die erzeugte Adresse die Form
  ``http://jobs.example.com/`` annimmt.
