VideoManagementPro: Moduldokumentation

1. Einleitung

Mit FirstSpirit lassen sich komplexe Webseiten erstellen, die zahlreichen Anforderungen unterliegen. Diese Anforderungen sind stets individuell und projektspezifisch. Immer mehr werden sie jedoch auch durch die Erwartungen der Webseiten-Besucher beeinflusst: Die reine Darstellung von Informationen reicht heutzutage nicht mehr aus. Stattdessen sollen Webseiten zusätzlich modern, beeindruckend und interaktiv sein.

An dieser Stelle setzt das VideoManagementPro-Modul an, das den VideoManager Pro von movingimage in ein FirstSpirit-Projekt integriert. Die verfügbaren Videos werden in beiden FirstSpirit-Clients in einem Report dargestellt. Aus diesem lassen sie sich per Drag-and-Drop in der Seite referenzieren.

Für Redakteure wurde so mit dem VideoManagementPro-Modul eine komfortable Möglichkeit geschaffen, einer Webseite Videos hinzuzufügen. Sie können alle notwendigen Schritte innerhalb von FirstSpirit ausführen und müssen nicht zwischen den beiden Systemen wechseln.

1.1. Technische Voraussetzungen

Für den Betrieb des VideoManagementPro-Modul wird mindestens ein technischer VideoManager Pro-Account vorausgesetzt.

Die Funktionalitäten des VideoManagementPro-Moduls können nicht in Verbindung mit der externen FirstSpirit-Vorschau verwendet werden.

2. Installation und Konfiguration

Für die Verwendung der Funktionalitäten des VideoManagementPro-Moduls ist die Installation und Konfiguration unterschiedlicher Komponenten notwendig. Die dafür erforderlichen Schritte werden in den nachfolgenden Unterkapiteln erläutert.

2.1. Konfiguration der Projekt-Komponente

Für den Einsatz des VideoManagementPro-Moduls ist eine projektspezifische Konfiguration notwendig. Diese wird über die Projekt-Komponente vorgenommen, die dem verwendeten Projekt hinzuzufügen ist. Öffnen Sie dafür den Server-Manager und wählen Sie den Bereich Projekt-Eigenschaften Projekt-Komponenten.

Projekt-Komponenten in den Projekt-Eigenschaften

projectcomponents

Im Hauptpanel ist eine Liste aller bereits vorhandenen Projekt-Komponenten zu sehen. Wählen Sie nach dem Klicken auf Hinzufügen die VideoManagementPro Project Configuration aus und bestätigen Sie die Auswahl mit OK. Die Projekt-Komponente wird anschließend der Liste im Hauptpanel hinzugefügt und muss anschließend noch konfiguriert werden (vgl. Abbildung Projekt-Komponenten in den Projekt-Eigenschaften). Selektieren Sie dafür den Eintrag in der Liste und öffnen Sie den zugehörigen Konfigurationsdialog über Konfigurieren (vgl. Abbildung Konfigurationsdialog der Projekt-Komponente).

Abbildung 1. Konfigurationsdialog der Projekt-Komponente

Benutzer: Während der Generierung muss der FirstSpirit-Server mit dem VideoManager Pro kommunizieren. Für die Authentifizierung benötigt er einen technischen movingimage-Benutzer, dessen Name in das Feld einzutragen ist. Der Benutzer muss auf alle im Projekt verwendeten Videos zugreifen können. Andernfalls ist eine vollständige Generierung des Projekts nicht möglich.
Passwort: Für die Authentifizierung wird neben dem Namen auch das Passwort des technischen Benutzers benötigt. Es ist in diesem Konfigurationsfeld anzugeben.

Diesen Nutzer in der Preview verwenden: Ist diese Option aktiviert, verwendet FirstSpirit den technischen User auch für die Generierung der Vorschau. Andernfalls erhält der Redakteur in beiden FirstSpirit-Clients eine Aufforderung zur Eingabe seiner persönlichen VideoManager Pro-Zugangsdaten, sobald ihm in der Vorschau ein Video angezeigt werden soll.
Konfiguration testen & aktualisieren: Mit einem Klick auf den Button lässt sich die Validität der eingegebenen Benutzerdaten prüfen. Sind diese fehlerhaft oder nicht vorhanden, erscheint ein entsprechender Hinweisdialog, dass der Login fehlgeschlagen ist. Sind diese korrekt, werden im zweiten Tab MI24-VideoManager Pro die VideoManager-Instanzen aktualisiert bzw. editierbar. Dieselbe Prüfung führt der OK-Button des Konfigurationsdialogs beim Speichern der Eingaben durch. Ab dem Zeitpunkt des Speicherns steht dem Redakteur in beiden Clients ein Report zur Auswahl eines Videos zur Verfügung.

Schlägt der Login für einen gültigen Usernamen innerhalb einer Stunde fünfmal fehl, ist der Account anschließend für eine Stunde gesperrt. Der User wird darüber per E-Mail informiert. Die Entsperrung erfolgt automatisch nach dem Ablauf der Stunde.

