docs(map): Revamp Overview, Tile and Marker examples and provide CSP information

_contentTemplates/map/general.md

@@ -0,0 +1,3 @@
+#urltemplate-csp
+> The Map component provides two ways to define the `UrlTemplate` of tile layers and the `MapLayerMarkerSettings` `Template` of marker layers. See [Map Content Security Policy]({%slug components/map/overview%}#content-security-policy) for more information and comparison.
+#end

components/map/events.md

@@ -556,6 +556,8 @@ The `OnPanEnd` event fires when the user has finished moving (panning) the Map.
 }
 ````
 
+@[template](/_contentTemplates/map/general.md#urltemplate-csp)
+
 ## See Also
 
 * [Live Demo: Map Events](https://demos.telerik.com/blazor-ui/map/events)

components/map/layers/bubble.md

@@ -112,7 +112,3 @@ The following example demonstrates how to configure the Map Bubble Layer.
     }
 }
 ````
-
->caption The result from the above code snippet.
-
-![Blazor Map Bubble Layer](../images/bubble-layer.png)

components/map/layers/overview.md

@@ -21,46 +21,48 @@ The layers in the Map are:
 * [Shape]({%slug components/map/layers/shape%})
 * [Bubble]({%slug components/map/layers/bubble%})
 
-## MapLayers Parameters
+## MapLayer Parameters
 
 The following parameters enable you to customize the appearance of the Blazor Map Layers:
 
+@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout)
+
 | Parameter | Type | Description |
-| ----------- | ----------- | ----------- |
-| `Type` | `MapLayersType (enum)` | The type of the layer. |
+| --- | --- | --- |
 | `Attribution` | `string` | The attribution for the layer. |
-| `Subdomains` | `string[]` | A list of subdomains to use for loading tiles. Alternating between different subdomains allows more requests to be executed in parallel. |
-| `UrlTemplate` | `string` | The URL template for tile layers. Template variables: x - X coordinate of the tile; y - Y coordinate of the tile; zoom - zoom level or subdomain - Subdomain for this tile. See subdomains. |
-| `Shape` | `MapMarkersShape (enum)` | The marker shape for marker layers. |
-| `Symbol` | `MapLayersSymbol (enum)` | The default symbol for bubble layers. |
-| `ZIndex` | `double` | The zIndex for this layer. Layers are normally stacked in declaration order (last one is on top). |
-| `ValueField` | `string` | The value field for bubble layer symbols. The data item field should be a number. |
-| `Extent` | `double[]` | Specifies the extent of the region covered by this layer. The layer will be hidden when the specified area is out of view. Accepts a four-element array that specifies the extent covered by this layer: North-West latitude, longitude, South-East latitude, longitude. |
 | `Data` | `object` | The data for the layer. |
+| `Extent` | `double[]` | Specifies the extent of the region covered by this layer. The layer will be hidden when the specified area is out of view. Accepts a four-element array that specifies the extent covered by this layer: North-West latitude, longitude, South-East latitude, longitude. |
 | `LocationField` | `string` | The data item field which contains the marker (symbol) location. The field should be an array with two numbers - latitude and longitude in decimal degrees. |
-| `TileSize` | `double` | The size of the image tile in pixels. |
-| `TitleField` | `string` | The data item field which contains the marker title. |
 | `MaxSize` | `double` | The maximum symbol size for bubble layer symbols. |
-| `MinSize` | `double` | The minimum symbol size for bubble layer symbols. |
 | `MaxZoom` | `double` | The maximum zoom level at which to show this layer. |
+| `MinSize` | `double` | The minimum symbol size for bubble layer symbols. |
 | `MinZoom` | `double` | The minimum zoom level at which to show this layer. |
 | `Opacity` | `double` | The opacity for the layer. |
