Konfiguration benutzerspezifischer Advanced URLs

FirstSpirit bietet Schnittstellen und eine Referenz-Implementierung („Advanced URL Creator“), welche die Möglichkeit bieten, unterschiedliche Pfadstrategien zur URL-Erzeugung in FirstSpirit einzubinden. Die Erzeugung der URLs wird dazu an eine UrlFactory delegiert. Neben der Referenz-Implementierung zur Verbesserung der URL-Erzeugung (Einstellung „Advanced URLs“ in den Projekteigenschaften) können diese Schnittstellen verwendet werden, um neue, kundenspezifische Pfadstrategien zu implementieren und als Modul in FirstSpirit zu integrieren.

Alle Klassen, die das Interface UrlFactory implementieren, erlauben die Übergabe von Parametern und Werten zur Konfiguration der URL-Erzeugung. Um diese Daten, die der Methode UrlFactory.init(…) zur Verfügung gestellt werden, zu persistieren, werden klasseninterne Felder zur Speicherung der Konfigurationseinstellung definiert:

public class UrlCreatorExample implements UrlFactory {
     
    // Felder für Persistenz während des Objektlebenslaufs.
    private PathLookup _pathLookup;
    private boolean _useWelcomeFilenames;

    public void init(final Map<String, String> settings, final PathLookup pathLookup) {   
        _pathLookup = pathLookup;
        _useWelcomeFilenames = settings.get("usewelcomefilenames");
        ....
   }
   ...
}

Die Methode init(…) wird jeweils nach Instanziierung eines UrlFactory-Objekts aufgerufen, um das Objekt mit, während einer Generierung, unveränderlichen Daten zu initialisieren. Beim Aufruf werden als Parameter ein Map-Objekt, mit den Konfigurationsparametern sowie ein PathLookup-Objekt, das zur Abfrage von benutzerdefinierten URLs auf Store-Verzeichnissen verwendet werden kann, bereitgestellt.

Anwendungsbeispiel siehe Referenz-Implementierung „Advanced URL Creator“.

Übergabe der Konfigurationsparameter

Sämtliche Konfigurationsparameter müssen entweder über ein Auftrags-Skript definiert werden, das VOR dem eigentlichen Generierungsauftrag ausgeführt wird oder über die Konfigurationseinstellungen in der module.xml-Datei.

Übergabe per Skript:

Übergabe per vorgelagertem Skript in der Auftragsverwaltung (in den Projekteigenschaften), z. B.:

context.setProperty("#urlCreatorSettings", Collections.singletonMap("usewelcomefilenames", "true")); 

Sollen mehrere Parameter übergeben werden, erfolgt die Übergabe über eine Map:

factorySettings = new HashMap(); 
factorySettings.put("useregistry","true");  
factorySettings.put("useLowercase","true");  
factorySettings.put("removedeleted","true");  
context.setProperty("#urlCreatorSettings", factorySettings); 

Auf die gleiche Weise können weitere Standard-Konfigurationsparameter und andere benutzerdefinierte Parameter übergeben werden. Diese müssen dann an die entsprechenden URL-Factory-Implementierung (s.o.) übergeben werden.

Übergabe per module.xml bzw. module-isolated.xml:
Statt der Übergabe über ein vorgelagertes Skript können die Konfigurationsparameter auch in der Datei module.xml (legacy) bzw. module-isolated.xml innerhalb der <configuration>-Tags definiert werden, z. B.:

<module>
    <name>myConfiguredUrlCreator</name>
    <version>0.1</version>
    <description>my configured URL Creator</description>
    <vendor>myCompanyName</vendor>
   
    <components>
        <public>
            <name>ConfiguredAdvancedUrlCreator</name>
            <class>de.espirit.firstspirit.generate.UrlCreatorSpecification</class>
            
            <configuration>
                <UrlFactory>de.espirit.firstspirit.generate.AdvancedUrlFactory</UrlFactory>
                    <useLowercase>true</useLowercase>
                    <useWelcomeFilenames>true</useWelcomeFilenames>
            </configuration>

        </public>
    </components>

</module> 

Standard-Konfigurationsparameter

Das FirstSpirit-Framework wertet einige Standard-Parameter aus:

• useWelcomeFileNames
• stripWelcomeFileNames
• useIRIs
• useRegistry
• readOnlyRegistry
• removeDeleted
• useLowercase
• selfLink

(Groß-/Kleinschreibung der Parameter ist nicht relevant, d. h. useIRIs, UseIris oder UseIRIs sind derselbe Parameter.)

useWelcomeFileNames

