byte5-CPO Sören Deger kennt als langjähriger Umbraco-Trainer und Projektmanager das CMS wie seine Westentasche. Anlässlich der Erscheinung der Umbraco-Version 8 noch in diesem Quartal teilt Sören in seiner Blogserie „Introducing v8“ sein Wissen, erklärt, was die neue Version an Funktionen mit sich bringt und welche technischen Vorzüge sie gegenüber ihren Vorgängerversionen bietet.

Dabei geht er insbesondere auf Installation, Mehrsprachigkeit und Änderungen bei Dokumententypen, auf nuCache und Log-Viewer sowie auf Content-Apps ein. Außerdem wird Sören klären, was wir von künftigen Minor-Releases erwarten dürfen. Heute geht es um eine der neuen Hauptfunktionen von Umbraco, Content-Apps.

DJR 0128 Edit

Nachdem wir uns vergangene Woche nuCache und den LogViewer näher angesehen haben, beschäftigen wir uns heute im vierten Teil meiner Blogserie mit dem neuen Feature Content-Apps. Content-Apps sollen die Arbeit von Redakteuren mit Inhalten in Umbraco unterstützen und immer kontextbezogene Informationen bereitstellen. Sie sind nicht dafür gedacht, Content zu bearbeiten.

Es gibt zum einen sogenannte Default-Content-Apps. Zu diesen gehört u.a. die Content-App Info, welche den ursprünglichen Info-Tab aus Umbraco-Version 7 ersetzt und die wichtigsten Systeminfos des aktuellen Content-Knotens anzeigt. Hierzu gehören beispielsweise unter anderem die Links, Historienverlauf, Status und die ID des Knotens.

 

 

 

 

Abbildung 1
Abb. 1: Menü der Default-Content-Apps in Umbraco 8

 

Natürlich ist es für Entwickler auch möglich eigene, sogenannte Custom-Content-Apps, zu entwickeln, in Umbraco zu integrieren und den Redakteuren als nützliches Werkzeug zur Verfügung zu stellen. So könnte man beispielsweise eine Content-App für Google Analytics entwickeln, mit der der Redakteur immer die Besucherzahlen dieses Knotens bzw. dieser Site angezeigt bekommt. Man könnte aber auch eine Content-App für eine Facebook-Integration entwickeln. In dieser könnte der Redakteur dann beispielsweise die aktuelle Seite bei Facebook posten und in der App auch direkt die Anzahl der Likes zu diesem Post angezeigt bekommen.

Es gibt bereits viele weitere Ideen für die Entwicklung von Content-Apps und es werden in naher Zukunft viele nützliche Content-Apps für Umbraco entwickelt und der Community zur Verfügung gestellt werden.

Natürlich habe auch ich mich bereits mit der Entwicklung von Content-Apps für Umbraco V8 beschäftigt und eine solche als Umbraco-Package veröffentlicht. In den verschiedensten Projekten meiner nun fast 10-jährigen Geschichte als Umbraco-Entwickler gab es immer wieder die Anforderung von Kunden, auch eine individuelle Dokumentation für das Backend und vor allem für die Content-Struktur zur Verfügung zu stellen.
Diese hatte man anfangs noch ganz klassisch mit PDF-Dateien gemacht, später gab es dann diverse Packages als Erweiterung für Umbraco, aber alle hatten sie einen Nachteil: Der Redakteur musste in der Dokumentation immer zunächst die richtige Stelle finden und dies kostete schlicht und ergreifend Zeit.

Und genau an dieser Stelle habe ich nun angesetzt: Da Content-Apps individuelle Informationen zum entsprechenden Content-Knoten liefern können, habe ich mit der Supportly-Content-App eine Möglichkeit geschaffen, dass Admins einfach und schnell im Backend Dokumentationen zu den jeweiligen Dokumententypen erstellen können. Der Redakteur bekommt danach durch einen Klick auf die Supportly-Content-App direkt die Dokumentation zum aktuellen Dokumententyp angezeigt.

Die Supportly-Content-App kann hier heruntergeladen werden.

Schauen wir uns nun zunächst einmal an, wie eine Custom-Content-App entwickelt werden kann.

Das Konzept ist identisch mit dem der Entwicklung von Custom-Property-Editoren in Version 7. Wir benötigen für eine Custom-Content-App folgende Komponenten:

-  Package.manifest: Registrierung der Content-App in Umbraco und Einbinden aller zusätzlicher Dateien, welche wir für die Content-App benötigen.

-  AngularJS-View: Eine HTML-Datei, welche wir für die Anzeige der Content-App im Umbracobackend benötigen

-  AngularJS-Controller: Eine Javascript-Datei, welche die Logik clientseitig bereitstellt

Ziel ist es, nun eine Content-App zu entwickeln, welche alle Content-Knoten auflistet, die den aktuellen Content-Konten verlinken. Wir werden den gesamten Cache von Umbraco durchsuchen und exemplarisch alle Werte von Content-Pickern dahingehend prüfen, ob die ID des aktuellen Content-Knotens eingetragen ist. Die Anzahl soll als kleiner Badge im Content-App-Symbol und alle Verlinkungen als Aufzählung in der Content-App angezeigt werden.

Zuerst erstellen wir hierzu im App_Plugins-Verzeichnis den neuen Ordner „b5RelatedLinksContentApp“. Darunter erstellen wir die drei folgenden Dateien:

Abbildung 2

-  package.manifest als Javascript-Datei)

-  relatedLinks.html als HTMl-Datei

-  relatedLinks.controller.js als Javascript-Datei

Unsere View und die Controller-Javascript-Datei
müssen wir nun in unserem package.manifest verlinken.

 

Hierzu öffnen wir das package.manifest und tragen
alle notwendigen Informationen, welche Umbraco
zur Registrierung unserer Content-App benötigt,
in Form eines JSON-Objekts ein.

Einzelheiten zu den Propertys des JSON-Objekts
sind nachfolgend als Kommentare hinterlegt.

 

Abb. 2: Dateistruktur für Content-App

 

 

Abbildung 3

Abb. 3: Aufbau des package.manifest unserer Content-App

 

Wenn wir nun Umbraco neu starten und uns im Backend anmelden, sehen wir bei jedem Content-Knoten bereits die neue Content-App, welche jedoch noch leer ist.

Abbildung 4

Abb. 4: Neue Content-App „Related Links“

 

Als nächstes erstellen wir folgendes HTML-Markup in unserer relatedLinks.html:

Abbildung 5
Abb. 5: relatedLinks.html mit Basic-Markup

 

Und danach tragen wir folgenden Code in den AngularJs-Controller ein:

Abbildung 6
Abb. 6: relatedLinks.controller.js mit Abruf der aktuellen Knoten-ID aus dem editorState-Objekt

 

Die aktuelle Knoten-ID werden wir im weiteren Verlauf noch benötigen. Nun erscheint im Backend zumindest bereits die h1-Überschrift in unserer Content-App.

Abbildung 7
Abb. 7: Darstellung der Content-App im Umbraco-Backend mit Überschrift

 

Man sollte nach Anpassungen immer den Cache im Browser löschen, da das Caching bei AngularJs sehr hartnäckig ist. Sollte auch das Löschen des Caches einmal nicht den gewünschten Effekt bringen, so kann man auch zusätzlich noch die Versionsnummer der clientdependency.config im config-Verzeichnis von Umbraco um 1 erhöhen.

Grundsätzliche Informationen zur Nutzung von AngularJs in Umbraco findet man in der offiziellen Umbraco-Dokumentation und kann sich auch an den Beispielen von Custom-Property-Editoren orientieren, welche sehr ähnlich ist:

-  Backoffice UI API Documentation

-  Creating a Property Editor

Um nun den Cache zu durchsuchen und alle Knoten zu finden, welche auf den aktuellen Knoten verlinken, benötigen wir nun das nachfolgende Model und den API-Controller.

Der gesamte fertige Quellcode kann übrigens hier auch heruntergeladen werden.

Abbildung 8
Abb. 8: b5RelatedLinksDataModel für „Related Links”-Content-App

 

Abbildung 9
Abb. 9: b5RelatedLinksContentAppApiController für „Related Links“-Content-App

 

Im Controller laden wir zunächst alle Root-Content-Knoten aus dem Cache, durchlaufen alle Knoten unterhalb des jeweiligen Root-Knotens und prüfen für alle Knoten in der Methode „GetRelatedProperty“, ob dort ein Content-Picker beinhaltet ist und falls ja, ob dieser den aktuellen Content-Knoten referenziert. Nur wenn dies der Fall ist, fügen wir ein stark vereinfachtes Model vom Typ „b5RelatedLinksDataModel“ zu einer Liste hinzu, welche am Ende der Controller zurückgibt. Dabei wird aus Performance-Gründen kein einziges Mal auf die Umbraco-Datenbank zugegriffen, sondern ausschließlich auf nuCache.

