Skip to content

Customization

Jump to bottom
Helmut Wolman edited this page Sep 16, 2024 · 16 revisions

Clients are motivated to have their own customization. Having that on mind, Karte von Morgen is designed to be highly flexible. Hence, we respect the Open-Closed Principle in every aspect of project. By that we mean adding a customization should be possible by adding a file or few files, but not changing the code base. Which led us to separate configuration and styling files from the project.

To manage Karte von Morgen well-structured we keep all of data related to a project will be under directories with the name of the project The 'public* folder is just needed for development purposes. The Enduser accesses the csv file without the 'public' folder in the domain. i.e. https://dev.kartevonmorgen.org/projects/main/dropdowns/categories.csv

Predefined Tags

predefined set of tags, which is shown like categories:

  • as a dropdown in the search bar #364 and #776
    • as a dropdown in the tags field while editing
  • as a checkbox-list below the search-field (in the filter area) #68
    • as a checkbox-list above the tagfield while editing #760

Dropdowns

This predefined list of categories (prominent tags) is customizable. Each iframe / URL can redirect to a different set by just changing the URL from /m/main? to /m/${project}? Example: https://new.kartevonmorgen.org/m/main?c=50,10&z=7.00 to https://new.kartevonmorgen.org/m/edu?c=50,10&z=7.00

File directory

categories

When the search input is empty, the dropdown displays a adaptable set of important tags and categories based on its CSV file.

Sample File for category CSV A sample file for the categories CSV

CSV Preview for category csv

label value headline bold underline italic fontSize icon
Aktion der Woche true
regionale Einkaufsführer einkaufsführer
Kleidung & secondhand (fairfashion) fair fairfashion Kleidung secondhand futurefashion
Beispiele zur erweiterten Suche true
#Fridays – filtern nur nach Stichworten #Fridays

Image Preview

Categories Dropdown

regions

Also key regions can be defined as CSV file, which will be promoted by clicking in the location searchfield below the content search. The search filters shows these regions as a Select dropdown that when a client click on the desired option, the map flies to the specified region.

Sample File for regions csv A sample file for the regions CSV

CSV Preview

label value headline bold underline italic fontSize
… Bitte Ortsnamen eingeben und Enter drücken
Baden-Württemberg: true
Stuttgart Stuttgart
Karlsruhe Karlsruhe
Freiburg Freiburg

Image Preview Regions Dropdown

Technical Discussion on dropdowns Issues: #364 and #776

Checkboxes

This feature should help fast filtering and mapping. You can define a few checkboxes (we recommend less than 10) that help the user to filter for prominent topics and especially to map easily with the correct tags. Behind one checkbox can be many tags. It's possible to facilitate the search options by providing a set of tags as checkboxes. These checkboxes render at the search filter area and the add/edit entity forms. The data for the checkboxes from a configurable CSV file.

File directory

Sample File A sample file for the checkboxes CSV

CSV Preview

label value
regionale Einkaufsführer einkaufsführer
Lebensmittel bio,Lebensmittel,vegan,weltladen

Image Preview Checkboxes in the search filters

Checkboxes in the forms

Technical Discussion Issue #760

Map Config

General configuration of map including the default center and zoom when map opens

{
  "map": {
    "location": {
      "lat": 50.826,
      "lng": 5.6030,
      "zoom": 6
    },
	"colorStyle": "standard"
  },
  "popularTags": {
    "min_count": 2
  },
  "sidebar": {
    "title": 
   }
}

File directory

  • Config: public/projects/${project}/config.json

Map Color

Sometimes its better if the map-background is just grey to have less disturbance for website-visitors and to make especially green points more prominent.

In the config.json you can define, if the default view of the map is grey or colorful grafik

  • color: "colorStyle": "standard"
  • grey: "colorStyle": "gray"

Every User can change the background color with the slider on the right side, and for each Iframe you can just define the background color by the following URL-Attribute:

Technical discussion Issue: https://github.com/kartevonmorgen/kartevonmorgen.ts/issues/227

Styles

The general style of project is defined under styles directory File directory

  • Styles: /styles/${project}

Pins