Der Parameter „useWelcomeFileNames“ kann zur Konfiguration von Startseitenreferenzen verwendet werden.  

context.setProperty("#urlCreatorSettings", Collections.singletonMap("usewelcomefilenames", "true"));

Dieser Parameter wird in der Referenz-Implementierung Advanced Url Creator verwendet (s.o.).

Mögliche Werte:

• true oder yes oder Wert nicht gesetzt (Standardwert):
  Nur der erste HTML-Ausgabekanal verwendet Welcomefilenames.
• false oder no:
  Es werden keine Welcomefilenames verwendet.
• all:
  Alle HTML-Ausgabekanäle verwenden Welcomefilenames.
  Eine solche Konfiguration kann zu identischen URLs führen, siehe (*).
• Kommaseparierte Liste von Ausgabekanälen:
  Alle aufgelisteten Kanäle verwenden Welcomefilenames.
  Eine solche Konfiguration kann zu identischen URLs führen, siehe (*).

true oder yes oder Wert nicht gesetzt (Standardwert):
Wird der Parameter mit dem Wert true übergeben (Standardwert), wird für Seitenreferenzen, die als Startseite eines Ordners der Struktur-Verwaltung markiert sind, der Dateiname index.* beim Erzeugen einer Advanced URL geliefert (unabhängig vom Anzeigenamen oder dem Dateinamen aus dem Eigenschaftsdialog).

Das gilt für den ersten HTML-Ausgabekanal (z.B. html).

Aus

../de/startpage/firstspirit_hybrid_cms.html
../en/startpage/firstspirit_hybrid_cms.html

bei der Standard-URL-Erzeugung wird im Advanced-Modus mit „useWelcomeFileNames“:

../Startseite/index.html
../Startpage/index.html

Für alle weiteren Ausgabekanäle (z.B. php) und für Seitenreferenzen, die nicht als Startseite gekennzeichnet sind,werden die URLs weiterhin basierend auf dem Anzeigenamen der Seitenreferenz erzeugt (wobei die Leerzeichen durch ein „-“-Zeichen ersetzt werden).

false oder no:
Wird der Parameter mit dem Wert false übergeben, werden für alle Seitenreferenzen, unabhängig ob Startseite oder nicht, die URLs basierend auf dem Anzeigenamen der Seitenreferenz erzeugt (wobei die Leerzeichen durch ein „-“-Zeichen ersetzt werden):

../Startseite/FirstSpirit-Hybrid-CMS.html
../Startpage/FirstSpirit-Hybrid-CMS.html

all:
Wird der Parameter mit dem Wert all übergeben, wird für Seitenreferenzen, die als Startseite eines Ordners der Struktur-Verwaltung markiert sind, der Dateiname index.* beim Erzeugen einer Advanced URL geliefert (unabhängig vom Anzeigenamen oder dem Dateinamen aus dem Eigenschaftsdialog)

Das gilt für alle im Projekt vorhandenen HTML-Ausgabekanäle.

Eine solche Konfiguration kann zu identischen URLs führen, siehe (*).

Liste von Ausgabekanälen:
Wird dem Parameter eine Liste von Ausgabekanälen übergeben, wird für Seitenreferenzen, die als Startseite eines Ordners der Struktur-Verwaltung markiert sind, der Dateiname index.* beim Erzeugen einer Advanced URL geliefert (unabhängig vom Anzeigenamen oder dem Dateinamen aus dem Eigenschaftsdialog).

Das gilt für alle HTML-Ausgabekanäle, die in der Liste angegeben sind.

Angegeben wird hier der Name des Vorlagensatzes (Vorlagensatz-Name: siehe Vorlagensätze (→Dokumentation für Administratoren)).

Eine solche Konfiguration kann zu identischen URLs führen, siehe (*).

(*) Bei einer Konfiguration, die für alle oder mehrere Ausgabekanäle „WelcomeFileNames“ verwendet, können mehrere index.*-Dateien in einem Ordner liegen (z. B. „/index.html“ und „/index.php“). Werden dann zusätzlich die Erweiterungen /index.* über „stripWelcomeFileNames“ entfernt, entstehen identische URLs. Von einer solchen Konfiguration wird dringend abgeraten!

stripWelcomeFileNames

Der Parameter „stripWelcomeFileNames“ ist nur relevant, wenn die verwendete URL-Pfadstrategie auch den Konfigurationsparameter useWelcomeFileNames verwendet. Mithilfe des Parameters „stripWelcomeFileNames“ kann die durch „useWelcomeFileNames“ ergänzte Extension „/index.*“ aus der Advanced URL entfernt werden (aber nicht aus dem Dateinamen, unter dem die Seite im Dateisystem abgelegt wird).