Standard MI24-VideoManager Pro: Der angegebene technische movingimage-Benutzer kann potenziell Zugriff auf mehrere VideoManager-Instanzen besitzen. In diesem Fall ist im Tab MI24-VideoManager Pro die Instanz zu wählen, die standardmäßig für die Auswahl eines Videos verwendet werden soll. Dafür muss über den Button Konfiguration testen & aktualisieren initial die Liste der verfügbaren Instanzen für den technischen Benutzer abgerufen werden. Ist dem Benutzer lediglich eine VideoManager-Instanz zugeordnet, wird diese automatisch als Standard-Wert übernommen.

Abbildung 2. Konfigurationsdialog der VideoManager Pro der Projekt-Komponente

Das Wechseln der standardmäßigen VideoManager-Instanz kann zu Formularfehlern führen, da die verfügbaren Video-Player ebenfalls innerhalb der Instanz definiert werden. Das Video kann dennoch innerhalb der Vorschau und später im Live-Stand angezeigt werden.

2.2. Hinzufügen der Web-Komponente

Für die Vorschau und den ContentCreator muss eine Web-Komponente hinzugefügt werden. Öffnen Sie hierfür den Server-Manager und wählen Sie den Bereich Projekt-Eigenschaften Web-Komponenten.

Abbildung 3. Web-Komponenten in den Projekt-Eigenschaften

Innerhalb des Hauptpanels sind verschiedene Registerkarten zu sehen, die jeweils eine Liste der bereits vorhandenen Web-Komponenten enthalten. Selektieren Sie nach dem Klicken auf Hinzufügen für die initial ausgewählte Registerkarte Vorschau die VideoManagementPro Web Application und bestätigen Sie die Auswahl mit OK. Installieren und aktivieren Sie die Web-Komponente anschließend auf einem aktiven Webserver. Dieser kann über die Auswahlbox gewählt werden.

Wiederholen Sie diesen Vorgang für den ContentCreator. Die Liste im Hauptpanel ist anschließend für beide Registerkarten um die Web-Komponente ergänzt (vgl. Abbildung Web-Komponenten in den Projekt-Eigenschaften).

Detaillierte Informationen zum Hinzufügen von Web-Komponenten finden Sie in der FirstSpirit Web-Komponenten Dokumentation.

3. Anpassungen im Projekt

Nach der Installation und Konfiguration der verschiedenen Komponenten müssen innerhalb des Projekts diverse Anpassungen vorgenommen werden, um die Einbettung von movingimage-Videos zu ermöglichen. Diese Anpassungen werden in den nachfolgenden Unterkapiteln anhand einer beispielhaften Absatzvorlage erläutert. Die Vorlage dient der Referenzierung sowie Ausgabe von Videos und stellt eine Grundlage für projektspezifische und komplexe Lösungen dar.

Der vollständige Ausgabekanal ist im Kapitel Ausgabekanal der Absatzvorlage zu finden.

3.1. Skript zur Abfrage von Embed Codes

Für die Einbettung von movingimage-Videos in einer Seite werden sogenannte Embed Codes benötigt. Die Codes lassen sich über die im VideoManagementPro-Modul enthaltene Executable GetVideoEmbedCode vom VideoManager Pro abfragen. Dafür erwartet sie die folgenden Parameter:

Tabelle 1. Parameter der Executable 'GetVideoEmbedCode'
Datentyp	Objektname	Beschreibung
java.util.List	videoIds	Die Ids der Videos, deren Embed Codes abgefragt werden.
java.util.Map	parameters	Die Parameter, die an die Anfrage-URL gehängt werden. Die Schlüssel dieser Map entsprechen den Schlüsseln der verfügbaren URL-Parameter von movingimage. Aktuell wird lediglich der nicht-optionale Parameter `player_definition_id` unterstützt.

Soll die Executable in einer (Absatz-)Vorlage verwendet werden, muss ein Skript mit dem Referenznamen getvideoembedcode angelegt werden:

Skript zur Abfrage von Embed Codes

#!executable-class
GetVideoEmbedCode

Das Skript muss sich auf den Geltungsbereich Vorlage beziehen. Wird ein anderer Geltungsbereich gewählt, kommt es zu Fehlern während der Generierung. Er kann in den Eigenschaften des Skripts angepasst werden.

Abbildung 4. Geltungsbereich

Ist die Option Diesen Nutzer in der Preview verwenden deaktiviert, fordert die Executable den Redakteur in der Vorschau zur Eingabe seiner movingimage-Zugangsdaten auf. Diese Zugangsdaten werden für die Dauer der Client-Sitzung vorgehalten, sodass nur eine einmalige Authentifizierung notwendig ist.

3.2. Platzhalterbild

Ist im Konfigurationsdialog der Projekt-Komponente die Option Diesen Nutzer in der Preview verwenden deaktiviert, wird in der Vorschau eine Authentifizierung des Redakteurs notwendig. Solange er diese nicht vorgenommen hat, wird ihm anstelle des Videos lediglich ein Platzhalterbild angezeigt. Gleiches gilt für den Fall, dass ihm das Sichtbarkeitsrecht für das Video fehlt.

Da die in diesem Dokument vorgestellte Lösung lediglich ein Beispiel darstellt, ist das Platzhalterbild nicht in der Auslieferung erhalten. In Zusammenhang mit der Verwendung der im nachfolgenden Kapitel beschriebenen Absatzvorlage muss es daher manuell angelegt werden und zwingend den Referenznamen dummy_video erhalten.

3.3. Absatzvorlage

