Konfiguration benutzerspezifischer Advanced URLs

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");
        ....
   }
   ...
}

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

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

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

Bei einer Selbstreferenzierung (d.h. wenn die aktuell generierte Seite eine Referenz auf sich selbst beinhaltet (z. B. innerhalb der Navigation) wird statt der Advanced URL ein Leerstring "" zurückgeliefert.

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

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

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:

 \ / : * ? " < > |  # 

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

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

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