Nun müssen wir als nächstes in unserem AngularJs-Controller die API anbinden. Um dies sauber zu trennen, erstellen wir im Verzeichnis „/App_Plugins/b5RelatedLinksContentApp“ eine neue Javascript-Datei „relatedLinks.resource.js“ und registrieren diese im package.manifest.

Abbildung 10
Abb. 10: Registrierung der neuen AngularJs-Ressource im package.manifest

 

In der AngularJs-Ressource müssen wir jetzt den benötigten API-Endpunkt definieren.

Abbildung 11
Abb. 11: b5RelatedLinksResource mit API-Endpunkt

 

Abschließend sind noch ein paar kleine Schritte notwendig: In unserem AngularJs-Controller müssen wir die neue AngularJS-Ressource einbinden, die Ressource aufrufen und den Response einer neuen Property unseres vm-Objektes zuweisen sowie in unserer AngularJs-View das vm-Objekt auslesen und die Daten ausgeben.

Abbildung 12
Abb. 12: Erweiterung des AngularJs-Controllers durch Ressourcenanbindung

 

Abbildung 13
Abb. 13: Ausgabe der verlinkten Knoten mit zusätzlichen Informationen in AngularJs-View

 

Jetzt ist es endlich an der Zeit unsere neue Content-App im Backend vollständig zu testen. Ich habe hierzu in drei Content-Knoten mit einem Content-Picker den „Blog“-Knoten aus dem Starterkit von Umbraco v8 ausgewählt. Wenn wir nun den Blog-Knoten öffnen und dann zur Content-App „Related Links“, wechseln bekommen wir alle referenzierenden Knoten angezeigt und können auch per Klick auf die URL direkt zum referenzierenden Knoten wechseln.

Abbildung 14
Abb. 14: Anzeige der referenzierenden Knoten in der Content-App „Related Links“ im Backend

 

Es wäre jetzt noch schön, wenn man die Anzahl der Links direkt als Badge im Symbol der Content-App angezeigt bekommen würde. Dadurch müsste man als Redakteur nicht in die Content-App wechseln, wenn ein solcher Badge bereits signalisieren würde, dass es keine referenzierenden Knoten gibt.

Hierfür gibt es die folgende sehr einfache Lösung:

Abbildung 15
Abb. 15: Implementierung der Badge-Funktionalität im AngularJs-Controller

 

Über die Property model.badge unseres Scopes können wir ein Badge im Content-App Symbol hinzufügen und aktualisieren.
Bei „type“ kann man „warning“ und „alert“ eintragen. Dementsprechend ist der Badge dann gelb oder rot. Wenn man keinen Typ angibt, wird eine neutrale Farbe angewandt. Ebenso ist es möglich die Property „count“ nicht anzugeben. In diesem Falle wird lediglich ein farbiger Badge ohne Zahl angezeigt.

Die Badge-Funktion funktioniert jedoch leider im aktuellen Umbraco Release 8.0.0 nicht. Es gibt hier ein bekanntes Issues, welches im Release 8.0.1 behoben sein soll. Dieses Release wird am 12. März veröffentlicht.

Als nächstes beschäftigen wir uns mit den Berechtigungen von Content-Apps. Wir können Content-Apps auf Dokumenten- und Medientypen und auf Benutzergruppen einschränken. Diese Konfiguration erfolgt im package.manifest.

Abbildung 16
Abb. 16: Berechtigungen für Content-App in package.manifest

 

Im nächsten – und vorerst letzten – Teil meiner Blogserie werde ich euch kommenden Freitag mitteilen, was uns an neuen Features in den nächsten Releases von Umbraco 8 erwartet.

Unser erster Hackathon zu Umbraco v8 findet am Donnerstag, den 4. April, statt! Sei dabei, wenn wir uns im Rahmen des deutschen Umbraco-Festivals ein paar Issues vorknöpfen und gemeinsam mit Poornima vom offiziellen Pull-Request-Team gemeinsam an Umbraco 8 feilen. Die Teilnahme kostet nichts außer einer Anmeldung bei Laura ! Los geht’s um 14 Uhr.

 

Zurück