Nanoc: Upgrade von 3.x auf 4.x
Nanoc nutze ich schon mehr als drei Jahre zur Erzeugung verschiedener Websites; aber wie das so ist bei verschiedenen und zudem historisch gewachsenen Installationen, je mehr und je komplexer man ein Werkzeug einsetzt, desto größer ist der Angang bei notwendigen Änderungen. Und so habe ich das Upgrade auf Nanoc 4 - über dessen Beta ich damals bereits berichtete - dann auch gut zwei Jahre vor mir hergeschoben.
Nunmehr werden aber endlich alle meine Präsenzen mit Nanoc 4 erzeugt.
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
undsnapshot
ein ggf. vorangestelltesrep.
(“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
durchNanoc
zu ersetzen, bspw. bei Einbinden der mitgelieferten Helper: ausinclude Nanoc3::Helpers::Blogging
wirdinclude 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.
Kommentare
Ansicht der Kommentare: Linear | Verschachtelt