Netz - Rettung - Recht

Es empfiehlt sich, den Umstieg anhand des Upgrade-Guides vorzunehmen. Ich habe mich entschlossen, das Pattern-Matching auf glob patterns umzustellen, aber bei legacy identifiers zu bleiben, um den Umstellungsaufwand überschaubar zu halten. Außerdem verwende ich häufig Eltern-Kind-Relationen zwischen verschiedenen Items (Seiten), die aber mit den full identifiers (“identifiers with extensions”) nicht mehr unzweideutig bestehen (und, um überhaupt zu funktionieren, einen Rückgriff auf einen Helper benötigen).

An folgenden Stellen der Konfiguration ist daher Hand anzulegen (oder war bei mir Hand anzulegen):

Datenquellen

In der nanoc.yaml muss bei den data_sources (meistens wohl filesystem) ein identifier_type: legacy eingefügt werden (Punkt 3 im “quick upgrade guide”).

Was dort nicht steht: Die Datenquelle muss diese Konfiguration selbst umsetzen. Insbesondere für eigene Datenquellen genügt es also nicht, dort einfach identifier_type: legacy einzufügen. Das festzustellen hat mich einige Zeit gekostet.

Anzusetzten ist daher bei der Erzeugung von Items in der Datenquelle. Dort ist ohnehin der Aufruf Nanoc::Item.new durch new_item zu ersetzen (Punkt 7 im “quick guide”). Das genügt aber nicht; der dritte Parameter dieses Funktionsaufrufs erwartet nämlich entweder einen String (der zu einem Identifier konvertiert wird) oder eine Instanz des Objekts Nanoc::Identifier. Was ich nun in der Dokumentation nicht gefunden habe, ist folgendes: ein String wird immer zu einem full identifier konvertiert! Will man Items mit legacy identifier erzeugen, muss man zwingend Nanoc::Identifier instanziieren. Aus "/user/#{user[:id]}/" wird also bspw. Nanoc::Identifier.new("/user/#{user[:id]}/", type: :legacy).

(Auf meinen Hinweis hin ist das nun der neue Punkt 8 im “quick guide”.)

Rules

Hat man - wie ich - auf glob patterns gesetzt (sonst genügt ein string_pattern_type: legacy in der nanoc.yaml), müssen die Rules angepasst werden. Ich verweise insoweit auf den Abschnitt Enabling glob patterns im Extended upgrade guide und die Dokumentation zu Identifiers and patterns, die man ohnehin einmal studieren sollte.

Wichtig - und im Upgrade-Guide dann doch eher versteckt am Ende dargestellt - ist zudem, dass Identifier keine Strings mehr sind, so dass String-Funktionen auf item.identifier nicht mehr ohne weiteres angewandt werden können (bspw. item.identifier.split). Bei jedem dieser Aufrufe muss daher zuvor eine Konvertierung in einen String erfolgen, alos .to_s eingefügt werden: item.identifier.to_s.split geht. Das gilt auch für Helper-Funktionen u.ä., wo sich solche Aufrufe finden können. (Das hat in meinem Fall am meisten Zeit gekostet; auf die Lösung kam ich erst nach Lektüre der Beiträge der letzten Jahre in der Nanoc-Mailingliste).

Weitere Änderungen:

• In compile-Regeln entfällt bei filter, layout und snapshot ein ggf. vorangestelltes rep. (“quick guide”, Punkt 5).

• Falls jemand im preprocess-Block Items erzeugt, sollte er statt Nanoc::Item.new jetzt @items.create verwenden (“quick guide”, Punkt 6).

• Überall, wo auf reps[0] zugegriffen wird, muss stattdessen .reps[:default] stehen (“quick guide”, jetzt Punkt 9).

• Entsprechend muss .rep_named(:something) durch .reps[:somethink] ersetzt werden (“quick guide”, jetzt Punkt 10).

Zudem muss man nicht mehr zwischen compile- und routing-Regeln differenzieren: die write-Anweisung erlaubt es, in einer compile-Regel direkt auch festzulegen, wo das Item ausgegeben werden soll. Das erscheint mir zwar praktisch, allerdings (ebenso wie die full identifiers) eher etwas für neue Projekte oder eine Komplettüberarbeitung.

Funktionen, Helper und Filter

• Generell ist Nanoc3 durch Nanoc zu ersetzen, bspw. bei Einbinden der mitgelieferten Helper: aus include Nanoc3::Helpers::Blogging wird include Nanoc::Helpers::Blogging usw. (“quick guide”, Punkt 1).

• Überall, wo auf @site.config zugegriffen wird, gehört jetzt @config hin (“quick guide”, Punkt 2).

• Alle Hinweise aus den vorstehenden Abschnitten gelten entsprechend auch für Helper und Filter.

• An Filter übergebene Parameter sind jetzt ebenfalls immutable; man kann sie also nicht mehr verändern. Auch die Zuweisung an eine Variable hilft nicht. Man kann aber ggf. den Inhalt in eine Variable kopieren: params_mutable = filterparams.dup.

Fazit

Der Upgrade-Guide ist gut, deckt aber nicht (unmittelbar) alle Fußangeln und Fallen ab; man sollte etwas Zeit für trial and error einkalkulieren, insbesondere für größere, komplexere Projekte.