Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Updates directory structure/templates pages to Mapbender 4 #505

Merged
merged 7 commits into from
Oct 15, 2024
Merged

Updates directory structure/templates pages to Mapbender 4 #505

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
4c0f257
Update directory structure
rschwammborn Aug 26, 2024
b8a09c3
1-word-update
rschwammborn Aug 26, 2024
773a6f9
Update path
rschwammborn Aug 26, 2024
53ecf18
Update from devdocs
rschwammborn Aug 26, 2024
c72030c
Update templates.rst pages
rschwammborn Aug 26, 2024
7fb1656
Add improvements from review comments
rschwammborn Sep 30, 2024
190a769
Minor text improvements
rschwammborn Sep 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 43 additions & 40 deletions de/architecture/directory_structure.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,29 +3,30 @@
Verzeichnisstruktur in Mapbender
################################

app
***
Dieses Verzeichnis beinhaltet:
application
***********
rschwammborn marked this conversation as resolved.
Show resolved Hide resolved

* den php-Cache (`var/cache`)
* das log-Verzeichnis (`var/log`)
* das Konfigurationsverzeichnis (`config/`)
* Der Anwendungs-Kernel (`src/Kernel.php`) (wird über die FrontendController aufgerufen; darüber wird die gesamte Anwendung kontrolliert)
* das Autoladen (*autoload.php*)
* Verzeichnis für spezielle Anwendungsressourcen (`Resources/`)
* die Kommandozeilen-Anwendungen für Pflege und Management (`bin/console`)
Dieses Verzeichnis enthält beinahe sämtliche Mapbender-Komponenten. Wichtige Unterverzeichnisse und Dateien sind:

* Das :ref:`config<de/architecture/directory_structure:config>`-Verzeichnis,
* Der Anwendungskernel (`src/Kernel.php`) als Zugangspunkt zu Symfony,
* Autoloading (`vendor/autoload.php`) generiert von Composer,
* Kommandozeilen-Anwendungen für Pflege und Management (``bin/console``, ``bin/phpunit``) und
* *.env* und *.env.local*: Globale Konfigurationsdateien, z.B. für Datenbank-URLs und SMTP-Server-Verbindungen.

config/
-------
bin
===

Grundlegende Konfigurationsdateien von Mapbender liegen im Verzeichnis `config/` sowie im Verzeichnis `config/packages`. Zwei Dateien sind dabei von besonderer Bedeutung:
Hier liegen diverse Bibliotheken.

* *parameters.yaml*
* `packages/doctrine.yaml`
config
======

Weitere Informationen im Kapitel :ref:`yaml_de`.
Grundlegende Konfigurationsdateien von Mapbender liegen im Verzeichnis `config/` sowie im Verzeichnis `config/packages`. Diese Dateien sind dabei von besonderer Bedeutung:

* :ref:`doctrine.yaml<de/customization/yaml:doctrine.yaml>`
* :ref:`parameters.yaml<de/customization/yaml:parameters.yaml>`
* *services.yaml*: Dient als Einstiegspunkt zur Konfiguration von Diensten.
rschwammborn marked this conversation as resolved.
Show resolved Hide resolved

config/applications
-------------------
Expand All @@ -34,40 +35,31 @@ Als YAML definierte Anwendungen können in dem Verzeichnis `config/applications`

Weitere Informationen im Kapitel :ref:`yaml_de`.


bin
***

Hier liegen diverse Bibliotheken.


mapbender
*********

Verzeichnis des `Mapbender Submoduls <https://github.com/mapbender/mapbender>`_. Liefert die Mapbender-spezifischen Bundles und den Mapbender-Code.
=========

* Verzeichnis des `Mapbender Submoduls <https://github.com/mapbender/mapbender>`_. Liefert die Mapbender-spezifischen Bundles und den Mapbender-Code.
* Verzeichnis für spezielle Anwendungsressourcen (`Resources/`)

mapbender/...../translations
----------------------------

Verzeichnis: `mapbender/src/Mapbender/CoreBundle/Resources/translations/`
Die Übersetzungen werden in `YAML-Dateien <https://en.wikipedia.org/wiki/YAML>`_ gespeichert. Jede Sprache benötigt eine YAML-Datei, wie z.B. *messages.fr.yaml* für die französische Übersetzung.


