/typo3-playground

Primary LanguageHTML

TYPO3 mit Composer installieren

System Requirements

Zur Nutzung wird Composer und NodeJS mit NPM oder YARN benötigt: https://nodejs.org/en/

1. Vorbereitung

  • Erstelle ein neues GitHub-Repository auf Basis der Vorlage "creationell-dev/typo3-installer" (dieses Repository)
  • Stelle sicher, dass du die aktuellste Version der JPKCLI nutzt (TYPO3 11 wird ab JPKCLI-Version 1.2.2 unterstützt)
  • Lege ein leeres Projektverzeichnis in einem WSL2-Verzeichnis an und navigiere hinein: mkdir <my-project> && cd <my-project>
  • initialisiere JPKCLI (Achtung: Typ ist typo311):
j init project
  • Initialisiere Docker-Container:
j init docker && j up
  • Navigiere in den Ordner project/web und leere diesen:
cd project/web
rm * .*
  • Klone das Repository und öffne es in VS Code (Achtung: der Punkt am Ende gehört zum Befehl!)
git clone git@github.com/creationell-dev/<REPOSITORY-KEY> .
j c
  • Starte Docker
j up

2. Composer-Installation

  • Wechsle in den PHP Container:
j dc sh php
  • wechsle in das web-Verzeichnis:
cd web
  • Installiere TYPO3:
composer install
  • Folgende Daten sind bei einer Standard-Installation mit Docker/JPKCLI einzugeben
    • GitHub Token: hier kann dieser verwendet werden
    • Database connection type: mysqli oder Enter drücken
    • User name for database server: db_1
    • User password for database server: db_1
    • Host name of database serve: db
    • TCP Port of database server: Enter drücken
    • Unix Socekt to connect to: Enter drücken
    • Use already existing database: yes
    • Name of the database: db_1
    • Name of the TYPO3 site
    • Specify the site base url: http://127.0.0.1:<your-port>180 <-- the nginx_port in jpkcli.ini
    • Specify the web server you want to write configuration for: none oder Enter drücken
    • NPM auth Token für FontAwesome: zu finden hier im CNET (Token ist unten im Beschreibungsfeld hinterlegt)

3. Cleanup

  • Die Pakete creationell/crea_distribution und creationell/creationell-typo3-setup werden nicht mehr benötigt, deinstalliere diese mit composer:
composer remove creationell/crea_distribution
composer remove --dev creationell/creationell-typo3-setup
  • Lösche diese beiden Pakete auch aus dem Verzeichnis packages
  • Logge dich in das TYPO3 Backend ein (BN: creationell, PW: password)
  • Ändere das Admin Passwort (ins CNET speichern)
  • Ändere das Install Tool Passwort (ins CNET speichern)

4. Optional

  • Wenn du den Docker Proxy verwenden möchtest (empfohlen), dann inkludiere die Datei proxy.ymal in der Datei config/dev.settings.yaml und starte den Proxy (j proxy)

5. NPM-Setup

  • Wechsle in den Node Container j dc sh nodejs
  • wechsle in das web-Verzeichnis: cd html/web
  • Installiere die npm-Dependencies und kompiliere JS/SCSS: npm install && npm run dev

Features

  • Unterstützung von .env Dateien zum Setzen von Environment Variablen
  • TYPO3 & Extension Konfiguration mittels YAML-Dateien im Verzeichnis config
  • Automatisierte Installation von TYPO3 und ausgewählten Extensions
  • Automatisiertes Erstellen eines Basis-Seitenbaums mit Systemordnern für News, Suche etc.
  • Integriertes Setup von Typoscript-Template und Site-Config
  • Extension-Programmierung im Ordner /packages, Verwaltung der Extensions mit Composer

Enthaltene Extensions (aka: creationell TYPO3 Vorlage)

creationell Theme

  • crea_theme
  • crea_theme_child: wird individuell pro Website angepasst

Privacy/DSGVO

Bildoptimierung

TYPO3 Form Framework (EXT:form)

SEO

Performance

Backend Erweiterungen

Inhalte

CLI/Scheduler

Weitere enthaltene Pakete

