Konfiguration benutzerspezifischer Advanced URLs

Mit FirstSpirit 5 wurden Schnittstellen und eine Referenz-Implementierung („Advanced URL Creator“) eingeführt, 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:

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

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

Übergabe per module.xml:

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

<module>
	<name>UrlFactory Example</name>
...
<components>
        <public>
            <name>Advanced URLs Example Module</name>
            <class>firstspirit.generate.UrlCreatorSpecificationImpl</class>
            <configuration>
                <UrlFactory>examples.urlfactory.UrlFactoryExample</UrlFactory>
                <useWelcomeFileNames>yes</useWelcomeFileNames>
            </configuration>
        </public>
	</components>
 ...
</module>

Standard-Konfigurationsparameter

Das FirstSpirit-Framework wertet einige Standard-Parameter aus:

• useWelcomeFileNames
• stripWelcomeFileNames
• useIRIs
• useRegistry
• removeDeleted
• useLowercase

(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"));

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

Aus

../de/startpage/mithras_home.html
../en/startpage/mithras_home.html

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

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

Für Seitenreferenzen, die nicht als Startseite gekennzeichnet sind, wird dagegen weiterhin der Anzeigename beim Erzeugen der Advanced URL verwendet.

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/Mithras-Homepage.html
../Startpage/Mithras-Homepage.html

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

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).

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

Werden die Parameter „useWelcomeFileNames“ und „stripWelcomeFileNames“ mit dem Wert „true“ übergeben (Standardwert), wird für Seitenreferenzen, die als Startseite eines Ordners in der Struktur-Verwaltung markiert sind, der Anzeigename der Startseite aus der Advanced URL entfernt.

Aus

../de/startpage/mithras_home.html
../en/startpage/mithras_home.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

Damit wird die Startseite des Ordners „Startpage“ im Dateisystem zwar mit der Extension „/index.*“ angelegt, kann aber (bei passender Webserver-Konfiguration) über die URL „/Startpage/“ angefragt werden.

Sind im Projekt mehrere Ausgabekanäle vorhanden, wird über „stripWelcomeFileNames“ nur „index.{master extension}“ entfernt. „Master extension“ ist die Dateierweiterung aus dem ersten Ausgabekanal (üblicherweise „html“).

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

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:

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

(% seit FirstSpirit Version )

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“).

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.

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

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 ungültige Links im Projekt entstehen (beim Wiederherstellen gelöschter Objekte).

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