Die Einbindung von movingimage-Videos in ein FirstSpirit-Projekt kann auf verschiedenste Weisen erfolgen. Die jeweils optimale Umsetzung muss daher immer individuell und auf Basis der bestehenden projektspezifischen Anforderungen ermittelt werden.

Die folgenden Unterkapitel skizzieren eine solche Umsetzung anhand einer Absatzvorlage.

3.3.1. Formular

Für die Referenzierung von Videos in einer Absatzvorlage muss diese zunächst über ein entsprechendes Formular verfügen. Das Formular benötigt mindestens:

eine FS_INDEX-Komponente zur Speicherung der Video-Id
eine Komponente zur Auswahl des Players (z.B. eine CMS_INPUT_COMBOBOX).

In der folgenden beispielhaften Formulardefinition ist darüber hinaus ein FS_BUTTON enthalten, der den VideoManager öffnet.

Formulardefinition der Absatzvorlage

<CMS_MODULE>
    <FS_INDEX name="st_video" height="1">
        <LANGINFOS>
            <LANGINFO lang="*" label="Video"/>
        </LANGINFOS>
        <SOURCE name="videomanagementpro-fsm/VideoManagementProPlugin"/> (1)
    </FS_INDEX>

    <CMS_INPUT_COMBOBOX name="st_playerDefinition"
    allowEmpty="no" noBreak="yes" useLanguages="no">
        <CMS_INCLUDE_OPTIONS type="public">
            <LABELS>
                <LABEL lang="*">#item</LABEL>
                <LABEL lang="DE">#item</LABEL>
            </LABELS>
            <NAME>MI24PlayerValueProvider</NAME>
        </CMS_INCLUDE_OPTIONS>
        <LANGINFOS>
            <LANGINFO lang="*" label="Player" description="Player"/>
        </LANGINFOS>
    </CMS_INPUT_COMBOBOX>

    <FS_BUTTON name="st_videoManager" hFill="no" noBreak="no"
    onClick="class:ExternalUrlExecutable" style="button" useLanguages="no">
        <LANGINFOS>
            <LANGINFO lang="*" label="Open VideoManager" description="Open VideoManager"/>
            <LANGINFO lang="DE" label="VideoManager öffnen" description="VideoManager öffnen"/>
        </LANGINFOS>
        <PARAMS>
            <PARAM name="target">#field.st_video</PARAM> (2)
        </PARAMS>
    </FS_BUTTON>
</CMS_MODULE>

1	Das `VideoManagementProPlugin` entspricht der Quelle der `FS_INDEX`-Komponente. Es muss zwingend in der dargestellten Form angegeben werden.
2	Der Parameter des `FS_BUTTONs` muss zwingend den Namen `target` besitzen und auf die `FS_INDEX`-Komponente verweisen. Gegebenenfalls muss der Bezeichner projektspezifisch angepasst werden.

Besitzt die verwendete Seitenvorlage ihrerseits einen FS_BUTTON zum Anlegen neuer Absätze, können Videos per Drag & Drop auf diesen Button in einem neuen Video-Absatz eingebunden werden. Dafür muss die FS_INDEX-Komponente in den Eigenschaften des Absatzes als Drop-Editor gesetzt werden.

3.3.2. Regeln

Soll der Absatz jeweils nur ein Video aufnehmen können, muss das Hinzufügen mehrerer Elemente für die FS_INDEX-Komponente unterbunden werden. Dies lässt sich durch die folgende Regel realisieren:

Regeldefinition der Absatzvorlage

<RULES>
    <RULE>
        <WITH>
            <EQUAL>
                <PROPERTY name="SIZE" source="st_video"/>
                <NUMBER>0</NUMBER>
            </EQUAL>
        </WITH>
        <DO>
            <PROPERTY name="ADD" source="st_video"/>
        </DO>
    </RULE>
</RULES>

Die Regel prüft, ob die Anzahl der in der Eingabekomponente st_video eingebundenen Elemente gleich Null ist. Liefert die Prüfung true zurück, ist der Hinzufügen-Button der FS_INDEX-Komponente aktiviert. Sobald ein Video eingebunden ist, liefert die Prüfung false zurück und der Button wird ausgegraut.

3.3.3. Ausgabekanal

Der HTML-Ausgabekanal der Absatzvorlage besitzt auf der obersten Ebene einen div-Container. Dieser steuert die Ausgabe des in der FS_INDEX-Komponente referenzierten Videos. Dabei sind die Vorschau und die Generierung getrennt voneinander zu behandeln. Nach der Ausgabe wird ein script-Tag definiert, welches erforderliche JavaScript-Funktionen von movingimage nachlädt.

Soll eine Seite mehrere Videoabsätze besitzen können, muss das script-Tag in der verwendeten Seitenvorlage platziert werden. Andernfalls wird es für jeden Absatz und somit mehrfach in die Seite integriert.