Die Übersetzungen werden in `YAML-Dateien <https://en.wikipedia.org/wiki/YAML>`_ gespeichert. Jede Sprache benötigt eine YAML-Datei, wie z.B. *messages.de.yaml* für die deutsche Übersetzung.
* Verzeichnis: `mapbender/src/Mapbender/CoreBundle/Resources/translations/`


public
******
======

Dieses Verzeichnis muss vom Webserver veröffentlicht werden. Der Alias muss auf dieses Verzeichnis verweisen.
Dieses Verzeichnis beinhaltet die statischen Ressourcen wie css, js, favicon etc.
Dieses Verzeichnis muss vom Webserver veröffentlicht werden. DocumentRoot muss auf dieses Verzeichnis verweisen.
rschwammborn marked this conversation as resolved.
Show resolved Hide resolved


Es kontrolliert:

* *index.php*: FrontendController (PHP-Script, welches aufgerufen werden kann).
* *index_dev.php*: FrontendController als Zugangspunkt in die Entwicklungsumgebung. Kann standardmäßig nur von lokalen IP-Adressen aufgerufen werden.

* *index.php*: FrontendController (PHP-Script, welches aufgerufen werden kann). Benutzt die Umgebung, die in *.env* oder *.env.local* definiert wird.
rschwammborn marked this conversation as resolved.
Show resolved Hide resolved
* *index_dev.php*: Benutzt immer die Entwicklungsumgebung. Kann standardmäßig nur von lokalen Host-Umgebungen aufgerufen werden.
rschwammborn marked this conversation as resolved.
Show resolved Hide resolved
* `public/` beinhaltet außerdem die statischen Ressourcen wie css, js, favicon etc.
rschwammborn marked this conversation as resolved.
Show resolved Hide resolved

public/bundles
--------------
Expand All @@ -79,17 +71,28 @@ public/bundles

bin/console assets:install --symlink --relative public

.. note:: **Hinweis**: Wenn Sie Windows benutzen, können Sie keine symbolischen Links verwenden. Daher müssen Sie das Kommando ``bin/console assets:install public`` nach jeder Änderung im Code aufrufen, um die Dateien in das Verzeichnis zu kopieren.
.. note:: **Hinweis**: Wenn Sie Windows benutzen, können Sie keine symbolischen Links verwenden. Daher müssen Sie das Kommando ``php.exe bin/console assets:install public`` nach jeder Änderung im Code aufrufen, um die Dateien in das Verzeichnis zu kopieren.
rschwammborn marked this conversation as resolved.
Show resolved Hide resolved


src
***
===

* Verzeichnis für anwendungsspezifische Bundles (Kunden-Bundle)
Verzeichnis für anwendungsspezifische Bundles (Kunden-Bundle).

* Der Anwendungs-Kernel (`src/Kernel.php`) wird über die FrontendController aufgerufen; darüber wird die gesamte Anwendung kontrolliert.

var
===

Dieses Verzeichnis beinhaltet:

* die php-Caches (`var/cache/dev` and `var/cache/prod`),
* das log-Verzeichnis (`var/log`),
* das SQLite-Datenbank-Verzeichnis (`var/db/`).

vendor
******
======

* Verzeichnis mit externen Bibliotheken, die via composer geladen wurden. Ressourcen werden von Symfony durch das Autoladen verwendet.
Verzeichnis mit externen Bibliotheken, die via Composer geladen wurden. Ressourcen werden von Symfony durch das Autoladen verwendet:

* Autoladen-Datei (*autoload.php*)
100 changes: 45 additions & 55 deletions de/customization/templates.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,38 +3,33 @@
Wie werden eigene Style-Vorlagen (templates) erzeugt?
#####################################################

Mapbender beinhaltet bereits Anwendungs-Vorlagen, sie befinden sich im Mapbender CoreBundle `Template`-Verzeichnis ``/application/mapbender/src/Mapbender/CoreBundle/Template``.
Mapbender beinhaltet bereits Anwendungs-Vorlagen, sie befinden sich im Mapbender CoreBundle Template-Verzeichnis `/application/mapbender/src/Mapbender/CoreBundle/Template`.
rschwammborn marked this conversation as resolved.
Show resolved Hide resolved
Häufig sollen jedoch eigene Anwendungs-Vorlagen und Administrationsoberflächen mit eigenem Corporate Design verwendet werden.
Um Probleme bei einem Upgrade zu vermeiden, sollte für personalisierte Oberflächen ein eigenes Bundle verwendet werden.