The balloons can be replaced with new images File directory

  • Pins: public/projects/${project}/pins

Pin Colours

The Colour of pins are adjustable, based on their hashtags. As requirement the pin colors should be adjustable based on tags easily. For that reason, we introduced a csv configuration in which tags and their colors can be defined, and the pins or markers will get that color dynamically. A German End-User description of this function can be found here: https://blog.vonmorgen.org/pin-farben/

File directory The configuration file is under: public/projects/{project}/pins/dynamic_colors.csv

Configuration structure It has two columns of tag and color. the tag is a single string representing a tag. And, the color can be any valid css color like: #ADFF2F, greenyellow, or etc.

File example

tag color
refill-station #ffa500
refill goldenrod
cd greenyellow

Screenshot customized map marker colors based on tags

Error-Handling Most errors occur, if you have a spacing in the color-coloum.

Technical Details

When a map marker wants to get rendered it calls NextJS backend api with the tags from the entry to check whether there's any color associated with them or not. if there any tag of the entry exist in the csv file the first matching color will return to be used in the markers.

In the end if no matching color excited in the configuration, the default colors or icons will be used.

Map markers there are two different map markers. circles and balloons.

  • circles: the color will be used as is without any changes
  • balloons: as the first iteration of test I realized using a single color for the balloons will cause the problem of inconsistency and decreases the quality of user interface as it will be flatted and will have no beautiful 3D shades. therefore, in order to keep the consistency as much as possible I used the lightness values from the default balloon SVGs. the lighnesses and offsets are:
[
  {
    "offset": 0,
    "lightness": 0.94
  },
  {
    "offset": 0.1285,
    "lightness": 0.87
  },
  {
    "offset": 0.2977,
    "lightness": 0.79
  },
  {
    "offset": 0.4696,
    "lightness": 0.73
  },
  {
    "offset": 0.643,
    "lightness": 0.68
  },
  {
    "offset": 0.8186,
    "lightness": 0.66,
  },
  {
    "offset": 1,
    "lightness": 0.65,
  },
]

API endpoint: /api/v0/maps/main/tags/markers/colors params: tags: string[] (optional) returns:

  • all tag colors tags params is not peresent
  • first matching tag color if a tag from the tag param exists in the configuration
  • otherwise, an empty array with the hasData: false

Test Cases

tag color
refill-station #ffa500
refill goldenrod
cd greenyellow

Technical discussion issue: #5

Icons

You can add Icons to the Pins on the map and you could change the icons in the burger menu.

File directory

  • Config: public/projects/${project}/pins/dynamic_icons.csv
tag icon
refill FaRegFutbol

https://github.com/kartevonmorgen/kartevonmorgen.ts/blob/develop/public/projects/main/pins/dynamic_icons.csv Icon-Name from https://react-icons.github.io/react-icons/

Not any icon can be just used, but we have to import it to our repo in https://github.com/kartevonmorgen/kartevonmorgen.ts/blob/develop/components/MapMarkerIcon.tsx and deploy a new version.

Technical discussion Issue: https://github.com/kartevonmorgen/kartevonmorgen.ts/issues/218

Burger Menu

The burger menu appears on the top right corner of the map and is responsible for showing primary links. This menu is configurable through its config file. The top right is dynamic in terms of link, title, icon, and policy. policy is the strategy whether to open the link in the current tab or open a new one

File directory

  • Burger menu Icons: public/projects/${project}/icons/burger-menu-icon.webp
  • Burger menu: public/projects/${project}/burger-menu.json
  • Burger menu icon: /public/projects/${project}/icons/burger-menu-icon.webp

Sample files

JSON Scheme (Technical) Here on the repository you can find the actual type of burger menu config
Here is the link to LinksWithIcon data transfer object: link

JSON Scheme (Non-Technical)

[
  {
    link: string
    title: string
    icon: fontAwesomeIconName
    policy: "self" | "newTab"
  }
]

The type of icon is font-awesome IconProp but for the sake of simplicity let's consider that a font-awesome icon name

Image Preview Burger Menue

Visit Kartevonmorgen.org or find further How-Tos of to use the map.

Clone this wiki locally