From 4c0f25799f01f8756704cac680ca49f506160e80 Mon Sep 17 00:00:00 2001 From: Robin Schwammborn Date: Mon, 26 Aug 2024 12:19:17 +0200 Subject: [PATCH 1/5] Update directory structure --- de/architecture/directory_structure.rst | 53 +++++++++------------ en/architecture.rst | 2 +- en/architecture/directory_structure.rst | 61 +++++++++++-------------- 3 files changed, 50 insertions(+), 66 deletions(-) diff --git a/de/architecture/directory_structure.rst b/de/architecture/directory_structure.rst index 800fc868d..cfc41c601 100644 --- a/de/architecture/directory_structure.rst +++ b/de/architecture/directory_structure.rst @@ -3,29 +3,21 @@ Verzeichnisstruktur in Mapbender ################################ -app +bin *** -Dieses Verzeichnis beinhaltet: -* 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`) +Hier liegen diverse Bibliotheken, z.B. +* Die Kommandozeilen-Anwendungen für Pflege und Management (`bin/console`) -config/ -------- +config +****** Grundlegende Konfigurationsdateien von Mapbender liegen im Verzeichnis `config/` sowie im Verzeichnis `config/packages`. Zwei Dateien sind dabei von besonderer Bedeutung: -* *parameters.yaml* -* `packages/doctrine.yaml` - -Weitere Informationen im Kapitel :ref:`yaml_de`. - +* :ref:`doctrine.yaml` +* :ref:`parameters.yaml` +* *services.yaml*: Dient als Einstiegspunkt zur Konfiguration von Diensten. config/applications ------------------- @@ -34,27 +26,18 @@ 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 `_. Liefert die Mapbender-spezifischen Bundles und den Mapbender-Code. - +* Verzeichnis des `Mapbender Submoduls `_. 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 `_ gespeichert. Jede Sprache benötigt eine YAML-Datei, wie z.B. *messages.de.yaml* für die deutsche Übersetzung. - +Die Übersetzungen werden in `YAML-Dateien `_ gespeichert. Jede Sprache benötigt eine YAML-Datei, wie z.B. *messages.fr.yaml* für die französische Übersetzung. public ****** @@ -62,13 +45,11 @@ 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. - 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. - public/bundles -------------- @@ -86,10 +67,20 @@ src *** * 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`) +* 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*) diff --git a/en/architecture.rst b/en/architecture.rst index 8ee7a8f5b..3db480678 100644 --- a/en/architecture.rst +++ b/en/architecture.rst @@ -4,7 +4,7 @@ Architecture ============ .. toctree:: - :maxdepth: 1 + :maxdepth: 2 architecture/components architecture/directory_structure diff --git a/en/architecture/directory_structure.rst b/en/architecture/directory_structure.rst index 18d4e4e82..63f3f9f7d 100644 --- a/en/architecture/directory_structure.rst +++ b/en/architecture/directory_structure.rst @@ -3,57 +3,41 @@ Directory structure in Mapbender ################################ -app +bin *** -This directory contains: -* the php-Cache (`var/cache`) -* the logs (`var/log`) -* the configuration directory (`config/`) -* the application kernel (`src/Kernel.php`) (is called by the FrontendControllers and controls the whole application) -* the Autoloading (*autoload.php*) -* the application specific resource directory (*Resources*) -* the command line application for maintaining and management tasks (`bin/console`) +Mapbender-related libraries are stored here, e.g.: +* The command line application for maintaining and managing tasks (`bin/console`) config ------- - -Basic configuration files of Mapbender are placed in the `config/` directory and the `config/packages` directory. Two files are of particular importance: +****** -* *parameters.yaml* -* `packages/doctrine.yaml` +Basic configuration files of Mapbender are placed in the `config/` directory and the `config/packages` directory. These files are of particular importance: -More Information: :ref:`yaml`. +* :ref:`doctrine.yaml` +* :ref:`parameters.yaml` +* *services.yaml*: Serves as entry point to configure services. - config/applications ------------------- The directory `config/applications` contains all applications that are defined in a YAML file. -More information in :ref:`yaml` . - - -bin -*** - -Here you find some libraries. - +Find more information in :ref:`yaml` . mapbender ********* -Directory of the `Mapbender submodule `_. Provides the Mapbender-specific bundles and the Mapbender code. - +* Directory of the `Mapbender submodule `_. Provides the Mapbender-specific bundles and the Mapbender code. +* Directory for application resources (`Resources/`) mapbender/...../translations ---------------------------- -Directory: `mapbender/src/Mapbender/CoreBundle/Resources/translations/` - -The translations are stored in `YAML files `_. Every language needs a YAML-file, like *messages.en.yaml* for the English translation. +Directory: `../mapbender/src/Mapbender/CoreBundle/Resources/translations/` +The translations are stored in `YAML files `_. Every language needs a YAML-file, like *messages.fr.yaml* for the French translation of Mapbender. public ****** @@ -66,12 +50,11 @@ It controls: * *index.php* - the FrontendController (PHP script which can be called). * *index_dev.php* - FrontendController for easy access to the development environment. By default, it can only be accessed from local IP addresses. - public/bundles -------------- -* storage for the static resources of the single bundles. -* the following command copies the resources from the bundles to the folder: +* Is the storage for the static resources of the single bundles. +* The following command copies the resources from the bundles to the folder: .. code-block:: yaml @@ -83,11 +66,21 @@ public/bundles src *** -* directory for applications specific bundles +* Directory for applications specific bundles +* The application kernel (`src/Kernel.php`) (is called by the FrontendControllers and controls the whole application) +var +*** + +This directory contains: + +* the caches (`var/cache/dev` and `var/cache/prod`) +* the logs (`var/log`) +* Sqlite-databases (`var/db`) vendor ****** -* Directory for external libraries (loaded by composer) are placed. Resources are used by Symfony using the Autoloading. +Directory for external libraries (loaded by composer) are placed here. Resources are used by Symfony using the Autoloading: +* Autoloading: *autoload.php* From b8a09c33c567e19eb8dd2b42dec99383c49bd719 Mon Sep 17 00:00:00 2001 From: Robin Schwammborn Date: Mon, 26 Aug 2024 12:20:17 +0200 Subject: [PATCH 2/5] 1-word-update --- de/architecture/directory_structure.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/de/architecture/directory_structure.rst b/de/architecture/directory_structure.rst index cfc41c601..222a77ebd 100644 --- a/de/architecture/directory_structure.rst +++ b/de/architecture/directory_structure.rst @@ -13,7 +13,7 @@ Hier liegen diverse Bibliotheken, z.B. config ****** -Grundlegende Konfigurationsdateien von Mapbender liegen im Verzeichnis `config/` sowie im Verzeichnis `config/packages`. Zwei Dateien sind dabei von besonderer Bedeutung: +Grundlegende Konfigurationsdateien von Mapbender liegen im Verzeichnis `config/` sowie im Verzeichnis `config/packages`. Diese Dateien sind dabei von besonderer Bedeutung: * :ref:`doctrine.yaml` * :ref:`parameters.yaml` From 773a6f9bbad2e2b09fe42d59104bde4cb5e8b6e0 Mon Sep 17 00:00:00 2001 From: Robin Schwammborn Date: Mon, 26 Aug 2024 12:23:12 +0200 Subject: [PATCH 3/5] Update path --- en/architecture/directory_structure.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/architecture/directory_structure.rst b/en/architecture/directory_structure.rst index 63f3f9f7d..1a9797f6d 100644 --- a/en/architecture/directory_structure.rst +++ b/en/architecture/directory_structure.rst @@ -76,7 +76,7 @@ This directory contains: * the caches (`var/cache/dev` and `var/cache/prod`) * the logs (`var/log`) -* Sqlite-databases (`var/db`) +* Sqlite-databases (`var/db/`) vendor ****** From 53ecf18b7fa0035e6cd50c5725c46bd2e9bddb30 Mon Sep 17 00:00:00 2001 From: Robin Schwammborn Date: Mon, 26 Aug 2024 13:51:15 +0200 Subject: [PATCH 4/5] Update from devdocs --- de/architecture/directory_structure.rst | 58 +++++++++++++++---------- en/architecture/directory_structure.rst | 57 ++++++++++++++---------- 2 files changed, 69 insertions(+), 46 deletions(-) diff --git a/de/architecture/directory_structure.rst b/de/architecture/directory_structure.rst index 222a77ebd..633223cc2 100644 --- a/de/architecture/directory_structure.rst +++ b/de/architecture/directory_structure.rst @@ -3,15 +3,24 @@ Verzeichnisstruktur in Mapbender ################################ -bin -*** +application +*********** + +Dieses Verzeichnis enthält beinahe sämtliche Mapbender-Komponenten. Wichtige Unterverzeichnisse und Dateien sind: -Hier liegen diverse Bibliotheken, z.B. +* Das :ref:`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. -* Die Kommandozeilen-Anwendungen für Pflege und Management (`bin/console`) +bin +=== + +Hier liegen diverse Bibliotheken. config -****** +====== Grundlegende Konfigurationsdateien von Mapbender liegen im Verzeichnis `config/` sowie im Verzeichnis `config/packages`. Diese Dateien sind dabei von besonderer Bedeutung: @@ -27,7 +36,7 @@ Als YAML definierte Anwendungen können in dem Verzeichnis `config/applications` Weitere Informationen im Kapitel :ref:`yaml_de`. mapbender -********* +========= * Verzeichnis des `Mapbender Submoduls `_. Liefert die Mapbender-spezifischen Bundles und den Mapbender-Code. * Verzeichnis für spezielle Anwendungsressourcen (`Resources/`) @@ -35,20 +44,22 @@ mapbender mapbender/...../translations ---------------------------- -Verzeichnis: `mapbender/src/Mapbender/CoreBundle/Resources/translations/` - Die Übersetzungen werden in `YAML-Dateien `_ gespeichert. Jede Sprache benötigt eine YAML-Datei, wie z.B. *messages.fr.yaml* für die französische Übersetzung. +* Verzeichnis: `mapbender/src/Mapbender/CoreBundle/Resources/translations/` + + public -****** +====== + +Dieses Verzeichnis muss vom Webserver veröffentlicht werden. DocumentRoot muss auf dieses Verzeichnis verweisen. -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. 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. +* *index_dev.php*: Benutzt immer die Entwicklungsumgebung. Kann standardmäßig nur von lokalen Host-Umgebungen aufgerufen werden. +* `public/` beinhaltet außerdem die statischen Ressourcen wie css, js, favicon etc. public/bundles -------------- @@ -60,27 +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. 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) +* 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`) -* SQLite-Datenbank-Verzeichnis (`var/db/`) +* 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*) diff --git a/en/architecture/directory_structure.rst b/en/architecture/directory_structure.rst index 1a9797f6d..a309ec72d 100644 --- a/en/architecture/directory_structure.rst +++ b/en/architecture/directory_structure.rst @@ -3,15 +3,24 @@ Directory structure in Mapbender ################################ -bin -*** +application +*********** + +This directory contains the default Mapbender application. Some important subdirectories and files are: -Mapbender-related libraries are stored here, e.g.: +* the :ref:`config` directory, +* the application kernel (`src/Kernel.php`) as entry point to the Symfony application, +* the Autoloading (`vendor/autoload.php`), auto-generated by Composer, +* the command line applications for maintaining and management tasks (``bin/console``, ``bin/phpunit``) and +* *.env* and *.env.local*: Global configuration files, e.g. for database urls and smtp server connection. + +bin +=== -* The command line application for maintaining and managing tasks (`bin/console`) +Here you find some libraries. config -****** +====== Basic configuration files of Mapbender are placed in the `config/` directory and the `config/packages` directory. These files are of particular importance: @@ -27,7 +36,7 @@ The directory `config/applications` contains all applications that are defined i Find more information in :ref:`yaml` . mapbender -********* +========= * Directory of the `Mapbender submodule `_. Provides the Mapbender-specific bundles and the Mapbender code. * Directory for application resources (`Resources/`) @@ -35,20 +44,21 @@ mapbender mapbender/...../translations ---------------------------- -Directory: `../mapbender/src/Mapbender/CoreBundle/Resources/translations/` - The translations are stored in `YAML files `_. Every language needs a YAML-file, like *messages.fr.yaml* for the French translation of Mapbender. +* Directory path: `../mapbender/src/Mapbender/CoreBundle/Resources/translations/` + public -****** +====== -This directory has to be published by the webserver. The ALIAS has to refer to this directory. -It contains the static resoures like css, js, favicon etc. +This directory has to be published by the webserver. The DocumentRoot directive has to refer to this directory. It controls: -* *index.php* - the FrontendController (PHP script which can be called). -* *index_dev.php* - FrontendController for easy access to the development environment. By default, it can only be accessed from local IP addresses. +* *index.php*: The FrontendController (PHP script which can be called). Uses the environment defined in *.env* or *.env.local*. +* *index_dev.php*: Always uses the dev environment. Per default, access is only allowed from local hosts. +* `public/` also contains the static resoures like css, js, favicon etc. + public/bundles -------------- @@ -60,27 +70,28 @@ public/bundles bin/console assets:install --symlink --relative public -.. note:: If you use Windows, you cannot create symbolic links and therefore have to run the command ``bin/console assets:install public`` to copy the files to the directory after every change in the code. +.. note:: If you use Windows, you cannot create symbolic links and therefore have to run the command ``php.exe bin/console assets:install public`` to copy the files to the directory after every change in the code. src -*** +=== + +Directory for application specific code and resources. -* Directory for applications specific bundles -* The application kernel (`src/Kernel.php`) (is called by the FrontendControllers and controls the whole application) +* The application kernel (`src/Kernel.php`) is called by the FrontendControllers and controls the whole application. var -*** +=== This directory contains: -* the caches (`var/cache/dev` and `var/cache/prod`) -* the logs (`var/log`) -* Sqlite-databases (`var/db/`) +* the caches (`var/cache/dev` and `var/cache/prod`), +* the logs (`var/log`), +* Sqlite-databases (`var/db/`). vendor -****** +====== -Directory for external libraries (loaded by composer) are placed here. Resources are used by Symfony using the Autoloading: +Directory for external libraries (loaded by Composer) are placed here. Resources are used by Symfony using Autoloading: * Autoloading: *autoload.php* From c72030c48bf0e9580a998321433a846ae6ce15c9 Mon Sep 17 00:00:00 2001 From: Robin Schwammborn Date: Mon, 26 Aug 2024 14:48:30 +0200 Subject: [PATCH 5/5] Update templates.rst pages --- de/customization/templates.rst | 100 +++++++++++-------------- en/customization/templates.rst | 132 ++++++++++++++++----------------- 2 files changed, 108 insertions(+), 124 deletions(-) diff --git a/de/customization/templates.rst b/de/customization/templates.rst index ca4fd08da..37f7eb9d6 100644 --- a/de/customization/templates.rst +++ b/de/customization/templates.rst @@ -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`. 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`, +* 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 `_ herunterladen. Erzeugen eines eigenen Bundles -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Anwender-Bundles werden im src-Verzeichnis ``/application/src`` abgelegt. +****************************** +Anwender-Bundles werden im src-Verzeichnis `/application/src` abgelegt. Die Struktur eines Bundles kann wie folgt aussehen: .. code-block:: bash @@ -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. @@ -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``. +********************************** +In unserem Beispiel heißt die Template-Datei *FullscreenDemo.php*. Sie befindet sich unter `src/Workshop/DemoBundle/Template/DemoFullscreen.php`. In der Template-Datei wird der Name des Templates, die Regionen die angelegt werden sollen sowie die verwendete Twig-Datei definiert. - .. code-block:: php `_ herunter. * Ändern Sie die Farbe Ihrer Icons. * Ändern Sie die Größe Ihrer Icons. * Ändern Sie die Farbe der Oberen Werkzeugleiste. diff --git a/en/customization/templates.rst b/en/customization/templates.rst index c1c3d8b7c..c417ae12d 100644 --- a/en/customization/templates.rst +++ b/en/customization/templates.rst @@ -3,33 +3,28 @@ How to create your own Template? ################################ -Mapbender comes with application templates out of the box, you can find them in the Mapbender CoreBundle ``/application/mapbender/src/Mapbender/CoreBundle/Template``. But usually you want to use your own templates with your own corporate design. - +Mapbender comes with application templates out of the box, you can find them in the Mapbender CoreBundle: `/application/mapbender/src/Mapbender/CoreBundle/Template`. +But usually you want to use your own templates with your own corporate design. To prevent overwriting your custom templates after an Mapbender upgrade you should create an extra bundle to safely store your custom files. - You can also change the style of your application with the built-in :ref:`CSS-Editor `. - **Steps for including your templates:** -* Create your own bundle -* Create a new namespace -* Create a template PHP-file to register your template -* Create your own Twig-file -* Create your own CSS-file(s) -* Register your bundle in src/Kernel.php -* Use your template +* Create your own bundle, +* Create a new namespace, +* Create a template PHP-file to register your template, +* Create your own Twig-file, +* Create your own CSS-file(s), +* Register your bundle in `src/Kernel.php`, +* Use your template. -To help you we prepared a Workshop/DemoBundle, which can be used not only for application templates, but also for customizing the administration interface. For the following steps, you can download the files with the following links: - -* https://github.com/mapbender/mapbender-workshop/tree/master +To help you, we prepared a Workshop/DemoBundle, which can be used not only for application templates, but also for customizing the administration interface. For the following steps, you can download the files from the `Workshop bundle `_. Create your own bundle -~~~~~~~~~~~~~~~~~~~~~~ - -User bundles are stored in the src-directory ``/application/src``. +********************** +User bundles are stored in the src-directory `/application/src`. This is how the structure can look like: @@ -57,14 +52,14 @@ This is how the structure can look like: The following files have to be altered for design changes: -* twig-file: to change the structure (e.g. - delete a component like the sidebar) -* css-file: to change colors, icons, fonts +* twig-file: to change the structure (e.g. - delete a component like the sidebar), +* css-file: to change colors, icons, fonts. Create a new namespace -~~~~~~~~~~~~~~~~~~~~~~ +********************** -The file WorkshopDemoBundle.php creates the namespace for the bundle and refers to the template and to your css-files. +The *WorkshopDemoBundle.php* file creates the namespace for the bundle and refers to the template and to your css files. .. code-block:: php @@ -90,15 +85,12 @@ The file WorkshopDemoBundle.php creates the namespace for the bundle and refers } - Create your own template file -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In our example the template file is called FullscreenDemo.php. You find it at ``src/Workshop/DemoBundle/Template/FullscreenDemo.php``. +***************************** +In our example, the template file is called *FullscreenDemo.php*. You can find it at `src/Workshop/DemoBundle/Template/FullscreenDemo.php`. In the template file you define the name of your template, the regions that you want to provide and refer to a twig file. - .. code-block:: php @@ -136,26 +128,25 @@ In the template file you define the name of your template, the regions that you public $twigTemplate = 'WorkshopDemoBundle:Template:demo_fullscreen.html.twig'; } + Create your own twig-file -~~~~~~~~~~~~~~~~~~~~~~~~~ +************************* You find the twig-files at the following path: -* ``application/mapbender/src/Mapbender/CoreBundle/Resources/views/Template`` +* `application/mapbender/src/Mapbender/CoreBundle/Resources/views/Template` The easiest way to create your own twig file is to copy an existing twig, save it under a new name and change the content like colors. - -Use the existing template from ``mapbender/src/Mapbender/CoreBundle/Resources/views/Template/fullscreen.html.twig`` and copy it to ``fullscreen_demo.html.twig``. +Use the existing template from `mapbender/src/Mapbender/CoreBundle/Resources/views/Template/fullscreen.html.twig` and copy it to *fullscreen_demo.html.twig*. -Create your own css-file -~~~~~~~~~~~~~~~~~~~~~~~~ +Create your own CSS file +************************ Create an empty css-file and fill it with content. You only have to define the parts that have to look different from the default style of the element. +Developer tools can help you to find out the styles you want to change. -Firebug can help you to find out the styles you want to change. - -Your file could be named like this: ``src/Workshop/DemoBundle/public/demo_fullscreen.css`` and have the following definition: +Your file could be named `src/Workshop/DemoBundle/public/demo_fullscreen.css` and have the following definition: .. code-block:: css @@ -220,11 +211,11 @@ The result of these few lines of css will look like this: .. image:: ../../figures/workshop_application.png :scale: 80 -When you open your new application a css-file will be created at: +When you open your new application, a css-file will be created at: -* ``web/assets/WorkshopDemoBundle__demo_fullscreen__css.css`` +* `web/assets/WorkshopDemoBundle__demo_fullscreen__css.css` -If you do further edits at your css file you may have to delete the generated css file in the assets directory to see the changes. You should also clear the browser cache. +If you do further edits at your css file, you may have to delete the generated css file in the assets directory to see the changes. You should also clear the browser cache. .. code-block:: bash @@ -236,15 +227,14 @@ Style the administrational pages Please change the following css-files for the :ref:`backend` pages: - * login.css : Change the design of the login page - * manager.css : Change the design of the administration pages (e.g. application overview) - * password.css : Change the design of the password pages (e.g. Reset Password - page) + * *login.css*: Change the design of the **login page**, + * *manager.css*: Change the design of the administration pages (e.g. **Application**), + * *password.css*: Change the design of the password pages (e.g. **Reset Password**). You only have to define the parts that have to look different than the default page style. +Developer tools can help you to find out the styles you want to change. -Firebug can help you to find out the styles you want to change. - -Referencing the CSS-files is possible with FOMManagerBundle and FOMUserBundle. They must be filed under ``app/Resources/``. The already contained twig-files overwrite the default settings if configured correctly (Requirements from manager.html.twig file). +Referencing the CSS-files is possible with FOMManagerBundle and FOMUserBundle. They must be filed under `app/Resources/`. The already contained twig-files overwrite the default settings if configured correctly (Requirements from *manager.html.twig* file). Alternatively, it is possible to copy a twig-file and adjust it afterwards. .. code-block:: bash @@ -253,16 +243,16 @@ Alternatively, it is possible to copy a twig-file and adjust it afterwards. Register your bundle in config/bundles.php -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +****************************************** -Add write access to the ``public`` directory for your webserver user, if need be: +Add write access to the `public` directory for your webserver user, if need be: .. code-block:: bash chmod ug+w public -Update the ``public`` directory. Each bundle has its own assets - CSS files, JavaScript files, images and more - but these need to be copied into the public web folder: +Update the `public` directory. Each bundle has its own assets - CSS files, JavaScript files, images and more - but these must be copied into the public `web` folder: .. code-block:: bash @@ -280,13 +270,15 @@ Now your template should show up in the template list when you create a new appl How to use a new template -~~~~~~~~~~~~~~~~~~~~~~~~~ +************************* + There are different ways of how to use the new template: -Usage in YAML-applications -************************** -You can adjust the YAML-applications in ``config/applications`` and change the template parameter. +Usage in YAML applications +========================== + +You can adjust the YAML-applications in `config/applications` and change the template parameter. .. code-block:: yaml @@ -294,24 +286,26 @@ You can adjust the YAML-applications in ``config/applications`` and change the t Usage in new applications from the backend -****************************************** +========================================== If you create a new application in the administration interface of Mapbender, you can choose the new template. Usage in an existing application -******************************** +================================ -For existing applications you can change the parameter in the Mapbender database in the column ``template`` of the table ``mb_core_application``. +For existing applications, you can change the parameter in the Mapbender database in the column **template** of the table **mb_core_application**. -For the *WorkshopDemoBundle* you change the entry from ``Mapbender\CoreBundle\Template\Fullscreen`` to ``Workshop\DemoBundle\WorkshopDemoBundle``. +For the **WorkshopDemoBundle**, you can change the entry from ``Mapbender\CoreBundle\Template\Fullscreen`` to ``Workshop\DemoBundle\WorkshopDemoBundle``. Usecases -~~~~~~~~ +******** + +Q: How do I change the logo, the title and the language? + +A: This and more tips can be found under :ref:`yaml`. -How do I change the logo, the title and the language? -This and more tips can be found here: :ref:`yaml`. How do I change the buttons? **************************** @@ -328,7 +322,7 @@ Mapbender uses 'Font Awesome Icons' font icon collection: font-style: normal; } -In your css-file you can refer to a font images like this: +In your CSS file, you can refer to a font images like this: .. code-block:: css @@ -336,7 +330,7 @@ In your css-file you can refer to a font images like this: content: "\f02f"; } -If you want to use an image you could place the image in your bundle and refer to it like this +If you want to use an image, you could place it in your bundle and refer to it like this: .. code-block:: css @@ -346,12 +340,12 @@ If you want to use an image you could place the image in your bundle and refer t Try this out -~~~~~~~~~~~~ - -* you can download the Workshop/DemoBundle at https://github.com/mapbender/mapbender-workshop -* change the color of your icons -* change the size of your icons -* change the color of the toolbar -* use an image instead of a font-icon for your button -* move the position of your overview to the left -* Have a look at the workshop files to see how it works +************ + +* you can download the Workshop/DemoBundle `here `_, +* change the color of your icons, +* change the size of your icons, +* change the color of the toolbar, +* use an image instead of a font-icon for your button, +* move the position of your overview to the left, +* Have a look at the workshop files to see how it works.