Der Stil einer einzelnen Anwendung kann ebenfalls über den :ref:`css_de` angepasst werden.


Wie werden eigene Vorlagen erzeugt?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
***********************************

**Schritte für die Einbindung:**

* Erzeugen eines eigenen Bundles
* Erzeugen eines neuen Namespaces
* Template PHP-Datei zur Registrierung der eigenen Vorlage erzeugen
* Erzeugen einer eigenen Twig-Datei
* Erzeugen eigener CSS-Datei(en)
* Registrierung des Bundles in src/Kernel.php
* Verwenden der neuen Vorlage
* Erzeugen eines eigenen Bundles,
* Erzeugen eines neuen Namespaces,
* Template PHP-Datei zur Registrierung der eigenen Vorlage erzeugen,
* Erzeugen einer eigenen Twig-Datei,
* Erzeugen eigener CSS-Datei(en),
* Registrierung des Bundles in `src/Kernel.php`,
rschwammborn marked this conversation as resolved.
Show resolved Hide resolved
* Verwenden der neuen Vorlage.


Als Beispiel für die Einbindung einer eigenen Vorlage wurde ein Workshop/DemoBundle vorbereitet. Dieses kann verwendet und individuell verändert werden.
Sie können sich die Dateien unter folgendem Link herunterladen:

* https://github.com/mapbender/mapbender-workshop/tree/master
Sie können sich die Dateien `hier <https://github.com/mapbender/mapbender-workshop/tree/master>`_ herunterladen.
rschwammborn marked this conversation as resolved.
Show resolved Hide resolved


Erzeugen eines eigenen Bundles
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Anwender-Bundles werden im src-Verzeichnis ``/application/src`` abgelegt.
******************************

Anwender-Bundles werden im src-Verzeichnis `/application/src` abgelegt.
rschwammborn marked this conversation as resolved.
Show resolved Hide resolved
Die Struktur eines Bundles kann wie folgt aussehen:

.. code-block:: bash
Expand All @@ -61,12 +56,12 @@ Die Struktur eines Bundles kann wie folgt aussehen:

Die folgenden Dateien können bearbeitet werden:

* twig-Datei: verändert die Struktur (z.B. - Löschen einer Komponente wie die Sidebar)
* css-Datei: verändert die Farben, Icons, Schriften
* twig-Datei: verändert die Struktur (z.B. - Löschen einer Komponente wie die Sidepane),
* css-Datei: verändert die Farben, Icons, Schriften.


Erzeugen eines neuen Namespaces
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*******************************

In unserem Beispiel erzeugt die Datei *WorkshopDemoBundle.php* einen Namespace für das Bundle und referenziert auf das Template.

Expand Down Expand Up @@ -94,15 +89,12 @@ In unserem Beispiel erzeugt die Datei *WorkshopDemoBundle.php* einen Namespace f
}



Anlegen der eigenen Template-Datei
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In unserem Beispiel heißt die Template-Datei *FullscreenDemo.php*. Sie befindet sich unter ``src/Workshop/DemoBundle/Template/DemoFullscreen.php``.
**********************************

rschwammborn marked this conversation as resolved.
Show resolved Hide resolved
In unserem Beispiel heißt die Template-Datei *FullscreenDemo.php*. Sie befindet sich unter `src/Workshop/DemoBundle/Template/DemoFullscreen.php`.
rschwammborn marked this conversation as resolved.
Show resolved Hide resolved
In der Template-Datei wird der Name des Templates, die Regionen die angelegt werden sollen sowie die verwendete Twig-Datei definiert.


.. code-block:: php

<?php
Expand Down Expand Up @@ -140,27 +132,26 @@ In der Template-Datei wird der Name des Templates, die Regionen die angelegt wer
public $twigTemplate = 'WorkshopDemoBundle:Template:demo_fullscreen.html.twig';
rschwammborn marked this conversation as resolved.
Show resolved Hide resolved
}


Eigene Twig-Datei erzeugen
~~~~~~~~~~~~~~~~~~~~~~~~~~
**************************

Die Twig-Dateien sind im folgenden Verzeichnis gespeichert:

``application/mapbender/src/Mapbender/CoreBundle/Resources/views/Template``
* `application/mapbender/src/Mapbender/CoreBundle/Resources/views/Template`

