Dieser Text dient der Dokumentation von kompleren Anwendungsfällen, die in der Anwendung mit der Intranet-Plattform auftreten. Die Dokumentation wird parallel mit der Software ergänzt und aktualisiert.

Die Dokumention bezieht sich aktuell primär auf die öffentlichen APIs und sind daher vorwiegend für technisch interessierte Anwender.

Model-View-Controller

Dieses Kapitel beschreibt den MVC-Ansatz der Plattform und insbesondere, wie die Views zustande kommen.

ViewResolver und Views

TODO:

View-Komponenten und Direktiven

Die Plattform stellt einige Komponenten zur Verfügung, mit denen häufig wiederkehrende Anforderungen standardisiert sind.

In den Freemarker-Views können die View-Komponenten als Direktiven verwendet werden.

TODO: Beschreibung der allgemeinen Attribute: permissions, permissionCtx etc.

@link: Link auf ein DataObject

Rendert einen Link auf ein DataObject.

Attribute

  • data:

  • type: Der Link-Typ, "show" oder "edit".

Beispiel
        [@link data=a type="show" class="edit" /]
Die @link-Direktive ist eine sehr kleine Komponente. Sie sollte nur verwendet werden, wenn die Standardkomponenten nicht weiterhelfen und eine wirkliche Custom-Ansicht erstellt wird, für die eine generelle Programmierung einer eigenen Komponente nicht sinnvoll erscheint.
Es fehlen noch weitere Link-Typen, um generell die WWButtons erzeugen zu können.

@box: Container mit Titel

Rendert eine WWBox mit standisierten CSS-Klassen. Sollte nested-content enthalten. Das können weitere Tags sein.

Attribute

  • title: Der Titel der WWBox.

  • class: CSS-Klassen, die zusätzlich zu den Standardklassen aufgenommen werden.

  • contentSensitive: Ist die box contentSensitive? "true" oder "false". Default: false

Beispiel
<@box title="Beteiligte Organisationen">
  Hallo Box!
</@box>

@fckeditorpane: Textdarstellung von FCKEditor-Eingaben

Rendert die Eingaben von Memofelder, die über den FCKEditor kommen.

Attribute

  • text: Der Text.

  • class: CSS-Klasse um das EditorPane

Beispiel
<@fckeditorpane text=o.description class='my-css-class' />

@gallery: Gallerie

Rendert eine Gallerie.

Attribute

  • data: Das DataObject, das als Basis für die Suche nach der Gallerie verwendet wird.

Beispiel
<@gallery data=o />

@googlemaps: GoogleMaps-Darstellung

Rendert eine Karte von GoogleMaps. Die Karte zoomt sich standardmässig so, dass alle Marker aus der geoJsonUrl-Quelle auf die Karte passen.

Attribute

  • geoJsonUrl: Eine URL als Quelle für eine GeoJson-Datei. Siehe dazu den internen GeoJSONProvider.

  • styleJsonUrl: Eine URL als Quelle für die GoogleMaps-Styles.

Beispiel
<@googlemaps geoJsonUrl="/kos/WNetz?art=GeoJSONProvider.select&ref=111" />

@filesystem: Dateisystem

Rendert eine Ansicht des übergebenen Wurzelordners.

Attribute

  • root: der Root-Folder. Der Root-Folder kann bei DataObjects, die Dateisysteme unterstützen über die Eigenschaft rootFolder ermittelt werden.

Beispiel
<@filesystem root=o.rootFolder/>

@listview: Liste von DataObjects

Rendert eine ListView.

Attribute

  • impl: die Implementation der ListView

  • id: die ID der Liste. Die ID der Liste wird zur Standardkonfiguration der Liste verwendet und gibt typischerweise den Namen der Collection an.

  • layout (optional): das Layout der ListView

  • data: Die Daten - diese werden als Expression aus dem Model angegeben.

  • actions: Eine Liste der logischen Buttons, die unter der ListView erscheinen sollen. Aktuell sind folgende Werte erlaubt: add, change, magnifier.

Beispiel
<@listview impl="kos.intranet2.core.news.NewsList"
        id="kos.intranet2.om.Project.news"
        data=o.news
        actions=['add','change','magnifer'] />

@listview_actions: Aktionen unter einer Liste

Die listview_actions-Komponenten wird von der @listview-Komponente verwendet, um die Aktions-Buttons der Liste zu erzeugen. In eigenen Ansichten, kann es sinnvoll sein, die Actions getrennt von einer @listview zu verwenden.

Beispiel
<@listview_actions id="kos.intranet2.om.Project.addresses"
                   actions=['add'] />

@topics: Topics mit Editor

Rendert die Topics-Komponente des aktuellen DataObject.

Theming

TODO:

System-Indicator

In das Rendern der HTML-Ausgabe wird Code generiert, der ggf. anzeigt auf welchem System man sich befindet. Aktuell wird hier dem DEV bzw. STAGING-System ein Balken angezeigt. Das kann mit einem einfachen Parameter in der URL für die gesamte Session umgestellt werden.

http://url?system-indicator=[true|false]

Utility-Klassen

TODO:

Entwicklung von Themes

TODO:

Öffentliche APIs

Die APIs dienen der strukturieren Übergabe von Daten aus dem Live-System. Die Daten werden in einem JSON-Format mit dem Content-Type application/json zurückgegeben.

Allgemein

Die Beschreibung der APIs werden anhand ihrer Controller-Methode (Call) und den möglichen Parametern beschrieben. Als Anwender der API kann man sich leicht eine entsprechende URL zusammenstellen.

Beispiel
Methode: Foo.bar
Parameter (Pflicht): a, Typ: int

URL: /kos/WNetz/art=Foo.bar&a=5

Authentifizierung und Autorisierung

Die öffentlichen APIs der Plattform sind durch einen APIKey geschützt. In der Plattform können in der Eigenschaft APIKeys mehrere Keys hinterlegt werden.

Alle API-Aufrufe müssen mit dem APIKey ergänzt werden, damit eine eine Authentifizierung stattfinden kann. Wenn bei einem API-Aufruf nichts anderes dokumentiert wird, werden nur Daten zurückgegeben, die als öffentlich markiert sind.

Die APIs liefern nur Daten zurück, die in der Plattform als öffentlich bzw. public markiert sind.
Beispiel
Methode: Foo.bar
Parameter (Pflicht): a, Typ: int

URL: /kos/WNetz/art=Foo.bar&a=5&apikey=12345
Um die Beispiele für die API-Calls lesbarer zu gestalten, wird der Parameter apikey in den Beispielen nicht angegeben.

Das Result-Objekt

Alle Ergebnisse der API-Aufrufe werden in einem Result-Objekt zurückgeliefert. Das Result-Objekt hat folgende Struktur:

Struktur des Result-Objekts
{
  "error": false,	(1)
  "message": "", 	(2)
  "warnings": [ 	(3)
  ],
  ....				(4)
}
1 Gibt an, ob dies eine Fehlermeldung ist.
2 Eine Nachricht des API-Calls. Hier werden die Texte der Fehlermeldungen hinterlegt.
3 Eine Liste an Strings, mit evtl. Warnungen, die bei der Verarbeitung auftraten.
4 Weitere spezifische Attribute.

Je nach API-Call wird die Struktur des Result-Objekts um weitere Attribute ergänzt.

TopicAPI

Die TopicAPI liefert einen Zugriff auf die Daten, die im Topic-Modul (oder Glossar) der Plattform hinterlegt sind.

Call: TopicAPI.list

Liefert eine Menge von Topics anhand unterschiedlicher Selektionskritieren.

Parameter: Es kann einer von folgenden Parameter evtl. auch mehrfach als *Selektionskriterium angegeben werden. Ist ein Parameter mehrfach angegeben, werden die Ergebnisse in einem UNION zusammengefasst.

  • Keiner: Wird kein zusätzlicher Parameter angegeben, so wird die Liste aller Topics zurückgegeben.

  • id (int): ID eines Topics.

  • category (int): Gibt die ID einer Category an, die alle zurückzugebenden Topics haben müssen.

Beispiele
/kos/WNetz?art=TopicAPI.list&id=1&id=5 		(1)
/kos/WNetz?art=TopicAPI.list&category=4		(2)
1 Liefert ein Result mit den Topics 1 und 5
2 Liefert ein Result mit den Topics, die mit der Kategorie 4 versehen sind

Die Aufrufe von TopicAPI.list liefern ein Result-Objekt mit folgender Struktur:

{
  "message": "",
  "warnings": [],
  "error": false
  "topics": [ (1)
    {
      "id": 4,
      "title": "...",
      "description": "...",
      "categories": [
        {
          "id": 1,
          "title": "Glossareinstieg"
        }
      ],
      "out_links": [
        {
          "type": "...",
          "topicIds": [ ]
        }
      ],
      "in_links": [ ]
    }
  ]
}
1 Eine Liste mit Topic-Objekten
Table 1. Struktur eines Topic-Objekts
Attribut Beschreibung

id

Die interne ID des Topics als Integer.

title

Der Titel als String.

description

Die längere Beschreibung des Topics als String. Kann HTML enthalten

categories

Eine Liste von Category-Objekten.

out_links

Eine Liste von ausgehenden Link-Objekten.

in_links

Eine Liste von eingehenden Link-Objekten.
Table 2. Struktur eines Category-Objekts
Attribut Beschreibung

id

Die interne ID des der Category als Integer.

title

Der Titel der Category als String.
Table 3. Struktur eines Link-Objekts
Attribut Beschreibung

type

Der Typ des Links als String.

topicIds

Eine Liste mit IDs von Topics, die über diesen Link-Typ verbunden sind.

Call: TopicAPI.listCategories

Liefert eine Liste von allen öffentlichen Kategorien, mit denen die Topics versehen werden können.

Parameter: Keine

Beispielergebnis
{
  "message": "",
  "warnings": [],
  "error": false,
  "categories": [ (1)
    {
      "id": 1,
      "title": "Glossareinstieg"
    }
  ],

}
1 Liste von Category-Objekten

Die Beschreibung der Category-Objekte findet sich hier.