factorySettings = new HashMap(); 
factorySettings.put("usewelcomefilenames", "true");  
factorySettings.put("stripwelcomefilenames", "true");  
context.setProperty("#urlCreatorSettings", factorySettings);  

Mögliche Werte:

• true oder yes oder Wert nicht gesetzt (Standardwert):
  /index.* (üblicherweise „/index.html“) wird gekürzt.
• false oder no:
  URL wird nicht gekürzt
• Liste von Erweiterungen:
  Alle aufgelisteten Erweiterungen (z. B. „/index.html“ und „/index.php“) werden gekürzt.

true oder yes oder Wert nicht gesetzt (Standardwert):
Werden die Parameter „useWelcomeFileNames“ und „stripWelcomeFileNames“ mit dem Wert true übergeben (Standardwert), wird die Startseite des Ordners Startpage im Dateisystem zwar mit der Erweiterung /index.* angelegt, kann aber (bei passender Webserver-Konfiguration) über die URL „/Startpage/“ angefragt werden.

Aus

../de/startpage/firstspirit_hybrid_cms.html
../en/startpage/firstspirit_hybrid_cms.html

bei der Standard-URL-Erzeugung wird im Advanced-Modus mit „useWelcomeFileNames“ und „stripWelcomeFileNames“ (im Dateisystem):

../Startseite/index.html
../Startpage/index.html

Und die Advanced URL:

../Startseite
../Startpage

false oder no:
Wird der Parameter „stripWelcomeFileNames“ mit dem Wert false übergeben, bleibt für alle Startseitenreferenzen die Erweiterung /index.* im Dateisystem und in der Advanced URL erhalten.

Liste von Erweiterungen:
Wird dem Parameter eine Liste von Erweiterungen übergeben, wird für Seitenreferenzen, die als Startseite eines Ordners der Struktur-Verwaltung markiert sind, die Extension /index.* beim Erzeugen einer Advanced URL gekürzt und kann, bei entsprechender Webserver-Konfiguration, über die jeweilige URL angefragt werden (analog zum Verhalten beim Wert true).

Angegeben werden hier die Namen der Erweiterungen (Zieldatei-Erweiterung: siehe Vorlagensätze (→Dokumentation für Administratoren)).

useIRIs

FirstSpirit unterscheidet bei der Benennung von Objekten strikt zwischen Anzeigenamen (nicht eindeutig, optional mehrsprachig pflegbar, mit Unicode-Unterstützung) und Referenznamen (eindeutig innerhalb des Namensraumes, eingeschränkt auf Buchstaben und Zahlen, d.h. kein Unicode-Support). Während die Anzeigenamen für die redaktionelle Arbeit relevant sind und jederzeit durch den Redakteur verändert werden können, werden Referenznamen in der Regel nur vom Vorlagenentwickler oder für systeminterne Aktionen benötigt und können nicht (oder nur mit großem Aufwand) verändert werden. Diese zweischichtige Benennung hat sich in der Praxis bewährt, führt aber dazu, dass an einigen Stellen auf Referenznamen zurückgegriffen werden muss. So dürfen beispielsweise URLs laut Spezifikation nur US-ASCII-Zeichen beinhalten, während nicht-ASCII-Zeichen nur per UTF-8 enkodiert werden können.

Bei der Erzeugung von Advanced URLs wird nun der Anzeigename der FirstSpirit-Objekte zugrunde gelegt, der potentiell ungültige Zeichen (Umlaute, Leerzeichen, u.a.) enthalten kann. Einige ungültige Zeichen werden beim Erzeugen von Advanced URLs direkt ersetzt (unabhängig von der Konfiguration durch „useIRIs“). So werden generell führende und abschließende Leerzeichen aus URLs entfernt und folgende Zeichen sowie weitere Leerzeichen durch Minuszeichen (-) ersetzt:

 \ / , : ; * ? " < > |  # @ = & + % $

Mithilfe des Parameters „useIRIs“ (Standardwert „true“) werden alle URLs in UTF-8 erzeugt, inklusive Leer- und Sonderzeichen.

context.setProperty("#urlCreatorSettings", Collections.singletonMap("useiris", "true"));

Aus

../de/marketing/aboutus.html
../en/marketing/aboutus.html

bei der Standard-URL-Erzeugung wird im Advanced-Modus mit „useIRIs“

../Marketing/Über-uns.html
../Marketing/About-us.html

