syncfusion-aspnetmvc-maps

# Implementing Syncfusion Maps for ASP.NET MVC The Syncfusion Maps component is a powerful data visualization control for rendering geographical data using Scalable Vector Graphics (SVG). It supports GeoJSON shapes, multiple layers, map providers (Bing, Azure, OpenStreetMap), and rich interactive features including zooming, panning, tooltips, markers, bubbles, and data-driven color mapping. ## When to Use This Skill Use the Syncfusion Maps component when you need to: - **Visualize geographical data** - Display country, state, or regional data on interactive maps - **Create choropleth maps** - Show data distribution using color mapping across geographical regions - **Plot location markers** - Display points of interest, offices, stores, or custom locations with markers - **Render bubble maps** - Visualize quantitative data with size-based bubbles on geographical locations - **Integrate map providers** - Use Bing Maps, Azure Maps, or OpenStreetMap as base layers - **Show custom shapes** - Render custom GeoJSON shapes for specific regions or areas - **Build interactive dashboards** - Create zoomable, pannable maps with tooltips and selection - **Display navigation routes** - Show navigation lines connecting different locations - **Overlay annotations** - Add custom HTML/text annotations on maps at specific coordinates - **Create multi-layer visualizations** - Combine multiple data layers on a single map - **Bind shape data** - Connect database or JSON data to geographical shapes - **Export maps** - Generate PNG, JPEG, SVG, or PDF exports of maps ## Component Overview **Component:** Maps **Helper:** `@Html.EJS().Maps("containerId")` **Package:** Syncfusion.EJ2.MVC5 **Namespace:** Syncfusion.EJ2.Maps **Key Capabilities:** - 📍 **Multiple Layers** - Unlimited layers and sublayers with independent configuration - 🗺️ **GeoJSON Support** - Load and render custom geographical shapes - 🌐 **Map Providers** - Integration with Bing Maps, Azure Maps, and OpenStreetMap - 🎨 **Color Mapping** - Equal, range, and desaturation color schemes for data visualization - 📌 **Markers** - Plot locations with Circle, Image, Letter, or custom HTML templates - 🫧 **Bubbles** - Size-based bubble visualization for quantitative data - 🏷️ **Data Labels** - Display shape names and data values with smart positioning - 🎯 **Interactivity** - Zoom, pan, tooltip, selection, and highlight features - 📊 **Legend** - Default and interactive legends for color mapping, markers, and bubbles - ✏️ **Annotations** - Custom HTML overlays at specific coordinates - 🌍 **Projections** - Support for 6 map projection types (Mercator, Equirectangular, etc.) - 🔗 **Navigation Lines** - Connect locations with styled lines - 🎭 **Polygons** - Draw custom polygons on maps - 🖨️ **Export** - Print and export to PNG, JPEG, SVG, PDF formats - 🌐 **Globalization** - Internationalization (i18n) and localization (l10n) support - ♿ **Accessibility** - WCAG 2.2 AA compliant with keyboard navigation and screen reader support ## Documentation and Navigation Guide ### Getting Started and Installation 📄 **Read:** [references/getting-started.md](references/getting-started.md) **When to read this reference:** - Setting up the Maps component for the first time - Installing Syncfusion.EJ2.MVC5 NuGet package - Configuring project dependencies and namespaces - Adding script references and ScriptManager - Creating your first map with GeoJSON data - Understanding controller setup and ViewBag data binding - Loading GeoJSON files from App_Data folder - Basic map rendering and configuration **What you'll learn:** - Complete prerequisites and system requirements - Step-by-step NuGet package installation - Web.config namespace configuration - CDN and local script reference options - ScriptManager registration in layout - Loading and deserializing GeoJSON files - Controller action setup for map data - Basic Html.EJS().Maps() implementation - Theme integration --- ### Layers and Data Binding 📄 **Read:** [references/layers-and-data.md](references/layers-and-data.md) **When to read this reference:** - Understanding map layer architecture - Working with GeoJSON format and structure - Adding main layers and sublayers to maps - Creating multi-layer visualizations - Loading GeoJSON from files or URLs - Binding data sources to map shapes - Configuring ShapeDataPath and ShapePropertyPath - Matching data records to geographical shapes - Implementing drill-down functionality with BaseLayerIndex - Populating shape data from databases or APIs - Dynamic data updates and transformations - Layer visibility and ordering control **What you'll learn:** - Complete layer system architecture - GeoJSON format specifications - Main layer vs sublayer configuration - Multiple layer support and management - Data source binding techniques - Shape property mapping - Controller data preparation - ViewBag data passing patterns - Layer-specific settings and customization --- ### Markers and Bubbles 📄 **Read:** [references/markers-and-bubbles.md](references/markers-and-bubbles.md) **When to read this reference:** - Adding location markers to maps - Using different marker types (Circle, Image, Letter, Template) - Customizing marker appearance (size, color, borders) - Positioning markers using latitude and longitude - Adding marker tooltips and handling marker events - Creating custom marker templates with Razor - Implementing marker clustering - Adding bubble visualizations to show quantitative data - Sizing bubbles based on data values - Configuring bubble colors, opacity, and styling - Working with multiple marker or bubble datasets - Combining markers and bubbles on same map **What you'll learn:** - Complete marker implementation guide - All marker types with examples - Marker positioning and coordinate systems - Marker data source configuration - Tooltip configuration for markers - Event handling (click, hover, selection) - Custom HTML marker templates - Bubble layer architecture - Bubble data binding - Size calculation and normalization - Multiple dataset management - Best practices for marker/bubble placement --- ### Data Visualization (Labels and Color Mapping) 📄 **Read:** [references/data-visualization.md](references/data-visualization.md) **When to read this reference:** - Enabling data labels on map shapes - Configuring label positioning (smart, auto, manual) - Creating custom label templates - Styling data labels (font, color, borders) - Handling label intersections and overlaps - Showing/hiding labels based on data conditions - Implementing color mapping for choropleth maps - Using equal color mapping for categorical data - Using range color mapping for numeric data - Using desaturation color mapping - Customizing color palettes and schemes - Binding data values to colors - Creating data-driven heat maps **What you'll learn:** - Complete data label system - Label positioning algorithms - Template-based label customization - Smart label placement - Intersection action strategies - All color mapping types explained - Equal vs range vs desaturation mapping - Color palette configuration - Data-to-color binding techniques - Best practices for readable visualizations --- ### Legend and Map Overlays 📄 **Read:** [references/legend-and-overlays.md](references/legend-and-overlays.md) **When to read this reference:** - Adding legends to maps - Configuring legend modes (Default, Interactive) - Positioning and aligning legends - Creating legends for color mapping - Creating legends for markers and bubbles - Customizing legend templates - Implementing interactive legend features - Adding annotations to maps - Positioning annotations at specific coordinates - Creating HTML annotation templates - Adding navigation lines between locations - Styling and animating navigation lines - Drawing polygons on maps - Configuring polygon data and styling - Highlighting map features **What you'll learn:** - Complete legend system (default and interactive modes) - Legend positioning and layout options - Legend for different visualization types - Custom legend item templates - Inverted pointer for interactive legends - Annotation system architecture - Annotation alignment and positioning - HTML template-based annotations - Navigation line implementation - Line styling and animation - Polygon drawing and configuration - Complete overlay management --- ### User Interactions 📄 **Read:** [references/user-interactions.md](references/user-interactions.md) **When to read this reference:** - Enabling zoom functionality (toolbar, pinch, mouse wheel, double-click) - Configuring pan/panning features - Setting zoom limits and constraints - Adding tooltips for shapes, markers, and bubbles - Implementing shape selection (single and multi-select) - Enabling highlight on hover - Handling map events (click, hover, zoom, pan, resize) - Customizing zoom toolbar buttons - Implementing keyboard navigation - Disabling specific interaction types - Configuring zoom factor and animation - Creating custom interaction behaviors **What you'll learn:** - Complete zooming system (all types) - Panning configuration - Zoom settings and properties - Tooltip system for all elements - Selection modes and configuration - Highlight settings - Event handling patterns - Zoom toolbar customization - Keyboard shortcuts and accessibility - Touch gesture support - Best practices for interactive maps --- ### Map Providers Integration 📄 **Read:** [references/map-providers.md](references/map-providers.md) **When to read this reference:** - Integrating Bing Maps as base layer - Integrating Azure Maps as base layer - Integrating OpenStreetMap (OSM) as base layer - Configuring tile layer settings - Setting up API keys for map providers - Using provider-specific map types (Road, Aerial, Hybrid) - Combining map providers with shape layers - Configuring tile URL patterns - Handling provider authentication - Working with provider-specific options - Optimizing tile loading and caching **What you'll learn:** - Complete map provider integration guide - Bing Maps setup and configuration - Azure Maps setup and configuration - OpenStreetMap implementation - API key registration and usage - Tile layer architecture - Layer type configuration (Geometry vs Tile) - URL pattern configuration - Provider authentication methods - Combining providers with GeoJSON layers - Performance optimization for tiles --- ### Customization and Advanced Features 📄 **Read:** [references/customization-and-advanced.md](references/customization-and-advanced.md) **When to read this reference:** - Setting map dimensions (width, height) - Adding map title and subtitle - Customizing map background and borders - Applying themes (Material, Bootstrap, Fabric, etc.) - Custom CSS styling for map elements - Implementing internationalization (i18n) - Implementing localization (l10n) for map text - Enabling RTL (right-to-left) support - Printing maps - Exporting maps to PNG, JPEG, SVG, or PDF formats - Configuring print and export settings - Ensuring WCAG 2.2 AA accessibility compliance - Implementing keyboard navigation - Adding screen reader support (ARIA attributes) - Configuring high contrast themes - Meeting Section 508 requirements **What you'll learn:** - Complete map customization options - Size and dimension configuration - Title and subtitle settings - Background and border styling - Theme system and CSS customization - Globalization support (i18n/l10n) - RTL implementation - Print functionality with settings - Export formats and configuration - Complete accessibility implementation - WCAG and Section 508 compliance - ARIA attributes and roles - Keyboard navigation patterns - Screen reader compatibility --- ### Maps API Reference 📄 **Read:** [references/maps-api-reference.md](references/maps-api-reference.md) **Complete Maps class API reference with 70+ properties:** - Container & display properties (Width, Height, Background, HtmlAttributes) - Positioning & layout properties (CenterPosition, Margin, MapsArea, TabIndex) - Styling & theme properties (Theme options - Material, Bootstrap, Fluent, Tailwind; Border configuration) - Data & layer properties (Layers collection, BaseLayerIndex for multi-layer drill-down, ProjectionType - Mercator, Equirectangular, Miller, etc.) - Legend & annotation properties (LegendSettings for visibility/positioning, Annotations for custom HTML overlays) - Zoom & pan properties (ZoomSettings for all zoom operations, TooltipDisplayMode gestures) - Selection & interaction properties (Description for accessibility, UseGroupingSeparator for numbers) - Export & print properties (AllowImageExport, AllowPdfExport, AllowPrint) - Localization & accessibility (Locale for i18n/l10n, EnableRtl for right-to-left languages, Format for internationalization) - All 30+ events organized by category (Lifecycle: Load, Loaded, Resize, AnimationComplete; Layer & Shape: LayerRendering, ShapeRendering, ShapeHighlight, ShapeSelected, DataLabelRendering; Marker & Bubble: MarkerClick, MarkerRendering, MarkerMouseMove, MarkerDragStart/End, MarkerClusterClick/MouseMove/Rendering, BubbleRendering, BubbleClick, BubbleMouseMove; Legend & Annotation: LegendRendering, AnnotationRendering; Mouse & Pointer: Click, DoubleClick, RightClick, MouseMove, ItemSelection, ItemHighlight; Zoom & Pan: Zoom, ZoomComplete, Pan, PanComplete; Tooltip & Print: TooltipRender, TooltipRenderComplete, BeforePrint) - 9 major enumerations (MapsTheme, ProjectionType, TooltipGesture, MarkerType, SelectionMode, LegendMode, LegendPosition, Type for layer types, BingMapType) - 15 related configuration classes (MapsLayer, MapsMarkerSettings, MapsBubbleSettings, MapsDataLabelSettings, MapsShapeSettings, MapsLegendSettings, MapsZoomSettings, MapsAnnotation, MapsColorMapping, MapsCenterPosition, MapsMargin, MapsBorder, MapsTitleSettings, MapsNavigationLineSettings, MapsMapsAreaSettings) - 6 common usage patterns with complete code examples (Choropleth map, Markers with tooltips, Multi-layer drill-down, Bing Maps provider, OpenStreetMap provider, Annotations) - Direct links to official Syncfusion API documentation for all properties and classes --- ## Quick Start Example Here's a minimal example to get started with the Maps component: **Controller (HomeController.cs):** ```csharp using System.Web.Mvc; using Newtonsoft.Json; public class HomeController : Controller { public ActionResult Index() { // Load GeoJSON data from App_Data folder ViewBag.MapData = GetWorldMap(); return View(); } public object GetWorldMap() { string jsonPath = Server.MapPath("~/App_Data/WorldMap.json"); string jsonContent = System.IO.File.ReadAllText(jsonPath); return JsonConvert.DeserializeObject(jsonContent, typeof(object)); } } ``` **View (Views/Home/Index.cshtml):** ```cshtml @using Syncfusion.EJ2 <div class="control-section"> <div style="width:100%; height:500px;"> @Html.EJS().Maps("container").Layers(layer => { layer.ShapeData(ViewBag.MapData).Add(); }).Render() </div> </div> ``` **Result:** A basic world map rendered with GeoJSON data. --- ## Common Patterns ### Pattern 1: Choropleth Map with Color Mapping **Controller:** ```csharp public ActionResult Index() { ViewBag.MapData = GetWorldMap(); ViewBag.PopulationData = new[] { new { Country = "United States", Population = 331 }, new { Country = "India", Population = 1380 }, new { Country = "China", Population = 1439 } }; return View(); } ``` **View:** ```cshtml @Html.EJS().Maps("container").Layers(layer => { layer.ShapeData(ViewBag.MapData) .ShapeDataPath("Country") .ShapePropertyPath(new[] { "name" }) .DataSource(ViewBag.PopulationData) .ShapeSettings(settings => settings .ColorValuePath("Population") .ColorMapping(cm => { cm.From(0).To(500).Color("#deebae").Add(); cm.From(500).To(1000).Color("#7bc1ce").Add(); cm.From(1000).To(1500).Color("#3a8fb7").Add(); }) ).Add(); }).Render() ``` ### Pattern 2: Adding Markers for Locations **Controller:** ```csharp public ActionResult Index() { ViewBag.MapData = GetWorldMap(); ViewBag.Markers = new[] { new { Latitude = 40.7128, Longitude = -74.0060, Name = "New York" }, new { Latitude = 51.5074, Longitude = -0.1278, Name = "London" }, new { Latitude = 35.6762, Longitude = 139.6503, Name = "Tokyo" } }; return View(); } ``` **View:** ```cshtml @Html.EJS().Maps("container").Layers(layer => { layer.ShapeData(ViewBag.MapData) .MarkerSettings(marker => { marker.Visible(true) .DataSource(ViewBag.Markers) .Shape(Syncfusion.EJ2.Maps.MarkerType.Circle) .Fill("#FF0000") .Height(10) .Width(10) .TooltipSettings(tooltip => tooltip.Visible(true).ValuePath("Name")) .Add(); }).Add(); }).Render() ``` ### Pattern 3: Interactive Map with Zoom and Selection ```cshtml @Html.EJS().Maps("container") .ZoomSettings(zoom => zoom .Enable(true)