<div $CMS_VALUE(editorId())$ >
    $CMS_IF(!st_video.empty)$
        $CMS_SET(set_videoIds, st_video.getIdentifiers())$

        $CMS_IF(!#global.preview)$
            $-- Render video --$
        $CMS_ELSE$
            $-- Render video in the preview --$
        $CMS_END_IF$

        <script src="//e.video-cdn.net/v2/embed.js"></script>
    $CMS_END_IF$
</div>

Generierung

Für die Anzeige eines Videos im generierten Stand muss die Executable GetVideoEmbedCode ausgeführt werden. Diese benötigt ihrerseits die Id des referenzierten Videos sowie die ausgewählte Player-Id. Der Aufruf geschieht über das bereits vorgestellte Skript. Das Ergebnis der Executable wird in einem weiteren div-Container ausgegeben.

$CMS_SET(set_params, {"player_definition_id":st_playerDefinition.getKey()})$ (1)
$CMS_RENDER(script:"getvideoembedcode", videoIds: set_videoIds, parameters: set_params)$ (2)

$CMS_IF(!embedCodes.isEmpty)$
    <div id="$CMS_VALUE(set_videoIds[0])$_$CMS_VALUE(#this.id)$_container"> (3)
        $CMS_VALUE(embedCodes.get(set_videoIds[0]))$ (4)
    </div>
$CMS_END_IF$

1	Zunächst erfolgt die Ermittlung der Id des ausgewählten Players.
2	Anschließend erfolgt die Ausführung der Executable `GetVideoEmbedCode`.
3	Der `div`-Container, in dem das Video dargestellt wird, erhält eine eindeutige Id.
4	Innerhalb dieses Containers wird der Embed Code ausgegeben.

Der Player in Zeile 4 kann über ein sogenanntes VideoStill eine bestimmte Breite annehmen. Ist dies gewünscht, muss zunächst die Liste aller VideoStills ermittelt und auf die gewünschte Auflösung eingeschränkt werden.

$CMS_IF(!st_video.values.isEmpty)$
        $CMS_SET(set_videoStill, st_video.values[0].getStill("thumbnail"))$
$CMS_END_IF$

Die Ermittlung des VideoStills ist in dem voranstehenden Codebeispiel vor dem div-Tag einzufügen. Die Einschränkung der Breite des ausgewählten Players erfolgt über ein CMS_IF, welches dem div-Tag als weiteres Attribut hinzuzufügen ist. Damit ergibt sich folgender Code für das öffnende div-Tag:

<div id="$CMS_VALUE(set_videoIds[0])$_$CMS_VALUE(#this.id)$_container" $CMS_IF(!set_videoStill.isNull)$style="width: $CMS_VALUE(set_videoStill.dimension.width)$px;"$CMS_END_IF$>

Weitere Dokumentation über die verwendeten Methoden und Objekte können der JavaDoc-Dokumentation entnommen werden.

Vorschau

Ist im Konfigurationsdialog der Projekt-Komponente die Option Diesen Nutzer in der Preview verwenden deaktiviert, wird in der Vorschau eine Authentifizierung des Redakteurs notwendig. Solange er diese nicht vorgenommen hat, wird ihm anstelle des Videos lediglich ein Platzhalterbild angezeigt. Des Weiteren können einige Videos für gewisse Benutzergruppen gesperrt sein. Beide Fällen müssen sich in der FirstSpirit-Vorschau widerspiegeln.

Die Funktionalitäten des VideoManagementPro-Moduls können nicht in Verbindung mit der externen FirstSpirit-Vorschau verwendet werden.

Dafür wird zunächst ein weiterer div-Container definiert. Dieser besitzt eine eindeutige Id und nimmt entweder das referenzierte Video oder das Platzhalterbild auf. Anschließend werden die folgenden JavaScript-Funktionen definiert:

checkUser
showVideoDummy
renderVideo
waitAndRender

<div
    $CMS_VALUE(editorId(editorName:"st_video"))$
    id="$CMS_VALUE(set_videoIds[0])$_$CMS_VALUE(#this.id)$_container">
</div>
<script>
    $-- Functions --$
</script>

checkUser

Die erste Funktion checkUser prüft, ob der Redakteur sich in der Vorschau bereits authentifiziert hat oder nicht. Abhängig davon initiiert sie die Anzeige des referenzierten Videos bzw. des Platzhalterbilds.

function checkUser(api, videoIds, sectionTemplateId) {
    api.execute(
        "class:com.espirit.moddev.videomanagementpro.IsUserAuthenticatedExecutable", (1)
        {},
        function (result) {
            if (result.authenticated == "true") {
                renderVideo(api, videoIds, sectionTemplateId); (2)
            } else {
                showVideoDummy(api, videoIds, sectionTemplateId); (3)
            }
        }
    );
}

1	Die Executable `IsUserAuthenticatedExecutable` prüft die Authentifizierung des Redakteurs.
2	Ist der Redakteur bereits authentifiziert, wird durch die Funktion `renderVideo` das Video dargestellt.
3	Andernfalls wird das Platzhalterbild durch die Funktion `showVideoDummy` angezeigt.

showVideoDummy

Die Funktion showVideoDummy fügt dem zuvor erwähnten div-Container ein Platzhalterbild hinzu, das in der Medienverwaltung unter dem Referenznamen dummy_video abgelegt ist. Des Weiteren definiert sie für dieses Bild eine Funktion für das onClick-Ereignis. Dieses Ereignis ruft die Funktion renderVideo auf, welche die Authentifizierung des Redakteurs sowie die Anzeige des Videos veranlasst.

function showVideoDummy (api, videoIds, sectionTemplateId) {
    for (var videoIndex in videoIds) {
        var videoId = videoIds[videoIndex];
        var dummyVideo = document.createElement("img"); (1)

        dummyVideo.setAttribute('src', '$CMS_REF(media:"dummy_video")$'); (1)
        dummyVideo.onclick = function () { (2)
            renderVideo(api, videoIds, sectionTemplateId); (2)
        };

        var containerId = videoId + "_" + sectionTemplateId + "_container"; (3)
        var container = document.getElementById(containerId); (3)
        if (container) {
            container.appendChild(dummyVideo); (4)
        }
    }
}

1	Es wird ein neues `img`-Element erzeugt, in dem das Platzhalterbild enthalten ist.
2	Ein Anklicken des Platzhalterbilds veranlasst die Authentifizierung des Redakteurs und die Anzeige des Videos.
3	Der zuvor erwähnte `div`-Container wird ermittelt.
4	Das Platzhalterbild wird dem ermittelten `div`-Container hinzugefügt.

renderVideo

Die Funktion renderVideo ruft die Executable GetVideoEmbedCode auf. Diese Executable fordert den Redakteur zur Eingabe seiner Zugangsdaten auf, falls dies notwendig ist, und ruft anschließend den Embed Code des referenzierten Videos von movingimage ab.

Nach dem Abschluss der Executable ermittelt die Funktion den zuvor erwähnten div-Container. Ihm fügt sie den Embed Code hinzu, wenn der Redakteur das Sichtbarkeitsrecht für das Video besitzt. Andernfalls wird dem Redakteur ein entsprechender Text angezeigt.

function renderVideo(api, videoIds, sectionTemplateId) {
    var params = {};
    params['player_definition_id'] = "$CMS_VALUE(st_playerDefinition)$"; (1)
    api.execute( (2)
        "class:com.espirit.moddev.videomanagementpro.GetVideoEmbedCode",
        { "videoIds": videoIds, "parameters": params },
        function (result) {
            try {
                for (var videoId in result) {
                    var containerId = videoId + "_" + sectionTemplateId + "_container"; (3)
                    var container = document.getElementById(containerId); (3)
                    var embedCode = result[videoId];

                    if(container) {
                        if (embedCode) {
                            container.innerHTML = embedCode; (4)
                            VideoPlayer.Collection.addPlayerById(containerId); (5)
                        } else {
                            container.innerHTML = "You do not have access rights for this video."; (6)
                        }
                    }
                }
            } catch (e) {
                console.error("Error in executable callback handler: " + e);
            }
        }
    );
}

1	Zunächst fragt die Funktion die Id des ausgewählten Players ab.
2	Des Weiteren führt sie die Executable `GetVideoEmbedCode` aus.
3	Anschließend ermittelt sie den zuvor erwähnten `div`-Container für die Ausgabe des Videos bzw. des Hinweises.
4	Besitzt der Redakteur das Sichtbarkeitsrecht, wird dem `div`-Container der Embed Code des Videos hinzugefügt.
5	Außerdem wird der ausgewählte Player ergänzt.
6	Fehlt dem Redakteur das Sichtbarkeitsrecht, erhält er einen entsprechenden Hinweis.

waitAndRender

Die Funktionen checkUser, showVideoDummy und renderVideo besitzen alle einen Parameter api, der für den Aufruf einer Executable benötigt wird. Abhängig vom verwendeten FirstSpirit-Client wird für den Parameter entweder das Objekt top.WE_API.Common (ContentCreator) oder JC_API (SiteArchitect) übergeben. Da die JC_API erst nach einer gewissen Zeit verfügbar ist, muss vor der Ausführung der beschriebenen Funktionen zunächst auf sie gewartet werden. Dies steuert die Funktion waitAndRender, die nur im SiteArchitect definiert wird.

$CMS_IF(!#global.is("WEBEDIT"))$
    function waitAndRender(videoIds, sectionTemplateId) {
        try {
            if (typeof JC_API === "undefined") { (1)
                window.onBrowserInjection = function(name, injected) { (2)
                    if (name === 'JC_API') {
                        checkUser(JC_API, videoIds, sectionTemplateId);
                    }
                };
            } else {
                checkUser(JC_API, videoIds, sectionTemplateId); (3)
            }
        } catch (e) {
            console.error("waitAndRender:" + e);
        }
    }
$CMS_END_IF$

1	Die Funktion prüft zuerst die Verfügbarkeit der `JC_API`.
2	Ist die `JC_API` noch nicht verfügbar, wird die Funktion `checkUser` erst zum Zeitpunkts des entsprechenden Events ausgeführt.
3	Ist die `JC_API` bereits initial verfügbar, wird die Funktion `checkUser` sofort aufgerufen.

Als Einstieg in die genannten Funktionen wird abschließend ein Skript benötigt. Dieses ruft im SiteArchitect zunächst die Funktion waitAndRender auf, während sie im ContentCreator direkt mit der Funktion checkUser startet.

try {
    $CMS_IF(#global.is("WEBEDIT"))$
        checkUser( (1)
            top.WE_API.Common,
            $CMS_VALUE(set_videoIds.map(x -> "\"" + x + "\"").toString())$, (2)
            $CMS_VALUE(#this.id)$);
    $CMS_ELSE$
        waitAndRender( (3)
            $CMS_VALUE(set_videoIds.map(x -> "\"" + x + "\"").toString())$, (2)
            $CMS_VALUE(#this.id)$);
    $CMS_END_IF$
} catch (e) {
    console.error(e);
}

1	Im ContentCreator kann direkt die Authentifizierung des Redakteurs und damit die Anzeige des Videos bzw. Platzhalterbilds veranlasst werden.
2	Die Funktion `checkUser` erwartet die Id des Videos, die aus der Liste extrahiert und zwischen Anführungszeichen gestellt werden muss.
3	Im SiteArchitect muss zunächst auf die Verfügbarkeit der `JC_API` gewartet werden. Dies regelt wie beschrieben die Funktion `waitAndRender`.

4. Verwendung in FirstSpirit

Mit der Installation des VideoManagementPro-Moduls und den vorgenommenen Anpassungen im Projekt wurden in beiden FirstSpirit-Clients verschiedene Funktionalitäten für die Referenzierung von movingimage-Videos bereitgestellt. Diese sind in beiden Clients äquivalent und werden nachfolgend anhand eines Beispiels Schritt für Schritt erläutert. Die Beschreibung konzentriert sich auf den ContentCreator. Grundsätzlich ist die Referenzierung eines Videos jedoch in beiden FirstSpirit-Clients möglich.

Das Beispiel ist auf einer beliebigen Seite nachvollziehbar, die jedoch die zuvor erstellte Absatzvorlage referenzieren können muss.

Da die movingimage-Seite vollständig responsiv ist, wird diese bei einer Breite unter 768 Pixel nur eingeschränkt dargestellt.

4.1. Auswahl eines Videos

Sowohl im SiteArchitect als auch im ContentCreator stellt das Modul einen VideoManagementPro-Report bereit. Dieser Report dient der Darstellung der aus dem VideoManager Pro stammenden Videos. Initial ist die Anzeige auf 25 Videos beschränkt. Sie wird beim Herunterscrollen dynamisch erweitert, bis die Gesamtanzahl aller verfügbaren Videos erreicht ist. Über das Suchfeld des Reports kann die Liste nach einem Schlagwort gefiltert werden. Außerdem ermöglichen die zwei Auswahllisten die Angabe von Sortierkriterien. Standardmäßig sortiert der Report die Videos absteigend nach ihrem Erstellungsdatum.

Ist die Option Diesen Nutzer in der Preview verwenden im Konfigurationsdialog der Projekt-Komponente deaktiviert, muss sich der Redakteur vor der Verwendung des Reports zunächst authentifizieren. Der dabei verwendete Benutzeraccount und der in der Projektkomponente angegebene technische Benutzer müssen demselben Hauptaccount zugeordnet sein.

Der verwendete Benutzer darf auf movingimage-Seite nur einem einzigen VideoManager Pro-Account zugeordnet sein. Andernfalls kommt es FirstSpirit-seitig zu Einschränkungen.

Die Anzeige des Reports erfolgt nur dann, wenn die während der Installation hinzugefügte Projekt-Komponente vollständig konfiguriert ist.

Die Liste im Report zeigt für jeden Eintrag jeweils den Titel und die Beschreibung eines Videos an. Besitzt ein Video keine Beschreibung, sind stattdessen standardmäßig drei Bindestriche sichtbar. Darüber hinaus werden im Flyout ein Vorschaubild und die Länge des Videos sowie der Zeitpunkt des Hochladens und die Anzahl der Aufrufe abgebildet. Das Flyout öffnet sich automatisch beim Überfahren eines Videoeintrags im Report.

4.2. Einbinden eines Videos

Die Einbindung eines zuvor ausgewählten Videos kann in diesem Beispiel nur in einem auf der zuvor erstellten Vorlage basierenden Absatz erfolgen.

Besitzt die Seite noch keinen solchen Absatz, kann dieser potenziell per Drag-and-Drop des gewünschten Videos auf einen FS_BUTTON angelegt werden. Dies ist nur möglich, wenn die Seite einen FS_BUTTON zum Erzeugen von Absätzen besitzt. Des Weiteren muss die FS_INDEX-Eingabekomponente der Absatzvorlage als Drop-Editor definiert sein. In diesem Fall wird das Video automatisch in der Komponente eingebunden. Andernfalls ist der Absatz manuell zu erstellen.

Besitzt die Seite bereits einen entsprechenden Absatz, lässt sich das ausgewählte Video in der FS_INDEX-Komponente des Absatzes einbinden. Dies kann per Drag-and-Drop aus dem Report heraus auf die Eingabekomponente im Bearbeitungsdialog erfolgen. Alternativ besitzt die Komponente einen Hinzufügen-Button, der einen Auswahldialog öffnet. In diesem sind ebenfalls alle zur Verfügung stehenden Videos aufgelistet.

Die Speicherung der Auswahl geschieht über den gleichnamigen Button.

4.3. Video bearbeiten

Die Einbindung eines aus dem VideoManager Pro stammenden Videos auf einer Seite erfolgt lediglich durch seine Referenzierung. Das bedeutet, dass innerhalb des FirstSpirit-Projekts keine Informationen persistiert werden. Aus diesem Grund muss jegliche Änderung an einem Video direkt im VideoManager Pro durchgeführt werden.

Jeder Eintrag im VideoManagementPro-Report besitzt daher den Button External view (vgl. Abbildung Button 'External view'). Er erscheint beim Überfahren des Eintrags und öffnet das entsprechende Video zur Bearbeitung im VideoManager Pro. Der SiteArchitect nutzt für die Anzeige des VideoManager Pro einen neuen Tab im Vorschau-Bereich, wohingegen der ContentCreator einen neuen Browser-Tab erzeugt.

Der Browser erkennt den neuen Tab eventuell als Popup und unterdrückt ihn bei entsprechenden Einstellungen. In diesem Fall muss sein Anzeigen manuell erlaubt werden.

Detaillierte Informationen zur Bearbeitung eines Videos sind in der Dokumentation des VideoManager Pro enthalten: http://doc.movingimage.com/display/VPH/Videodaten+bearbeiten

Abbildung 6. Button 'External view'

4.4. Statistiken eines Videos anzeigen

Die Einbindung eines Videos auf einer Seite ist nur dann sinnvoll, wenn es bei den Besuchern der Live-Seite eine Resonanz hervorruft. Es ist daher empfehlenswert die Wirksamkeit eines Videos in regelmäßigen Abständen zu überprüfen. Der VideoManager Pro erfasst daher für jedes Video Statistiken, die in FirstSpirit allerdings nicht unmittelbar verfügbar sind.

Stattdessen stellt die in diesem Dokument beschriebene Absatzvorlage einen Button VideoManager öffnen bereit (vgl. Abbildung Schaltfläche 'VideoManager öffnen'). Dieser öffnet den VideoManager Pro, in dem nach der Auswahl des Videos die Statistiken einsehbar sind. Wurde noch kein Video referenziert, besitzt der Button keine Funktion. Der SiteArchitect nutzt für die Anzeige des VideoManager Pro einen neuen Tab im Vorschau-Bereich, wohingegen der ContentCreator einen neuen Browser-Tab erzeugt.

Der Browser erkennt den neuen Tab eventuell als Popup und unterdrückt ihn bei entsprechenden Einstellungen. In diesem Fall muss sein Anzeigen manuell erlaubt werden.

Da die movingimage-Seite vollständig responsiv ist, wird diese bei einer Breite unter 768 Pixel nur eingeschränkt dargestellt.

Detaillierte Informationen zu den Statistiken sind in der Dokumentation des VideoManager Pro enthalten: http://doc.movingimage.com/display/VPH/Statistik

Abbildung 7. Schaltfläche 'VideoManager öffnen'

4.5. Authentifizierung

Für die Generierung der im Projekt eingebundenen Videos muss der FirstSpirit-Server mit dem VideoManager Pro kommunizieren. Aus diesem Grund ist im Konfigurationsdialog der Projekt-Komponente ein technischer User anzugeben. Dieser User lässt sich auch für die Darstellung der Videos in beiden FirstSpirit-Clients verwenden. Dafür muss die ebenfalls im Konfigurationsdialog enthaltene Option Diesen Nutzer in der Preview verwenden aktiviert werden.

Der verwendete User darf auf movingimage-Seite nur einem einzigen VideoManager Pro-Account zugeordnet sein. Andernfalls kommt es FirstSpirit-seitig zu Einschränkungen.

Initial ist diese Option nach der Installation des VideoManagementPro-Moduls deaktiviert. In diesem Fall muss sich ein Redakteur in beiden FirstSpirit-Clients zunächst authentifizieren, bevor er die Funktionen des VideoManagementPro-Moduls nutzen kann. Der dabei verwendete Benutzeraccount und der in der Projektkomponente angegebene technische Benutzer müssen demselben Hauptaccount zugeordnet sein. Für die Authentifizierung öffnet sich ein entsprechender Dialog zur Eingabe seiner Login-Daten, sobald der Redakteur:

den Report des VideoManagementPro-Moduls öffnet,
ein Video über die FS_INDEX-Komponente des Absatzes referenziert oder
in der Vorschau das Platzhalterbild eines eingebundenen Videos anklickt.

Abbildung 8. Authentifizierungsdialog

Falls die Anmeldung fehlschlägt, kann die gewünschte Aktion nicht ausgeführt werden. Valide Zugangsdaten werden pro Redakteur vorgehalten und erst beim Beenden der Client-Sitzung verworfen. Dies bedeutet, dass pro Client-Sitzung nur eine einmalige Authentifizierung notwendig ist.

5. Appendix

5.1. Ausgabekanal der Absatzvorlage

Vollständiger HTML-Ausgabekanal der Beispielabsatzvorlage

<div $CMS_VALUE(editorId())$ >
    $CMS_IF(!st_video.empty)$
        $CMS_SET(set_videoIds, st_video.getIdentifiers())$
        $CMS_IF(!st_video.values.isEmpty)$
            $CMS_SET(set_videoStill, st_video.values[0].getStill("thumbnail"))$
        $CMS_END_IF$

        $CMS_IF(!#global.preview)$
            $CMS_SET(set_params, {"player_definition_id":st_playerDefinition.getKey()})$
            $CMS_RENDER(script:"getvideoembedcode", videoIds: set_videoIds, parameters: set_params)$

            $CMS_IF(!embedCodes.isEmpty)$
                <div
                        id="$CMS_VALUE(set_videoIds[0])$_$CMS_VALUE(#this.id)$_container"
                        $CMS_IF(!set_videoStill.isNull)$style="width: $CMS_VALUE(set_videoStill.dimension.width)$px;"$CMS_END_IF$>
                    $CMS_VALUE(embedCodes.get(set_videoIds[0]))$
                </div>
            $CMS_END_IF$
        $CMS_ELSE$
            <div
                    $CMS_VALUE(editorId(editorName:"st_video"))$
            id="$CMS_VALUE(set_videoIds[0])$_$CMS_VALUE(#this.id)$_container"
            $CMS_IF(!set_videoStill.isNull)$style="width: $CMS_VALUE(set_videoStill.dimension.width)$px;"$CMS_END_IF$>
            </div>

            <script>
                function checkUser(api, videoIds, sectionTemplateId) {
                    api.execute(
                        "class:com.espirit.moddev.videomanagementpro.IsUserAuthenticatedExecutable",
                        {},
                        function (result) {
                            if (result.authenticated == "true") {
                                renderVideo(api, videoIds, sectionTemplateId);
                            } else {
                                showVideoDummy(api, videoIds, sectionTemplateId);
                            }
                        }
                    );
                }

                function showVideoDummy (api, videoIds, sectionTemplateId) {
                    for (var videoIndex in videoIds) {
                        var videoId = videoIds[videoIndex];
                        var dummyVideo = document.createElement("img");
                        dummyVideo.setAttribute('src', '$CMS_REF(media:"dummy_video")$');
                        dummyVideo.onclick = function () {
                            renderVideo(api, videoIds, sectionTemplateId);
                        };
                        var containerId = videoId + "_" + sectionTemplateId + "_container";
                        var container = document.getElementById(containerId);
                        if (container) {
                            container.appendChild(dummyVideo);
                        }
                    }
                }

                function renderVideo(api, videoIds, sectionTemplateId) {
                    var params = {};
                    params['player_definition_id'] = "$CMS_VALUE(st_playerDefinition)$";
                    api.execute(
                        "class:com.espirit.moddev.videomanagementpro.GetVideoEmbedCode",
                        { "videoIds": videoIds, "parameters": params },
                        function (result) {
                            try {
                                for (var videoId in result) {
                                    var containerId = videoId + "_" + sectionTemplateId + "_container";
                                    var container = document.getElementById(containerId);
                                    var embedCode = result[videoId];
                                    if(container) {
                                        if (embedCode) {
                                            container.innerHTML = embedCode;
                                            VideoPlayer.Collection.addPlayerById(containerId);
                                        } else {
                                            container.innerHTML = "You do not have access rights for this video.";
                                        }
                                    }
                                }
                            } catch (e) {
                                console.error("Error in executable callback handler: " + e);
                            }
                        }
                    );
                }

                $CMS_IF(!#global.is("WEBEDIT"))$
                    function waitAndRender(videoIds, sectionTemplateId) {
                        try {
                            if (typeof JC_API === "undefined") {
                                window.onBrowserInjection = function(name, injected) {
                                    if (name === 'JC_API') {
                                        checkUser(JC_API, videoIds, sectionTemplateId);
                                    }
                                };
                            } else {
                                checkUser(JC_API, videoIds, sectionTemplateId);
                            }
                        } catch (e) {
                            console.error("waitAndRender:" + e);
                        }
                    }
                $CMS_END_IF$

                try {
                    $CMS_IF(#global.is("WEBEDIT"))$
                    checkUser(
                        top.WE_API.Common,
                        $CMS_VALUE(set_videoIds.map(x -> "\"" + x + "\"").toString())$,
                        $CMS_VALUE(#this.id)$);
                    $CMS_ELSE$
                    waitAndRender(
                        $CMS_VALUE(set_videoIds.map(x -> "\"" + x + "\"").toString())$,
                        $CMS_VALUE(#this.id)$);
                    $CMS_END_IF$
                } catch (e) {
                    console.error(e);
                }
            </script>
        $CMS_END_IF$

        <script src="//e.video-cdn.net/v2/embed.js"></script>

    $CMS_END_IF$
</div>

6. Rechtliche Hinweise

Das VideoManagementPro-Modul ist ein Produkt der Crownpeak Technology GmbH, Dortmund, Germany.

Für die Verwendung des Modules gilt gegenüber dem Anwender nur die mit der Crownpeak Technology GmbH vereinbarte Lizenz.

Details zu möglicherweise fremden, nicht von der Crownpeak Technology GmbH hergestellten, eingesetzten Software-Produkten, deren eigenen Lizenzen und gegebenenfalls Aktualisierungsinformationen, finden Sie in der Datei META-INF/licenses.csv, die mit dem Modul ausgeliefert wird.

7. Hilfe

Der Technical Support der Crownpeak Technology GmbH bietet qualifizierte technische Unterstützung zu allen Themen, die FirstSpirit™ als Produkt betreffen. Weitere Hilfe zu vielen relevanten Themen erhalten und finden Sie in auch in unserer Community.

Dokumentation

für die Version 1.8.0
Aktualisiert: 09.04.2024

Unternehmen

Kontakt

Crownpeak Technology GmbH
Stockholmer Allee 24
44269 Dortmund, DE
+49 231 477 77 0
Kontaktieren Sie uns