inf-schule | Interaktive Elemente » Vue Custom Elements

Vue Custom Elements

Es ist möglich mithilfe des Frameworks Vue Elemente für inf-schule zu erstellen. Man spricht in diesem Zusammenhang von Custom Elements.

Vorbereiten der Entwicklungsumgebung

Zur Vorbereitung der Entwicklungsumgebung müssen die Pakete vue und vue-cli installiert werden. Dafür ist es sinnvoll, einen Package-Manager wie z.B. npm zu verwenden. Am einfachsten installiert man node.js, dort ist npm integriert. Die folgenden Terminal-Befehle gelten für npm, dabei steht das -g dafür, dass die Pakete global installiert werden:

sudo npm install -g vue
sudo npm install -g @vue/cli

Vorbereiten des Projektes

Navigiere im Terminal in ein Verzeichnis, in dem der Projektordner erstellt werden soll. Das Projekt wird dann mit dem Befehl vue create projektname initiiert. Die folgende Konfiguration sollte gewählt werden:

"Manually select features"
per Leertaste die folgenden Pakete auswählen: "Choose Vue version", "Babel", "CSS Pre-processors" und "Linter/Formatter" -> Enter
Vue Version 3.x auswählen -> Enter
Use class-style component syntax? -> Yes -> Enter
Use Babel alongside TypeScript (required for modern mode, auto-detected polyfi lls, transpiling JSX)? -> Yes -> Enter
Den CSS Pre-processor "Sass/SCSS (with darat-sass)" auswählen -> Enter
Den linter/formatter "ESLint + Airbnb config" auswählen -> Enter
Additional Lint-Features "Lint on save" auswählen -> Enter
Where do you prefer placing config for Babel, ESLint, etc.? -> In dedicated config files -> Enter
Diese Konfigurations-Vorlage kann optional für spätere Projekte gespeichert werden.

Anschließend wird das Projekt vorbereitet. Die Befehle sollte ohne Fehler ausgeführt werden. Sollten Fehler auftreten, fehlen eventuell noch Pakete, die dann nachinstalliert werden müssten und anschließend muss das Projekt neu initiiert werden.

Test der Entwicklungsumgebung

Die Entwicklungsumgebung bietet die Möglichkeit, das Projekt lokal ohne weiteren Webserver zu testen. Dafür im Terminal in das Verzeichnis des Projektes navigieren und den Befehl npm run serve ausführen. Nach ein paar Sekunden sollte im Terminal nun eine Adresse und ein Port erscheinen, unter dem das Projekt erreichbar ist, falls es keine Fehler gibt. Der Server kann im Hintergrund weiterlaufen und überwacht die Änderungen im Projekt. Wird eine Projektdatei verändert und gespeichert, so wird das Projekt aktualisiert und die Seite im Brower neu geladen, sodass die Änderungen direkt geprüft werden können. Den Server beendet man wie üblich über die Tastenkombination "control + c".

Konfiguration als Custom Element vornehmen

Der Befehl npm run build erzeugt aktuell noch eine komplette Vue-App, die sich nicht als einzelnes Element in inf-schule einbauen lässt. Folgende Änderungen sind dafür nötig:

./src/components/

Die Komponenten benötigen als Dateinamen am Ende ein .ce.vue. Als Beispiel wird auch für die weitere Konfiguration davon ausgeganen, dass es eine Komponente mit dem Dateinamen Komponente1.ce.vue gibt.

./src/main.js

In dieser Datei wird festgelegt, welche Komponenten des Projektes in der späteren Datei vorhanden sein sollen. In Zeile 5 wird ebenfalls der HTML-Tag festgelegt, über den die Komponente eingebunden werden kann. Die Zeile 2, sowie die Zeilen 4 und 5 müssen für jede Komponente kopiert und angepasst werden.

import { defineCustomElement } from 'vue';
import Komponente1 from './components/Komponente1.ce.vue';

const FullNameElement = defineCustomElement(Komponente1);
customElements.define('komponente-1', FullNameElement);

./vue.config.js

Diese Datei muss neu erstellt werden. Sie legt in den Zeilen 2 bis 11 fest, dass nur eine .js Datei erstellt und CSS dort implementiert wird. Die Zeile 12 legt den relativen Pfad fest, das ist nur nötig, damit die erstellte .html Datei die nötige .js findet und man das Element testen kann. Die Zeilen 13 bis 17 legen fest, dass Vue nicht integriert wird, da auf inf-schule schon global eine Instanz von Vue läuft, die genutzt werden kann. Damit wird die Dateigröße erheblich reduziert.

module.exports = {
    configureWebpack: {
        optimization: {
            splitChunks: false
        }
    },
    css: {
        extract: false,
    },
    filenameHashing: false,
    productionSourceMap: false,
    publicPath: './',
    chainWebpack: (config) => {
        config.externals({
            vue: "Vue"
        });
      },
};

./public/index.html (optional)

Diese Datei kann optional geändert werdne, damit das Element auch lokal getestet werden kann.

Im head muss die folgende Zeile ergänzt werden, damit das Element lokal läuft, da Vue ausgelagert wurde (siehe oben): <script src="https://unpkg.com/vue@next"></script>
Im body muss der HTML-Tag für das Element oder die Elemente gesetzt werden. In unserem Beispiel: <komponente-1></komponente-1>

Custom Element erstellen

Damit das Element erstellt wird, muss der Befehl npm run build ausgeführt werden. Es wird der Ordner ./dist/ erstellt. Die Datei ./dist/index.html kann mit einem Browser geöffnet werden und das Element getestet werden (falls die optonale Konfiguration der Datei ./public/index.html vorgenommen wurde, siehe oben). Wichtig für inf-schule ist jedoch nur die Datei ./dist/js/app.js.

Externe Dateien einbinden

Sollen externe Dateien eingebunden werden, so müssen diese Dateien im gleichen Ordner wie die Inhaltsdatei liegen. Vue übernimmt diese Dateien im build-Prozess in den Ordner ./dist/, wenn sie im Ordner ./public/ liegen. Im Vue Dokument kann dann mit window.location.href + "/dateiname.dateiendung" darauf verlinkt werden, sodass nach dem build-Befehl die Links passen.

Custom Element auf inf-schule einbinden

Damit das Element auf einer Inhaltsseite genutzt werden kann, müssen folgende Dateien geändert werden:

Vue-Projekt ./dist/js/app.js --> inf-schule ./assets/thirdparty/projektname/js/

Die Datei ./dist/js/app.js muss im inf-schule Repository unter ./assets/thirdparty/projektname/js/ abgelegt werden.

./site/plugins/inf-schule/config/features.json

Das Feature muss registriert werden. Dafür muss die Datei ./site/plugins/inf-schule/config/features.json angepasst werden. Hier wird die benötigten Javascript Datei im JSON-Format dem Featurenamen zugeordnet:

"projektname": {
        "js": [
            "assets/thirdparty/projektname/js/app.js"
        ]
    }

Damit das Element auf einer Inhaltsdatei genutzt werden kann, muss es über das Attribut features geladen werden. In unserem Beispiel über features: projektname. Das Element kann jetzt an passender Stelle in der Inhaltsdatei über den festgelegten HTML-Tag eingebunden werden, in unserem Beispiel <komponente-1></komponente-1>.