Layout

Introduction

A map.apps layout consists of two bundles

theme-* (for example everlasting) which defines colors, fonts, hover effects, graphics and more
template-* (for example seasons) which defines the general positioning of widgets on the screen.

Both bundles are needed to run a map.apps app and can be configured in the app.json. The default map.apps themes are created using LessCSS . It has features like variables and functions, which simplifies the customization of themes. Color and font adaption can be done in a single file by changing the according variables. During the build process of the map.apps project the LESS files are converted to ordinary CSS files.

Configure your app to use an existing theme

No configuration needed. Add the theme-bundle’s name (for example theme-everlasting) to the allowedBundles list in app.json. The theme is applied on app startup.

Configure your app to use an existing template

No configuration needed. Add the template-bundle’s name (for example template-seasons) to the allowedBundles list in app.json. The template is applied on app startup.

Creation of a custom theme

If none of the provided theme bundles ( theme-everlasting , theme-summer , theme-winter , theme-autumn , theme-spring ) matches your design requirements, it is possible to create a whole new theme from scratch (by completely rewriting the CSS code) or by using the mapapps-4-developers project to kickstart theming. With this project it is possible to change color values and create a new map.apps look.

The following section explains the process in detail. It is assumed that the latest release of mapapps-4-developers project is already downloaded and extracted to a location of your choice. For later reference, this location is called [mapapps-4-developers]. In this example, the name of the new theme is elephant which can of course be replaced by anything that fits your context.

Step 1: Create theme bundle

Start with duplicating the folder theme-custom (with its contents) at [mapapps-4-developers]/src/main/js/bundles/ and rename it to theme-elephant. Open the manifest.json at [mapapps-4-developers]/src/main/js/bundles/theme-elephant and change both occurrences of "name": "theme-custom" to "name": "theme-elephant". It is also possible to change the metadata such as version or description to your needs.

Inside the themeSettings.less at [mapapps-4-developers]/src/main/js/bundles/theme-elephant/styles change the variable @themeName from theme-custom to theme-elephant.

Step 2: Adjust Gulpfile

Gulp is used to copy and compile the map.apps theme base resources for a theme. Add the custom theme inside the themes and themeChangeTargets array in [mapapps-4-developers]/gulpfile.js:

gulpfile.js

...
mapapps.registerTasks({
    /* A detailed description of available setting is available at https://www.npmjs.com/package/ct-mapapps-gulp-js */
    /* a list of themes inside this project */
    themes: [
        'theme-a',
        'theme-elephant'
    ],
    /* state that the custom theme is depending on map.apps everlasting theme that provides the base styles */
    hasBaseThemes: true,
    /* state that vuetify components are supported and therefore vuetify core styles are needed */
    hasVuetify: true,
    themeChangeTargets: {
        "vuetify": [
            "theme-custom",
            "theme-elephant"
        ]
    }
});
...

Step 3: App Configuration and launching development server

Now add the theme bundle to the app (for example the sample app at [mapapps-4-developers]/src/main/js/apps/sample/app.json). Make sure that there is no other theme-bundle inside the allowedBundles list.

Now the development server can be launched with the command line mvn jetty:run -Pwatch all. If you are unsure what to do, refer to the Readme.md inside the mapapps-4-developers project repository.

Step 4: Customize the theme’s color

The theme is now ready to be customized by changing for example the color variable values inside the themeSettings.less file at [mapapps-4-developers]/src/main/js/bundles/theme-elephant/styles.

+ Besides of altering the values of variables, it is also possible to add custom LESS/CSS code (for example to provide styling for a custom bundle).

Change the position of a bundle’s widget or window behavior

The UI widgets provided by any map.apps bundle can be placed either inside a toggleable window or directly visible inside the app’s header, footer or map container. The default behavior and position of widgets can be customized. More info about re-configuration of UI-widgets can be found inside the template’s bundle documentation . If you are interested in which attachpoints are provided by map.apps default layout template bundle refer to the template-seasons documentation .