+| `Shape` | `MapMarkersShape` enum | The marker shape for marker layers. |
+| `Subdomains` | `string[]` | A list of subdomains to use for loading tiles. Using multiple subdomains allows more requests to be executed in parallel. Also see `UrlTemplate`. |
+| `Symbol` | `MapLayersSymbol` enum | The default symbol for bubble layers. |
+| `TileSize` | `double` | The size of the image tile in pixels. |
+| `TitleField` | `string` | The data item field which contains the marker title. |
+| `Type` | `MapLayersType` enum | The type of the layer. |
+| `UrlTemplate` | `string` | The URL template for tile layers. The available variables are: <ul><li>`x`&mdash;the X coordinate of the tile;</li><li>`y`&mdash;the Y coordinate of the tile</li><li>`zoom`&mdash;the zoom level</li><li>`subdomain`&mdash;the subdomain for this tile. Also see `Subdomains`. <br />There are [two possible ways to define the `UrlTemplate`]({%slug components/map/overview%}#content-security-policy). |
+| `ValueField` | `string` | The value field for bubble layer symbols. The data item field should be a number. |
+| `ZIndex` | `double` | The zIndex for this layer. Layers are normally stacked in declaration order (last one is on top). |
 
 ### MapLayersMarkerSettings parameters
 
 The following parameters enable you to customize the appearance of the Blazor Map Marker Layers:
 
 | Parameter | Type | Description |
-| ----------- | ----------- | ----------- |
-| `Tooltip` | `object` | The configuration of the marker tooltip. |
+| --- | --- | --- |
 | `Template` | `RenderFragment` | Specifies the tooltip template. |
+| `Tooltip` | `object` | The configuration of the marker tooltip. |
 
 ### MapLayersBubbleSettingsStyleFill parameters
 
 The following parameters enable you to customize the appearance of the Blazor Map Bubble Layers:
 
 | Parameter | Type | Description |
-| ----------- | ----------- | ----------- |
+| --- | --- | --- |
 | `Color` | `string` | The default fill color for layer bubbles. Accepts a valid CSS color string, including hex and rgb. |
 | `Opacity` | `double` | The default fill opacity (0 to 1) for layer bubbles. |
 
@@ -69,9 +71,8 @@ The following parameters enable you to customize the appearance of the Blazor Ma
 The following parameters enable you to customize the appearance of the Blazor Map Bubble Layers:
 
 | Parameter | Type | Description |
-| ----------- | ----------- | ----------- |
+| --- | --- | --- |
 | `Color` | `string` | The default stroke color for layer bubbles. Accepts a valid CSS color string, including hex and rgb. |
-| `Opacity` | `double` | The default fill opacity (0 to 1) for layer bubbles. |
 | `DashType` | `DashType (enum)` | The default dash type for layer bubbles. |
 | `Opacity` | `double` | The default stroke opacity (0 to 1) for layer bubbles. |
 | `Width` | `double` | The default stroke width for layer bubbles. |
@@ -81,7 +82,7 @@ The following parameters enable you to customize the appearance of the Blazor Ma
 The following parameters enable you to customize the appearance of the Blazor Map Shape Layers:
 
 | Parameter | Type | Description |
-| ----------- | ----------- | ----------- |
+| --- | --- | --- |
 | `Color` | `string` | The default fill color for layer shapes. Accepts a valid CSS color string, including hex and rgb. |
 | `Opacity` | `double` | The fill opacity of the shape. |
 
@@ -90,9 +91,8 @@ The following parameters enable you to customize the appearance of the Blazor Ma
 The following parameters enable you to customize the appearance of the Blazor Map Shape Layers:
 
 | Parameter | Type | Description |
-| ----------- | ----------- | ----------- |
+| --- | --- | --- |
 | `Color` | `string` | The stroke color of the shape. |
-| `Opacity` | `double` | The default stroke opacity (0 to 1) for layer shapes. |
 | `DashType` | `double` | The default dash type for layer shapes. The following dash types are supported: "dash" - a line consisting of dashes; "dashDot" - a line consisting of a repeating pattern of dash-dot; "dot" - a line consisting of dots; "longDash" - a line consisting of a repeating pattern of long-dash; "longDashDot" - a line consisting of a repeating pattern of long-dash-dot; "longDashDotDot" - a line consisting of a repeating pattern of long-dash-dot-dot or "solid" - a solid line. |
-| `Opacity` | `double` | The default stroke opacity (0 to 1) for layer bubbles. |
-| `Width` | `double` | The default stroke width for layer shapes. |
+| `Opacity` | `double` | The default stroke opacity (0 to 1) for layer shapes. |
+| `Width` | `double` | The default stroke width for layer shapes. |

components/map/layers/shape.md

@@ -76,7 +76,3 @@ The following example demonstrates how to configure the Map Shape Layer.
     }
 }
 ````