Kopieren Sie eine existierende Twig-Datei, speichern Sie diese unter einem neuen Namen und verändern Sie den Inhalt, z.B. die Farbe.

Verwenden Sie z.B. ``mapbender/src/Mapbender/CoreBundle/Resources/views/Template/fullscreen.html.twig`` und kopieren Sie diese nach ``/Workshop/DemoBundle/Resources/views/Template/fullscreen_demo.html.twig``
Verwenden Sie z.B. `mapbender/src/Mapbender/CoreBundle/Resources/views/Template/fullscreen.html.twig` und kopieren Sie diese nach `/Workshop/DemoBundle/Resources/views/Template/fullscreen_demo.html.twig`.


Eigene CSS-Datei erzeugen
~~~~~~~~~~~~~~~~~~~~~~~~~

Erzeugen Sie eine leere CSS-Datei und geben Sie in dieser nur die CSS-Definitionen für Ihre Anwendungs-Vorlage an.
Es muss lediglich das CSS definiert werden, das vom Standard der Elemente abweicht.
*************************

Erzeugen Sie eine leere CSS-Datei und geben Sie in dieser nur die CSS-Definitionen für Ihre Anwendungs-Vorlage an. Es muss lediglich das CSS definiert werden, das vom Standard der Elemente abweicht.
Mit Hilfe der Entwicklerwerkzeuge Ihres Browsers können Sie die bestehende Definition ermitteln, in Ihre CSS-Datei kopieren und hier anpassen.

Ihre CSS-Datei könnte wie folgt heißen: ``src/Workshop/DemoBundle/Resources/public/demo_fullscreen.css`` und die folgende Definition enthalten:
Ihre CSS-Datei könnte wie folgt heißen: `src/Workshop/DemoBundle/Resources/public/demo_fullscreen.css` und die folgende Definition enthalten:

.. code-block:: css

Expand Down Expand Up @@ -227,7 +218,7 @@ Das Ergebnis der wenigen Zeilen CSS sieht dann so aus:

Beim Laden der neuen Anwendung wird eine CSS-Datei im web/assets-Verzeichnis angelegt:

* ``web/assets/WorkshopDemoBundle__demo_fullscreen__css.css``
* `web/assets/WorkshopDemoBundle__demo_fullscreen__css.css`

Wenn Sie die CSS-Datei weiter bearbeiten, müssen Sie die unter ``web/assets`` generierte Datei löschen, damit diese neu geschrieben wird und die Änderungen wirksam werden. Der Browser-Cache sollte ebenfalls geleert werden.

Expand All @@ -242,13 +233,13 @@ Styling der Administrationsseiten

Passen Sie die vorhandenen CSS-Dateivorlagen für die unterschiedlichen Bereiche an:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

folgende Doku muss ich später nochmal prüfen. Erstmal so übernehmen


* login.css : Anpassung des Designs der Login-Oberfläche (Anmelde-Seite)
* manager.css : Anpassung des Designs der Verwaltungs/Administrations-Oberfläche (Anwendungsübersicht u.ä.)
* password.css : Anpassung des Designs der Passwort-Oberfläche (Passwort vergessen u.ä.)
* *login.css*: Anpassung des Designs der Login-Oberfläche (**Anmelden**-Seite),
* *manager.css*: Anpassung des Designs der Verwaltungs/Administrations-Oberfläche (**Anwendungsübersicht** etc.),
* *password.css*: Anpassung des Designs der Passwort-Oberfläche (**Passwort vergessen**).

Es muss lediglich das CSS definiert werden, das vom Standard der Administrationsoberfläche abweicht.

Auf die CSS-Dateien wird über das FOMManagerBundle und FOMUserBundle referenziert. Diese müssen unter ``app/Resources/`` abgelegt werden. Die bereits enthaltenen Twig-Dateien überschreiben nach der erfolgreichen Einrichtung die Standard-Einstellungen (Vorgaben aus der manager.html.twig Datei).
Auf die CSS-Dateien wird über das FOMManagerBundle und FOMUserBundle referenziert. Diese müssen unter `app/Resources/` abgelegt werden. Die bereits enthaltenen Twig-Dateien überschreiben nach der erfolgreichen Einrichtung die Standard-Einstellungen (Vorgaben aus der *manager.html.twig* Datei).
Alternativ kann auch die bisherige Twig-Datei kopiert und angepasst werden.

