Home > Configuration > Advanced: Custom Mapping
Advanced: Using a Custom Mapping Function
There may be special situations where the way Sitemapper automatically maps the pages in your site might not work well for you. This might be the case, for instance, if you are using virtual pages to generate your site's pages on-the-fly, or if you are remapping your pages' URLs with special custom routes. In these cases, in order to get a good sitemap, you will have to define your own, custom mapping function.
When you define a custom mapping function, it overrides Sitemapper's own mapping routines. That means that any 'sitemap' blueprint options or 'sitemap' fields will be ignored, and it is totally up to you to decide which pages and images get added to your map.
You can define a custom mapping function with a 'customMap' option in your 'config.php' file, like this:
'cre8ivclick.sitemapper.customMap' => function($s){
// function code goes here - build the map:
$map = [];
...
// last of all, return the map:
return $map;
}The function receives a single parameter: the site object - equivalent to what you get with Kirby's 'site()' helper. The function should build a '$map' array, as described below, with information about all pages and images to be listed in the sitemap. Make sure that the format of the array you build is exactly as outlined below.
Last of all, the function must return the '$map' array. Sitemapper will then use the array to dynamically generate the sitemap for you.
The $map Array Format
Your custom mapping function must return an array in the exact format described here.
At the top level, each item in the array represents a page in the map - and the key of each item is the page URL:
$map = [
Page1URL => [],
Page2URL =>[],
Page3URL => [],
...
] Each page is itself an array, with 3 possible keys:
- mod is required: it is the last modification date of this page, in ISO 8601 date format (get it by using the 'c' format string with PHP's 'date' handler)
- images is optional: if present, it should be a simple list of URLs for images present on the page
- lang is optional: used only in multilingual sites, when there are multiple versions of a page in different languages - see section below.
In a single-language site with 2 pages - a home page and a 'landing' page - where both pages have only a couple of images each, our array might look like this:
$map = [
'https://example.com' => [
'mod' => '2019-11-04T13:47:32+11:00',
'images' => [
'https://example.com/media/pages/home/image1.jpg',
'https://example.com/media/pages/home/image2.jpg'
]
],
'https://example.com/landing' => [
'mod' => '2019-11-03T10:12:03+11:00',
'images' => [
'https://example.com/media/pages/landing/graph-a.jpg',
'https://example.com/media/pages/landing/graph-b.jpg'
]
]
];Multilingual Sites and 'lang' Entries
Not every page in a multilingual site is a multilingual page. Even if the page is meant to be translated into several languages, maybe the translations aren't ready yet, and the page might only be available in the default language. If a page is only available in a single language, you don't need to add a 'lang' key to your array at all: just treat is as a normal, single-language page.
We only need to add 'lang' when there are alternative versions of the page in other languages - that is what the 'lang' key is for. The 'lang' entry is an array, where each entry represents one translation/version of the page, like this:
$map = [
'https://example.com' => [
'mod' => '2019-11-04T13:47:32+11:00',
'lang' => [
'en' => [], // info about English version of page
'de' => [], // info about German version of page
'x-default' => [] // optional info about 'default' page
]
]
]Each entry in 'lang' is itself an array with 2 required items: locale (the RFC 4646 locale of the language - using hyphens, not underscores), and url (the URL of the page for that language). It is also recommended that you add an 'x-default' entry that helps search engines understand which page should be shown as the 'default', when no search language is specified.
Important: when listing pages in multiple languages using 'lang', every page listed in your 'lang' entries must also have its own separate listing in the sitemap - or search engines are likely to ignore it. For example: if you are listing a 'landing' page as having versions in both English and German, you must have 2 separate entries in the sitemap: one for the page in English, one for the page in German. In both entries you must have a 'lang' entry that lists both versions of the page (in English and German).
As an example, let's say that we have a single-page website - just a home page - which has 2 images, and is available in both English and German. If English is the 'default' language, our '$map' array might look like this:
$map = [
'https://example.com' => [
'mod' => '2019-11-04T13:47:32+11:00',
'images' => [
'https://example.com/media/pages/home/image1.jpg',
'https://example.com/media/pages/home/image2.jpg'
],
'lang' => [
'en' => [
'locale' => 'en-AU',
'url' => 'https://example.com'
],
'de' => [
'locale' => 'de-DE',
'url' => 'https://example.com/de'
],
'x-default' => [
'locale' => 'x-default',
'url' => 'https://example.com'
]
]
],
'https://example.com/de' => [
'mod' => '2019-11-04T16:11:02+11:00',
'images' => [
'https://example.com/media/pages/home/image1.jpg',
'https://example.com/media/pages/home/image2.jpg'
],
'lang' => [
'en' => [
'locale' => 'en-AU',
'url' => 'https://example.com'
],
'de' => [
'locale' => 'de-DE',
'url' => 'https://example.com/de'
],
'x-default' => [
'locale' => 'x-default',
'url' => 'https://example.com'
]
]
]
];Note that the 'lang' entry for all the different translated versions of the page should actually be the same.
< Configuration/Extra Filtering Function Configuration/Examples >