-
->caption The result from the above code snippet.
-
-![Blazor Map Shape Layer](../images/shape-layer.png)

components/map/layers/tile.md

@@ -28,26 +28,25 @@ The following example demonstrates how to configure the Map Tile Layer.
 >caption The Map Tile Layer configuration.
 
 ````CSHTML
-@* This code snippet showcases an example of a Tile Layer configuration. *@
-
-<TelerikMap Center="@Center" Zoom="3">
+<TelerikMap Center="@MapCenter"
+            Zoom="3">
     <MapLayers>
         <MapLayer Type="@MapLayersType.Tile"
-                  Attribution="@Attribution"
-                  Subdomains="@Subdomains"
-                  UrlTemplate="@UrlTemplate">
+                  Attribution="@LayerAttribution"
+                  Subdomains="@LayerSubdomains"
+                  UrlTemplate="@LayerUrlTemplate">
         </MapLayer>
     </MapLayers>
 </TelerikMap>
 
 @code {
-    public string[] Subdomains { get; set; } = new string[] { "a", "b", "c" };
-    public string UrlTemplate { get; set; } = "https://#= subdomain #.tile.openstreetmap.org/#= zoom #/#= x #/#= y #.png";
-    public string Attribution { get; set; } = "&copy; <a href='https://osm.org/copyright'>OpenStreetMap contributors</a>";
-    public double[] Center { get; set; } = new double[] { 30.268107, -97.744821 };
+    private double[] MapCenter { get; set; } = new double[] { 30.268107, -97.744821 };
+
+    public readonly string[] LayerSubdomains = new string[] { "a", "b", "c" };
+    public const string LayerUrlTemplate = "https://#= subdomain #.tile.openstreetmap.org/#= zoom #/#= x #/#= y #.png";
+    public const string LayerAttribution = "&copy; <a href='https://osm.org/copyright'>OpenStreetMap contributors</a>";
+
 }
 ````
 