.. code-block:: bash
Expand All @@ -264,16 +255,16 @@ Bei unveränderter Übernahme der Stylevorgaben sieht die Administration dann so


Registrieren des Bundles in config/bundles.php
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
**********************************************

Falls noch nicht geschehen, setzen Sie Schreibrechte für das public-Verzeichnis für Ihren Webserver-Benutzer:
Falls noch nicht geschehen, setzen Sie Schreibrechte für das `public`-Verzeichnis für Ihren Webserver-Benutzer:

.. code-block:: bash

chmod ug+w public


Aktualisieren Sie das public-Verzeichnis. Jedes Bundle hat seine eigenen Assets - CSS Dateien, JavaScript-Dateien, Bilder und mehr - diese müssen in das public-Verzeichnis kopiert werden.
Aktualisieren Sie das `public`-Verzeichnis. Jedes Bundle hat seine eigenen Assets - CSS Dateien, JavaScript-Dateien, Bilder und mehr - diese müssen in das `public`-Verzeichnis kopiert werden.

.. code-block:: bash

Expand All @@ -291,43 +282,42 @@ Jetzt sollte beim Anlegen einer neuen Anwendung die neue Vorlage in der Liste er


Verwendung der eigenen Vorlage
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
******************************

Die neue Anwendungs-Vorlage kann über verschiedene Wege verwendet werden:


Einbindung in YAML-Anwendungen
******************************
==============================

Sie können nun die YAML-Anwendungen unter ``config/applications`` anpassen und auf das neue Template verweisen.
Sie können nun die YAML-Anwendungen unter `config/applications` anpassen und auf das neue Template verweisen.

.. code-block:: yaml

template: Workshop\DemoBundle\Template\DemoFullscreen


Einbindung in eine neue Anwendungen über das Backend
****************************************************
====================================================


Wenn Sie eine neue Anwendung mit der Mapbender-Administration erzeugen, können Sie eine Vorlage (Template) auswählen.


Einbindung in eine bestehende Anwendung
***************************************
=======================================

Für bereits existierende Anwendungen kann das Template über die Mapbender Datenbank in der Tabelle ``mb_core_application`` in der Spalte *template* angepasst werden.
Für bereits existierende Anwendungen kann das Template über die Mapbender Datenbank in der Tabelle **mb_core_application** in der Spalte **template** angepasst werden.

Für das *WorkshopDemoBundle* wird hier statt des Eintrags ``Mapbender\CoreBundle\Template\Fullscreen`` der Eintrag ``Workshop\DemoBundle\WorkshopDemoBundle`` angegeben.
Für das **WorkshopDemoBundle** wird hier statt des Eintrags ``Mapbender\CoreBundle\Template\Fullscreen`` der Eintrag ``Workshop\DemoBundle\WorkshopDemoBundle`` angegeben.


Anwendungsfälle
~~~~~~~~~~~~~~~
***************

Wie kann das Logo verändert werden?
Wie kann der Anwendungstitel angepasst werden?
Wie stelle ich die Sprache ein?
F: Wie kann das Logo verändert werden? Wie kann der Anwendungstitel angepasst werden? Wie stelle ich die Sprache ein?

Auf diese und weitere Fragen finden Sie Antworten im Kapitel :ref:`yaml_de`.
A: Auf diese und weitere Fragen finden Sie Antworten im Kapitel :ref:`yaml_de`.


Wie können eigene Buttons eingebunden werden?
Expand Down Expand Up @@ -364,9 +354,9 @@ Wenn Sie ein Bild nutzen möchten, legen Sie dieses am besten in Ihrem Bundle ab


Probieren Sie es aus
~~~~~~~~~~~~~~~~~~~~
********************

* Laden Sie das Workshop/DemoBundle herunter: https://github.com/mapbender/mapbender-workshop
* Laden Sie das Workshop/DemoBundle `hier <https://github.com/mapbender/mapbender-workshop>`_ herunter.
* Ändern Sie die Farbe Ihrer Icons.
* Ändern Sie die Größe Ihrer Icons.
* Ändern Sie die Farbe der Oberen Werkzeugleiste.
Expand Down
2 changes: 1 addition & 1 deletion en/architecture.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Architecture
============

.. toctree::
:maxdepth: 1
:maxdepth: 2

architecture/components
architecture/directory_structure
Expand Down
Loading