customization.md

Customization

You can override default settings, colors, CSS, HTML and translations in your own customization folder.

See the general presentation for an overview of the application.

After each customization changes, you'll have to restart the Docker container by running docker-compose restart.

Settings

Default configuration are defined in files from https://github.com/GeotrekCE/Geotrek-rando-v3/tree/main/frontend/config folder. You can override all settings default values in files from your own customization/config/ folder.

Examples of customizations are available in https://github.com/GeotrekCE/Geotrek-rando-v3/tree/main/frontend/customization/config folder.

In json files, you can just override the primary keys you need. You have to override primary keys globally.

• global.json (default value in https://github.com/GeotrekCE/Geotrek-rando-v3/blob/main/frontend/config/global.json) to define :

  • searchResultsPageSize, mapResultsPageSize: used to limit the sizes of results per page when fetching API
  • maxPoiPerPage: max number of point of interest (POI) displayed on a single trek page
  • maxTouristicContentPerPage: max number of touristic contents displayed on a single trek page
  • portalIds: eventual portal filters (list of ids).
  • enableSensitiveAreas: boolean, default to false. Set it to true if sensitive areas are defined in your Geotrek-admin
  • enableOutdoor: : boolean, default to false. Set it to true to enable Outdoor sites and courses
  • apiUrl : Geotrek-admin API URL
  • googleAnalyticsId: eventual Google Analytics Id
  • googleSiteVerificationToken: eventual code to enable Google Search Console and Google developer tools
  • enableIndexation to disable search engine indexation
  • baseUrl: base URL of your portal (for dynamic sitemap.xml)
  • fallbackImageUri: this uri is used to generate a default image for a trek or a touristic content if none is defined
  • touristicContentLabelImageUri : this uri is used to define the logo of the labeled touristic contents:
  • applicationName: application name appearing on PWA
  • enableReport: to enable report form in trek detail pages
  • enableSearchByMap: to enable searching by map displayed area (bbox)

• header.json to define logo URL, default and available languages, number items to flatpages to display in navbar (see default values in https://github.com/GeotrekCE/Geotrek-rando-v3/blob/main/frontend/config/header.json)

• home.json to define homepage settings. You can define blocks to display and trek suggestion block with trek ID to highlight on homepage (see https://github.com/GeotrekCE/Geotrek-rando-v3/blob/main/frontend/customization/config/home.json).

  • In welcomeBanner, you can personnalize the cover on the homepage. You can add an asset on the top of the page: it can either be a video, a single picture or a carousel of images:

    • videoUrl: to add a video
    • carouselUrls: to add a carousel of images. You have to add an array of urls
    • pictureUrl: to add a single image

    Only one type of asset can be displayed. If you add several fields (videoUrl and pictureUrl for example), we will pick one, following this order of priority: video over carousel over picture.

    You can also enable a text to be displayed on the top of this asset:

    • shouldDisplayText: true to display the text on above the asset, false to hide it.

• In the footer.json file, you can define social networks, informations about your organization, and some links (see example in https://github.com/GeotrekCE/Geotrek-rando-v3/blob/main/frontend/customization/config/footer.json).

  • Social networks: facebook, twitter, youtube, instagram or fallback.
  • Contact information such as your name, address, phone number and email.
  • Links based on the key pair label/url (can be based on translation labels for multilingual) and/or the key informationID whose value is equal to a flatpage identifier.

• filter.json to define filters to hide, their order and values (see example in https://github.com/GeotrekCE/Geotrek-rando-v3/blob/main/frontend/config/filter.json). If you want to hide some of the filter, you have to override their properties with "display": false

• map.json to define basemaps URL and attributions, center (y, x), default and max zoom level (see example in https://github.com/GeotrekCE/Geotrek-rando-v3/blob/main/frontend/customization/config/map.json).

  • You can also update the map layers. There are two map layers available:

    • mapClassicLayerUrl for the map version
    • mapSatelliteLayerUrl for the satellite version. It is optional, so if you want to have only one available map background, you can add mapSatelliteLayerUrl: undefined. This will remove the button which allows the user to switch between two map backgrounds.

  • zoomAvailableOffline allows you to define the zoom modes allowed in offline mode. This allows you to control the amount of disk space required when caching. Default [13,14,15]

• redirects.json to define URL rewriting for your instance. For example, you can use this customization to redirect old URL style (Geotrek-rando V2) to the new URL style (Geotrek-rando V3) or to redirect old URL to a new URL after changing the name of a hike in the backend.

  • In rules, you can define all the rules needed to redirect clients

    • source: must match to the old URL. Use the wildcard * to redirect a subdirectory. Use :varname to forward a variable to the destination
    • destination: must match to the new URL. Use :varname to inject a variable captured in the old URL
    • permanent: Set to true if the redirection is permanent. Set to false if the redirection is temporally. Default to false

    Examples :

    {
      "rules": [
        {
          "source": "/a-cheval/col-de-font-froide",
          "destination": "/trek/582-col-de-font-froide"
        },
        {
          "source": "/a-pied/:name",
          "destination": "/search?rawText=:name"
        },
        {
          "source": "/fr/walking/:name",
          "destination": "/en/search?rawText=:name",
          "locale": false
        }
      ]
    }

    You can find more examples and more details following this link : https://nextjs.org/docs/api-reference/next.config.js/redirects

Warning:

• When setting up Google Analytics, you have to setup a flow. When setting up the flow, be careful to enter the corresponding url (the url of your website), otherwise the data will not be received.
• By default Google analytics is disabled (googleAnalyticsId set to null), you will have to override it in the global.json file of your customization folder.

Colors

You can override colors in customization/theme/colors.json file to change the main colors, based on https://github.com/GeotrekCE/Geotrek-rando-v3/blob/main/frontend/tailwind.config.js default theme.

Example for Cevennes national park orange colors:

{
  "primary1": {
    "DEFAULT": "#ff9100",
    "light": "#ffa032"
  },
  "primary3": "#d57b04"
}

You can also override CSS in customization/theme/style.css file. To help overriding CSS, some ID have been added on main DIV components (header, logo, footer, cover, cards, results, maps, details...).

Translations

You can override every texts in translations files, based on default ones (https://github.com/GeotrekCE/Geotrek-rando-v3/tree/main/frontend/src/translations).

You should at least override home.title, home.description and home.welcome-text.

HTML

You can include some HTML parts in the first and last sections of the homepage, with files:

• customization/html/homeTop.html
• customization/html/homeBottom.html

See HTML examples in https://github.com/GeotrekCE/Geotrek-rando-v3/tree/main/frontend/customization/html.

Icons are provided by Geotrek-admin API. See icons documentation to know how they have to be designed.

Images, favicon, mobile phone icons and splashscreens

These files need to be in the correct folder during the build process and therefore, we created a specific medias folder in the customization repository.

It provides 6 default images that can be customized:

• android-icon.png: It has to be 144x144px and controls the icon appearing on Android phones
• maskable-icon.png: It hass to be 144x144px and will be used only on android phones enabling round icons (it will hence be cropped to fit a circle by the android phones)
• ios-icon.png: It has to be 144x144px and controls the icon appearing on iOS phones
• android-splashscreen.png: It has to be 512x512px and controls the splashscreen appearing on Android phones
• ios-splashscreen.png: It has to be 512x512px and controls the splashscreen appearing on iOS phones
• favicon.png: It will be used as the favicon in web browsers

You can also add images and other files in the medias folder to be used as logo, images in HTML parts and static pages. They will be available on "url-geotrek-rando/medias/image-name.jpg" and can be linked as "/medias/image-name.jpg".

Apply changes

After each customization changes, you'll have to restart the Docker container by running docker-compose restart.