->caption The result from the above code snippet.
-
-![Blazor Tile Layer](../images/tile-layer.png)
+@[template](/_contentTemplates/map/general.md#urltemplate-csp)

components/map/overview.md

@@ -10,41 +10,32 @@ position: 0
 
 # Blazor Map Overview
 
-The <a href="https://www.telerik.com/blazor-ui/map" target="_blank">Blazor Map component</a> displays geospatial information organized in layers.
-
-The component provides [tile layers]({%slug components/map/layers/tile%}), [shape (vector) layers]({%slug components/map/layers/shape%}), [bubble layers]({%slug components/map/layers/bubble%}), and [marker layers]({%slug components/map/layers/marker%}).
+The <a href="https://www.telerik.com/blazor-ui/map" target="_blank">Blazor Map component</a> displays geospatial information organized in layers. The component provides [tile layers]({%slug components/map/layers/tile%}), [vector shape layers]({%slug components/map/layers/shape%}), [bubble layers]({%slug components/map/layers/bubble%}), and [marker layers]({%slug components/map/layers/marker%}).
 
 ## Creating Blazor Map
 
-1. Use the `TelerikMap` tag to add the component to your razor page.
-
-2. Add the `MapLayer` tag nested inside `MapLayers`.
-
-3. Set the `Type` property.
-
-4. Set the `Attribution` and `Subdomains` properties.
-
-5. Provide the [`UrlTemplate` property]({%slug components/map/layers%}#maplayers-parameters).
+1. Use the `TelerikMap` tag to add the component to a Razor file.
+1. Add a `<MapLayer>` tag nested inside `<MapLayers>`. Set its `Type` to `MapLayersType.Tile`.
+1. Set the [`UrlTemplate` parameter]({%slug components/map/layers%}#maplayer-parameters) of the tile layer. Check the [required syntax that complies with Content Security Policy](#content-security-policy).
+1. (optional) Set the Map `Attribution` and `Subdomains` parameters, depending on the specific tile provider.
 
->caption A basic configuration of the Telerik Map.
+>caption Basic Telerik Map for Blazor
 
 ````CSHTML
-@* This code snippet showcases an example of a basic Map configuration. *@
-
 <TelerikMap>
     <MapLayers>
         <MapLayer Type="@MapLayersType.Tile"
-                  Attribution="@Attribution"
-                  Subdomains="@Subdomains"
-                  UrlTemplate="@UrlTemplate">
+                  Attribution="@LayerAttribution"
+                  Subdomains="@LayerSubdomains"
+                  UrlTemplate="@LayerUrlTemplate">
         </MapLayer>
     </MapLayers>
 </TelerikMap>
 
 @code {
-    public string[] Subdomains { get; set; } = new string[] { "a", "b", "c" };
-    public string UrlTemplate { get; set; } = "https://#= subdomain #.tile.openstreetmap.org/#= zoom #/#= x #/#= y #.png";
-    public string Attribution { get; set; } = "&copy; <a href='https://osm.org/copyright'>OpenStreetMap contributors</a>";
+    private readonly string[] LayerSubdomains = new string[] { "a", "b", "c" };
+    private string LayerUrlTemplate { get; set; } = "https://#= subdomain #.tile.openstreetmap.org/#= zoom #/#= x #/#= y #.png";
+    private const string LayerAttribution = "&copy; <a href='https://osm.org/copyright'>OpenStreetMap contributors</a>";
 }
 ````
 
@@ -70,54 +61,49 @@ Blazor Map also incorporates a navigation tool allowing the end user to easily z
 
 The Blazor Map generates events that you can handle and further customize its behavior. [Read more about the Blazor Map events...]({%slug components/map/events%}).
 
-## Methods
-
-The Map methods are accessible through its reference.
+## Content Security Policy
 
-* `Refresh` - redraws the component.
+The Map renders with the help of a JavaScript-based rendering engine. This engine uses a templating mechanism that supports two kinds of syntax:
 
->caption Get a reference to the Map and use its methods.
+* [Legacy inline syntax](#creating-blazor-map). In this case, the template parameter is a string that consumes dynamic values <a href="https://docs.telerik.com/kendo-ui/framework/templates/essentials" target="_blank">through `#= ... #` expressions</a>, for example, `UrlTemplate="https://#= subdomain #.tile.openstreetmap.org/#= zoom #/#= x #/#= y #.png"`;
+* JavaScript functions that obtain dynamic values from the function arguments, for example, `UrlTemplate="jsFunctionName"`. This feature was introduced in version **4.5.0**.
 
-````CSHTML
-@* This code snippet showcases an example usage of the Refresh() method. *@
+Both syntax options provide the same capabilities. The legacy inline syntax depends on JavaScript code evaluation, which is not [compliant with strict Content Security Policy (CSP)]({%slug troubleshooting-csp%}). The function-based approach is CSP compliant and can be more readable and convenient in complex scenarios.
 
-<TelerikButton OnClick="@( () => ChangeZoom() )">Change Size!</TelerikButton>
-<br />
-<br />
+>caption CSP compliant Map
 
-<TelerikMap @ref="MapRef" Zoom="@Zoom">
+````CSHTML
+<TelerikMap>
     <MapLayers>
         <MapLayer Type="@MapLayersType.Tile"
-                  Attribution="@Attribution"
-                  Subdomains="@Subdomains"
-                  UrlTemplate="@UrlTemplate">
+                  Attribution="@LayerAttribution"
+                  Subdomains="@LayerSubdomains"
+                  UrlTemplate="urlTemplateFunction">
         </MapLayer>
     </MapLayers>
 </TelerikMap>
 
-@code {
-    TelerikMap MapRef { get; set; }
-
-    public double Zoom { get; set; } = 4;
-
-    public void ChangeZoom()
-    {
-        Zoom = 1;
-        MapRef.Refresh();
+@* Move the JavaScript to a separate JS file. *@
+<script suppress-error="BL9992" nonce="BL9992">//
+    function urlTemplateFunction(context) {
+        return `https://${context.subdomain}.tile.openstreetmap.org/${context.zoom}/${context.x}/${context.y}.png`;
     }
+//</script>
 
-    public string[] Subdomains { get; set; } = new string[] { "a", "b", "c" };
-    public string UrlTemplate { get; set; } = "https://#= subdomain #.tile.openstreetmap.org/#= zoom #/#= x #/#= y #.png";
-    public string Attribution { get; set; } = "&copy; <a href='https://osm.org/copyright'>OpenStreetMap contributors</a>";
+@code {
+    private readonly string[] LayerSubdomains = new string[] { "a", "b", "c" };
+    private const string LayerAttribution = "&copy; <a href='https://osm.org/copyright'>OpenStreetMap contributors</a>";
 }
 ````
 
-## Parameters
+## Map Parameters
 
 The Blazor Map provides various parameters that allow you to configure the component:
 
+@[template](/_contentTemplates/common/parameters-table-styles.md#table-layout)
+
 | Parameter | Type | Description |
-| ----------- | ----------- | ----------- |
+| --- | --- | --- |
 | `Center` | `double[]` | The map center. Coordinates are listed as [Latitude, Longitude]. |
 | `MinZoom` | `double` | The minimum zoom level. Typical web maps use zoom levels from 0 (the whole world) to 19 (sub-meter features). |
 | `MaxZoom` | `double` | The maximum zoom level. Typical web maps use zoom levels from 0 (the whole world) to 19 (sub-meter features). |
@@ -135,27 +121,64 @@ The Blazor Map provides various parameters that allow you to configure the compo
 The following `MapControlsAttribution` parameters enable you to customize the appearance of the Blazor Map Controls:
 
 | Parameter | Type | Description |
-| ----------- | ----------- | ----------- |
+| --- | --- | --- |
 | `Position` | `MapControlsPosition (enum)` | Specifies the position of the attribtion control. |
 
 The following `MapControlsNavigator` parameters enable you to customize the appearance of the Blazor Map Controls:
 
 | Parameter | Type | Description |
-| ----------- | ----------- | ----------- |
+| --- | --- | --- |
 | `Position` | `MapControlsPosition (enum)` | Specifies the position of the navigation control. |
 
 The following `MapControlsZoom` parameters enable you to customize the appearance of the Blazor Map Controls:
 
 | Parameter | Type | Description |
-| ----------- | ----------- | ----------- |
+| --- | --- | --- |
 | `Position` | `string` | Specifies the position of the zoom control. |
 
-## Next Steps
+## Map Reference and Methods
+
+The Map exposes a `Refresh` method. Use it to redraw the component after making programmatic changes that do not apply automatically.
+
+>caption Get the Map reference and use its methods
 
-[Configure the Tile Layer]({%slug components/map/layers/tile%})
+````CSHTML
+<TelerikButton OnClick="@ChangeMapZoom">Change Map Zoom</TelerikButton>
+
+<TelerikMap @ref="MapRef"
+            Zoom="@MapZoom">
+    <MapLayers>
+        <MapLayer Type="@MapLayersType.Tile"
+                  Attribution="@LayerAttribution"
+                  Subdomains="@LayerSubdomains"
+                  UrlTemplate="@LayerUrlTemplate">
+        </MapLayer>
+    </MapLayers>
+</TelerikMap>
+
+@code {
+    private TelerikMap? MapRef { get; set; }
+
+    private double MapZoom { get; set; } = 4;
+
+    private readonly string[] LayerSubdomains = new string[] { "a", "b", "c" };
+    private const string LayerUrlTemplate = "https://#= subdomain #.tile.openstreetmap.org/#= zoom #/#= x #/#= y #.png";
+    private const string LayerAttribution = "&copy; <a href='https://osm.org/copyright'>OpenStreetMap contributors</a>";
+
+    private void ChangeMapZoom()
+    {
+        MapZoom = 1;
+
+        MapRef?.Refresh();
+    }
+}
+````
+
+## Next Steps
 
-[Using the Map Events]({%slug components/map/events%})
+* [Configure Map Layers]({%slug components/map/layers%})
+* [Handle Map Events]({%slug components/map/events%})
 
 ## See Also
 
-  * [Live Demo: Map](https://demos.telerik.com/blazor-ui/map/overview)
+* [Live Demo: Map](https://demos.telerik.com/blazor-ui/map/overview)