Diese Composer packages sind keine regulären TYPO3-Extension, beeinflussen aber den Umgang mit der TYPO3 Instanz:

Suggested extensions

In der composer.json werden weitere Extensions gelistet, die für im Falle einer entsprechenden Anforderung genutzt werden könnten:

{
  "t3g/blog":  "Flexible blog system for TYPO3",
  "extcode/cart": "Simple (yet extendable) shopping cart extension",
  "ichhabrecht/content-defender":  "Disallow certain content elements in columns of your BE layouts.",
  "in2code/fetchurl": "Fetch an url and show its content in the frontend.",
  "fixpunkt/fp-masterquiz":  "Quiz, polls and tests.",
  "clickstorm/go-maps-ext": "Google maps integration.",
  "derhansen/plain-faq":  "FAQ with list and detail view",
  "in2code/powermail": "Advanced forms.",
  "evoweb/recaptcha":  "Google Recaptcha integration for EXT:form",
  "derhansen/sf_event_mgt": "Event management & booking",
  "derhansen/sf_event_mgt_indexer":  "ke_search indexer for sf_event_mgt",
  "friendsoftypo3/tt-address": "Address & contacts management.",
  "apache-solr-for-typo3/solr":  "SOLR search integration.",
  "cobweb/flush_language_cache": "Adds a button to flush the l10n cache.",
  "apen/recordsmanager":  "Export any database record.",
  "wazum/sluggi": "Improved slug management.",
  "in2code/typoscript2ce": "Render typoscript as content element.",
  "ichhabrecht/mask-export":  "Export mask elements as extension.",
  "brotkrueml/typo3-matomo-widgets": "Show statistics from Matomo on the dashboard.",
  "kitzberger/form-mailtext":  "Customize email texts sent by EXT:form",
  "zotornit/webfonts": "Easy way to use selfhosted Google webfonts",
  "t3g/querybuilder": "Filter records in the list module."
}

Bitte beachte, dass einzelne dieser Extensions noch nicht in einer (stabilen) Version für TYPO3 11 bereitstehen könnten.

Frontend-Boilerplate mit Laravel Mix / Webpack

Mit diesem Paket können ebenfalls Frontend-Assets wie CSS, JS und Fonts kompiliert werden.