und im Advanced-Modus ohne „useIRIs“

../Marketing/%C3%9Cber-uns.html
../Marketing/About-us.html

Der Parameter „useIRIs“ hat keine Auswirkungen auf den Dateinamen, sondern wirkt sich lediglich auf die erzeugte Advanced URL aus (analog zum Parameter stripWelcomeFileNames).

Die Angabe von useIRIs=false wirkt sich beim Auflösen per $CMS_REF(...)$ / ref(...) nicht auf Zeichen aus, die mittels selfLink definiert werden. Beispiel: Die Konfiguration useIRIs=false selfLink="?" führt nicht zu <a href="%3F">, sondern bleibt weiterhin <a href="?">.

useRegistry

Über die „Globalen Einstellungen“ im FirstSpirit SiteArchitect kann die URL-Erzeugung eines Projektes beeinflusst werden. Beispielsweise können dort so genannte Short-URLs für bestimmte Projektinhalte (z. B. für „Landing Pages“) konfiguriert werden. Auf diese Weise können zusätzlich zu den normalen URLs kurze, einprägsame, „sprechende“ URLs für bestimmte Inhalte erzeugt werden. Diese Konzepte (Short URLs, SEO-URLs) greifen nur, wenn die erzeugten Advanced URLs in einer Persistenzstruktur gespeichert sind, in der jedem Objekt eine projektweit, eindeutige URL zugewiesen wird.

Wird der Parameter „useRegistry“ mit dem Wert „true“ übergeben (Standardwert), werden alle neu erzeugten Advanced URLs in der Projekt-Registry gespeichert. In diesem Fall kann die zugrundeliegende URL-Creator-Implementierung die URLs aus der Persistenzstruktur lesen bzw. neu berechnete URLs in der Persistenzstruktur speichern.

context.setProperty("#urlCreatorSettings", Collections.singletonMap("useregistry", "true"));

Die Registry kann innerhalb des Lebenszyklus eines Projektes stark wachsen, da einmal gespeicherte URLs erhalten bleiben. Wird beispielsweise ein Objekt innerhalb des Projektes gelöscht, so bleibt die zu diesem Objekt gespeicherte URL trotzdem erhalten, um im Falle der Wiederherstellung des Objektes auch automatisch die gespeicherte URL wiederherstellen zu können (siehe zu diesem Thema auch Speichern und Zurücksetzen von URLs). Das Löschen von gespeicherten Advanced URLs kann über den Parameter „removeDeleted“ konfiguriert werden.

removeDeleted

Der Parameter „removeDeleted“ ist nur relevant, wenn die verwendete URL-Pfadstrategie auch den Konfigurationsparameter „useRegistry“ verwendet.

factorySettings = new HashMap();
factorySettings.put("useregistry", "true"); 
factorySettings.put("removedeleted", "true"); 
context.setProperty("#urlCreatorSettings", factorySettings);

Wird der Parameter „removeDeleted“ mit dem Wert „true“ übergeben (Standardwert „false“), können URLs auf Objekte, die im Projekt bereits gelöscht wurden, auch aus der Registry entfernt werden. Das Standardverhalten sieht vor, dass die Advanced URLs in der Projekt-Registry erhalten bleiben, um beim Wiederherstellen eines gelöschten Objektes im Projekt auch die zu diesem Objekt erzeugten URLs automatisch wiederherstellen zu können.

In ungünstigen Fällen kann die Registry innerhalb des Lebenszyklus' eines Projektes stark anwachsen. Wird beispielsweise eine Seitenreferenz im Projekt gelöscht, die eine PageGroup bezüglich einer Content-Projektion beinhaltet, so können mit dieser Seitenreferenz schnell viele tausende, gespeicherte URLs verbunden sein (auch durch gelöschte Datensätze).

Ein weiterer Anwendungsfall ist die Bereinigung von URL-Konflikten im Projekt. So kann die Verwendung des Parameters „useWelcomeFileNames“ zu Problemen führen. Da URLs einmalig vergeben werden und innerhalb des Projektes eindeutig sind, bleibt auch ein einmalig erzeugter „Index“-Eintrag für eine Startseite erhalten, selbst wenn die zugehörige Seitenreferenz bereits aus dem Projekt entfernt wurde. Neue Startseiten werden dann automatisch mit einer fortlaufenden Nummer versehen, statt

../Startseite/index.html

erhält man also:

../Startseite/index.1.html

Um diesen Konflikt aufzulösen, muss zunächst der alte Index-Eintrag aus der Registry entfernt werden.

