Introduction

This book is targeted at Mapbender developers and will cover useful topics not needed by administrators or users of Mapbender installations.

Things to consider

Warning

The development section of the documentation is partly deprecated, please read with caution. An updated technical documentation for developers is integrated into the Mapbender source code. It can be read directly on GitHub.

There are a couple of things you should be familiar with in order to contribute to Mapbender:

  • Object-Orientated PHP: We’re using PHP which offers full object orientation.

  • Symfony: This is what we build upon. So read The Book to learn more about Symfony.

  • JavaScript: We use jQuery a lot and especially the jQuery UI widget factory. These are essential to understand to write maintainable JavaScript code.

Installation

The installation procedure from Git is described under Git-based installation.

Modules and bundles

Please refer to the respective sections in the CONTRIBUTING.md guide to understand what modules and what bundles are, and how the latter can be created.

Twig

Symfony follows the template approach and we use this in Mapbender. Symfony uses a templating engine to generate HTML, CSS or other content. A template is a text file that can generate any text based format like HTML, XML. It is used to express presentation and not programm logic. You can use them to create a layout. You can create a base layout and then overwrite or append any of your layout blocks with individual templates. Read more about Templates in Mapbender at How to create your own Template? or in the Contributing Guide and find a good introduction about Twig in the Symfony Template documentation.

Overriding JavaScript and CSS/Sass Resources

Using the ApplicationAssetService class, JavaScript and CSS/Sass resources can be manually overridden:

To do this, use mapbender.application_asset.service within a class, e.g., in the boot method of your bundle file with $this->container->get('mapbender.application_asset.service'). Alternatively, you can achieve this behavior in any PHP file with <argument type="service" id="mapbender.application_asset.service" />. Make sure to use a file that gets called, such as the template.

Then, call ApplicationAssetService::registerAssetOverride or ApplicationAssetService::registerAssetOverrides to mark assets for replacement. Below you will find an example that utilizes custom resources for the Button class:

class MyBundle extends Bundle
{
   [ ... ]

   public function boot(): void
   {
      parent::boot();
      $assetService = $this->container->get('mapbender.application_asset.service');
      $assetService->registerAssetOverride('@MapbenderCoreBundle/Resources/public/sass/element/button.scss', '@MyBundle/Resources/public/element/my_button.scss');

      $assetService->registerAssetOverrides([
            '@MapbenderCoreBundle/Resources/public/sass/element/button.scss' => '@MyBundle/Resources/public/sass/element/my_button.scss',
            '@MapbenderCoreBundle/Resources/public/js/element/button.js' => '@MyBundle/Resources/public/js/element/my_button.js',
      ]);
   }
}

Hint

It is also possible to override a resource in the parameters.yaml file.