Grundlage dessen ist die Bibliothek Laravel Mix (https://laravel-mix.com/docs/):

##What is Mix? Webpack is an incredibly powerful module bundler that prepares your JavaScript and assets for the browser. The only understandable downside is that it requires a bit of a learning curve.

In an effort to flatten that curve, Mix is a thin layer on top of webpack for the rest of us. It exposes a simple, fluent API for dynamically constructing your webpack configuration.

Mix targets the 80% usecase. If, for example, you only care about compiling modern JavaScript and triggering a CSS preprocessor, Mix should be right up your alley. Don't worry about researching the necessary webpack loaders and plugins. Instead, install Mix...

Arbeiten mit SCSS und JS

Im Ordner '/frontend' befinden sich bereits vorbereitete SCSS und JS-Dateien, die nach Belieben erweitert werden können. Standardmäßig sind Bootstrap 4, FontAwesome 5 Pro, jQuery und Popper.js im Paket enthalten. Diese können entrsprechend erweitert werden.

Weitere Assets (Fonts/Icons/Images) können im entsprechenden Ordner in public/assets abgelegt werden.

Kompilieren

  1. Mit npm run dev bzw. yarn run dev wird Webpack im Development-Modus gestartet. Das Programm kompiliert die SCSS- und JS-Dateien in den in der .env festgelegten Ordner (i.d.R. 'web/assets').
  2. Mit npm run watch bzw. yarn run watch wird Webpack im Development-Modus mit Filewatcher gestartet. Das Programm erkennt dann Änderungen im Ordner '/src' und kompiliert die SCSS- und JS-Dateien in den in der .env festgelegten Ordner (i.d.R. 'web/assets').
  3. Mit npm run prod bzw. yarn run prod wird wird Webpack im Production-Modus gestartet.

Die kompilierten Dateien werden in public/assets abgelegt.

Kompilierte JS-Dateien

Standardmäßig erzeugt unsere Konfiguration folgende Dateien im Ordner web/assets/:

  • js/manifest.js: Webpack-Runtime, muss vor den anderen JS-Dateien eingebunden werden
  • js/vendor.js: Bibliotheken wie jQuery, FontAwesome etc.
  • js/vendor.js.LICENSE.txt: Übersicht und Lizenzinformationen der eingesetzten Bibliotheken
  • js/index.js: Custom JavaScript

Die drei JS-Dateien müssen in der Reihenfloge wie oben gezeigt in den HTMl-Code eingebunden werden.

Die Quelle dieser drei Dateien ist webpack/src/scripts/index.js, d.h. alles was hier importiert oder geschrieben wird, ist im kompilierten JS-Code enthalten.

Weitere JS-Dateien kompilieren

Manchmal möchte man einzelne Funktionsbestandteile ausgliedern, dann kann in der Datei webpack.mix.js der entsprechende Befehl ergänzt werden, z.B.:

mix.js('frontend/scripts/custom.js', 'js');

Für die JS-Kompilierung stehen noch zahlreiche weitere Befehle zur Verfügung, z.B. zur Kompilierung von Vue (mix.vue(...)), TypeScript (mix.ts(...))

Doku: https://laravel-mix.com/docs/6.0/mixjs

Kompiliertes CSS

Im Standard wird die Datei webpack/src/styles/index.scss zur Datei web/assets/css/index.css kompiliert. Um weitere CSS-Dateien zu erzeugen, kann der folgende Befehl genutzt werden (in webpack.mix.js):

mix.sass('frontend/styles/other.scss', 'css');

Auch hier werden andere Präprozessoren wie Less oder PostCSS unterstützt.

Doku: https://laravel-mix.com/docs/6.0/css

Weitere Tasks

Laravel Mix kann vor, nach oder im Kompilierungsprozess weitere Tasks durchführen.

Im Standard wird der Inhalt des Verzeichnisses webpack/public in den Ordner web/assets kopiert.

Vorteile

  • JavaScript kann mit ES6 geschrieben werden, beim Kompilieren wird die in der Datei .browserslistrc festgelegte Browserkompatibilität automatisch berücksichtigt
  • Das lokale Kompilieren des SCSS Codes bietet verschiedene Vorteile ggü. der Kompilierung mit PHP: es wird Autoprefixer für eine bessere Browserkompatibilität genutzt, Bootstrap kann in der neuesten Version verwendet werden, ...
  • Webpack bietet ein enormes Potenzial zur Code-Optimierung
  • durch Laravel Mix wird die Komplexität der Webpack_konfiguration stark vermindert

Bitte beachten:

  • .env bzw. .env.* Dateien sowie die Datei .npmrc sollen niemals ins GIT committed werden!
  • es steht ein leerer Ordner '/web' zur Verfügung, der als Mapping-Pfad zum Web-Root auf dem Server genutzt werden kann. Alle Theme und Extension Dateien sollten also hier landen.

FontAwesome 5 (Pro)

FontAwesome 5 wird standardmäßig in der Pro Version via npm install installiert.

Voraussetzung dafür ist ein gültiger FontAwesome Auth-Token in der Datei .npmrc. Über Environment Variablen (Einträge in der Datei .env) kann zudem gesteuert werden, ob FontAwesome genutzt werden soll (Stanbdard: ja) und ob statt der Pro-Version FA free verwendet werden soll (Standard: nein).

ENABLE_FONTAWESOME=1
ENABLE_FONTAWESOME_FREE=0

Sofern aktiviert werden im Rahmen des mitgelieferten Build Prozesses mit Laravel Mix die SVG Dateien aus dem FontAwesome Paket in den Ordner public/icons kopiert, sodass diese zur weiteren Verwendung/Einbindung (z.B. mit dem IconViewHelper des https://gitlab.com/creationell_t3extensions/crea_theme_bs4) zur Verfügung stehen. Dieses Verhalten kann in der Datei webpack.mix.js natürlich angepasst werden (z.B. könnten stattdessen die Font Dateien kopiert werden, um FA als Font zu verwenden).