Beim Entfernen einer Advanced URL aus der Persistenzstruktur können potentiell vorhandenen Bookmarks und externe Links auf diese URL ihre Gültigkeit verlieren.

readOnlyRegistry

Dieser Parameter ermöglicht die rein lesende Nutzung der in der Registry gespeicherten URLs:
Wird er mit dem Wert true übergeben (Standardwert: false), werden bestehende URLs weiterhin aus der Registry ausgelesen, neue URLs dieser aber nicht hinzugefügt.

Der Parameter kann somit für Generierungen verwendet werden, die keine permanenten URLs erzeugen sollen (z. B. Generierungen des aktuellen Stands auf einen Testserver) und so die erzeugten URLs vorab zu prüfen.

Damit der Parameter readOnlyRegistry ausgewertet wird muss der Parameter useRegistry ebenfalls auf true gesetzt sein.

useLowercase

Unter Windows spielt die Groß-/Kleinschreibung bei Dateien und Ordner keine Rolle, d. h. bei den Ordnern „abc“, „Abc“ und „ABC“ handelt es sich um denselben Ordner.

Bei Unix-Dateisystemen sind Groß-/Kleinschreibung bei Dateien und Ordnern hingegen Unterscheidungsmerkmale. So kann es zu Konflikten kommen, wenn die Dateien beispielsweise unter Linux erzeugt werden und dann auf ein Windows-System übertragen werden.

Mithilfe des Parameters „useLowercase“ kann die Groß-/Kleinschreibung von Dateien und Ordnern bei der Generierung beeinflusst werden:

Wird der Parameter mit dem Wert „false“ übergeben, wird bei der Erzeugung von Advanced URLs Groß-/Kleinschreibung der Anzeigenamen im Projekt berücksichtigt. Dies ist das Standardverhalten.

Wird der Parameter mit dem Wert „true“ übergeben, wird für die Erzeugung der Datei- und Ordnernamen Kleinschreibung verwendet.

Beispiel:
Ein Projekt enthält zwei Strukturordner (Menüebenen) mit den Anzeigenamen „Folder“ und „folder“.
Bei einer Generierung mit dem Wert „false“ für „useLowercase“ werden folgende Advanced URLs gebildet:

/folder/index.html
/Folder/index.html

Bei einer Generierung mit dem Wert „true“ für „useLowercase“ werden folgende Advanced URLs gebildet:

/folder/index.html
/folder/index-2.html

selfLink

Unabhängig davon, ob die Referenz-Implementierung („Advanced URL Creator“) oder eine eigene, kundenspezifische Pfadstrategie, basierend auf den neuen Interfaces, implementiert und als Modul in FirstSpirit integriert wird, gilt: Bei einer Selbstreferenzierung (d.h. die aktuell generierte Seite beinhaltet eine Referenz auf sich selbst, z. B. innerhalb der Navigation) wird als URL standardmäßig der Name-Part zurückgeliefert, also z. B. "index.html".

Der Konfigurationsparameter selfLink kann zur Konfiguration eines konstanten Strings verwendet werden, der bei Selbstreferenzierungen zurückgeliefert wird.

Gültige Werte sind:

• " " (Leerstring): wird dieser Wert gesetzt, wird für Selbstreferenzen ein Leerstring zurückgeliefert.
• Weitere gültige Werte sind "?" und "#", die (abhängig vom Browser) ebenfalls als Referenz auf die aktuelle Seite interpretiert werden.

Hinweis: Nicht alle Browser können mit „leeren“ Verweisen (" " (Leerstring)) umgehen. Es sind Fälle bekannt, in denen der Browser einen leeren Verweis nicht als Link auf die aktuell angezeigte URL interpretiert, sondern als Verweis auf den Verzeichnispfad, in dem die generierte Datei liegt. Statt einem Reload von "/index.html" versucht der Browser hier also das aktuelle Verzeichnis "/" zu öffnen. In diesen Fällen kann eine Referenz, die im HTML-Vorlagensatz über den Ausdruck $CMS_REF(..)$ in einem <a href>-Tag ausgegeben wird, dazu führen, dass betroffene Seiten nicht neu geladen werden. Dies ist insbesondere für dynamische Webseiten problematisch. In Kombination mit dem Parameter useWelcomeFilenames=false (siehe oben) führte dieses Verhalten letztlich zu einem http-404-Fehler, weil keine Index-Datei gefunden wurde.
In FirstSpirit-Versionen < 5.2 wurde bei einer Selbstreferenzierung als URL ein Leerstring " " zurückgeliefert.

Zur Verwendung mit useIRIs siehe oben.