šŸ“„ FieldOfficeMap.cshtml Documentation

Welcome to the FieldOfficeMap.cshtml documentation! This view renders an interactive map of field offices, leverages Bing Maps, Syncfusion EJ2 controls, and integrates with backend APIs to display real‑time location data, search suggestions, traffic, routing, and more.


šŸ“‘ Table of Contents

  1. Overview & Purpose
  2. Key Functional Areas
  3. Dependencies & Technologies
  4. Data Models & ViewModels
  5. API Endpoints Overview
  6. JavaScript Helper Methods & Utilities
  7. Error Handling & Alerts
  8. Third‑Party Integrations
  9. Sample Code Blocks
  10. Usage Examples
  11. UML Sequence Diagram
  12. Conclusion

1. Overview & Purpose

šŸ—ŗļø FieldOfficeMap.cshtml is an ASP.NET MVC Razor View that:

  • Initializes a Bing Maps instance with multiple map types (road, aerial, birdseye, etc.).
  • Fetches Field Office location data from a backend API (/Location/GetFieldLocations).
  • Plots Pushpins šŸ“ for each field office and shows a custom Infobox on click.
  • Enables Autosuggest šŸ” (business suggestions) via Bing’s AutoSuggestManager.
  • Provides traffic layer, continuous geolocation tracking, and optional (commented out) routing.
  • Integrates Syncfusion EJ2 TextBox for search input, jQuery DataTables, and Bootstrap modals for additional UI interactions.

Intended Use:
This view allows operations, management, or executive teams to visually explore field office distribution, click on offices for details, search new locations, and track user/device location in real‑time.


2. Key Functional Areas

Area Description
Map Initialization GetMap() loads Bing Maps script, sets API key, and configures the map with default type & zoom.
Data Fetching fetch('/Location/GetFieldLocations') retrieves JSON array of offices, converts to Microsoft.Maps.Location.
Pushpin & Infobox Logic Creates pushpins for each office; showInfobox(pin, data) shows a styled HTML infobox with office details.
Search & Autosuggest Uses Microsoft.Maps.AutosuggestManager attached to Syncfusion <ejs-textbox> for business suggestions.
Traffic & Routing Loads Bing Modules: Traffic, SpatialDataService, SpatialMath. TrafficManager shows live traffic.
Geolocation Tracking startTracking() & stopTracking() watch user location and update a dedicated pushpin.
Map Events Mousewheel zoom switching (aerial ↔ birdseye), view change end, click events for customized behaviors.
Modal & DataTables jQuery + DataTables for table exports (CSV/Excel/PDF); Bootstrap modal to show image/document details.

3. Dependencies & Technologies

Technology / Library Source Purpose
ASP.NET Core MVC Razor Views Microsoft.AspNetCore.Mvc.Razor Server‑side view rendering
Bing Maps V8 API https://www.bing.com/api/maps/mapcontrol Interactive map, pushpins, routes, traffic
Syncfusion EJ2 JavaScript Syncfusion.JavaScript, ejs-textbox Rich UI controls (TextBox)
jQuery code.jquery.com/jquery-3.6.0.js DOM manipulation, AJAX
DataTables & Extensions cdn.datatables.net Table features & export buttons
Bootstrap ~/libs/bootstrap/js/bootstrap.bundle.min.js Modal dialogs, responsive layout
MetisMenu, SimpleBar, Node-Waves ~/libs/metismenu/..., ~/libs/simplebar/... Sidebar menus, custom scrollbars, effects
HTML5 Geolocation API navigator.geolocation Continuous user/device tracking

4. Data Models & ViewModels

Although this is a View, it expects the following JSON model from /Location/GetFieldLocations:

Property Type Description
FieldOfficeId int Unique identifier of the office
FieldOffice string Name of the field office
Latitude double GPS latitude
Longitude double GPS longitude
MailingAddress string Office mailing address
Manager string Manager’s name
Superintendent string Superintendent’s name
ProjectManager string Project Manager’s name
Lead string Lead person
JobCount int # open jobs
WOCount int # work orders
EmployeeCount int # employees
AssetsCount int # IT assets
EquipmentCount int # equipment
POCount int # purchase orders

Note: The view also references AJAX endpoints for modals:

  • /JDE/Details/{FieldOfficeId} (link in infobox)
  • /Imaging/ViewBlob/{DocumentImageId} & /LegalImaging/myModalProperties (for document images)

5. API Endpoints Overview

Endpoint Method Description
/Location/GetFieldLocations GET Returns JSON array of field offices (see model).
/JDE/Details/{id} GET Renders detail page for a specific field office.
/Imaging/ViewBlob/{DocumentImageId} GET Streams an image file in a new window/tab.
/LegalImaging/myModalProperties GET Returns HTML partial to populate Bootstrap modal.

6. JavaScript Helper Methods & Utilities

Below is a summary of the main JS functions:

Function Purpose
GetMap() Entry point. Dynamically loads Bing Maps script, sets credentials, configures map & modules.
showInfobox(pin, data) Builds custom HTML infobox with office details; re-centers map if infobox overflows viewport.
startTracking() Adds a hidden user pushpin; begins geolocation watchPosition.
stopTracking() Clears geolocation watch; removes pushpin via removePinById().
removePinById(id) Utility to remove pushpins by metadata identifier.
suggestionSelected(result) Clears previous pins; adds new pin for search suggestion; fits map to suggestion’s bestView.
switchToBirdseye() Checks if birdseye imagery is available at current center & heading; switches if available.
highlight(id, event) Highlights a debug DIV for 1s on map events (drag start/end, click).
mapClicked(e) (Commented) Example to add a new pushpin on map click & show an input form.
directionsUpdated(e) (Commented) Performs a spatial data service query for ā€œnear routeā€ data.
getRouteMode(req), getRouteOptimization(req) Helpers to map Bing Directions options to SDS query parameters.

7. Error Handling & Alerts

  • Fetch errors are not explicitly caught; browser console logs may appear if network fails.
  • directionsUpdated: alerts user if no route or unsupported transit mode.
  • jQuery AJAX for modal content provides an .error() callback with an alert("Dynamic content load failed.").
  • Autocomplete: if network or suggestions fail, no fallback – may require additional .catch.

8. Third‑Party Integrations

  • Bing Maps V8: Map, Pushpins, Infobox, AutoSuggestManager, TrafficManager, SpatialDataService, SpatialMath.
  • Syncfusion EJ2: <ejs-textbox> for a rich search box with style and persistence control.
  • jQuery & DataTables: Advanced table export (CSV/Excel/PDF) and search features – though the main view code references a #TreeGrid.
  • Bootstrap Modal: For dynamic image/document details.

9. Sample Code Blocks

9.1 Map Initialization & Data Fetching

function GetMap() {
  // Initialize the Bing map
  map = new Microsoft.Maps.Map('#myMap', {
    credentials: '<YOUR_BING_KEY>',
    mapTypeId: Microsoft.Maps.MapTypeId.aerial
  });

  // Create infobox (hidden)
  infobox = new Microsoft.Maps.Infobox(map.getCenter(), { visible: false });
  infobox.setMap(map);

  // Fetch field office locations
  fetch('/Location/GetFieldLocations')
    .then(res => res.json())
    .then(locations => {
      // Plot pushpins
      locations.forEach(loc => {
        const position = new Microsoft.Maps.Location(loc.Latitude, loc.Longitude);
        const pin = new Microsoft.Maps.Pushpin(position);
        Microsoft.Maps.Events.addHandler(pin, 'click', () => showInfobox(pin, loc));
        map.entities.push(pin);
      });
      // Fit map bounds
      const bounds = Microsoft.Maps.LocationRect.fromLocations(
        locations.map(l => new Microsoft.Maps.Location(l.Latitude, l.Longitude))
      );
      map.setView({ bounds });
    });
}

9.2 Custom Infobox

function showInfobox(pin, data) {
  const html = `
    <div style="padding:10px; background:#f5f5f5; border:1px solid #ccc;">
      <strong>${data.FieldOffice}</strong><br/>
      <strong>Manager:</strong> ${data.Manager}<br/>
      ...
      <a href="/JDE/Details/${data.FieldOfficeId}" target="_blank">
         View Field Office Details
      </a>
    </div>`;
  
  infobox.setOptions({
    location: pin.getLocation(),
    htmlContent: html,
    visible: true
  });
}

10. Usage Examples

  1. Add the View
    • Place FieldOfficeMap.cshtml under Views/JDE/.
    • In JDEController, add an action:
      public IActionResult FieldOfficeMap() {
        return View();
      }
      
  2. Ensure API Exists
    • Implement LocationController.GetFieldLocations() returning IEnumerable<FieldOfficeDto>.
  3. Bing Maps Key
    • Replace <YOUR_BING_KEY> in the bottom script loader.
  4. Run & Navigate
    • Launch your app and browse to /JDE/FieldOfficeMap.
    • Use the Search box to find new locations.
    • Click šŸ“ Start Continuous Tracking to begin geolocation updates.

11. UML Sequence Diagram

@startuml
actor User
participant "FieldOfficeMap.cshtml" as View
participant "Bing Maps API" as Bing
participant "Location API" as API

User -> View : Navigate to /JDE/FieldOfficeMap
View -> Bing : Load map control
View -> API : GET /Location/GetFieldLocations
API --> View : JSON [ {Latitude,Longitude,...}, ... ]
loop For each location
  View -> Bing : Create Pushpin(latitude, longitude)
  Bing -> View : Pushpin instance
end
User -> View : Click Pushpin
View -> Bing : showInfobox(pin,data)
@enduml

12. Conclusion

šŸŽ‰ FieldOfficeMap.cshtml is a comprehensive, interactive map view showcasing field office data with rich features: live traffic, autosuggestions, geolocation tracking, and dynamic infobox details. By leveraging Bing Maps, Syncfusion EJ2, and standard web technologies, it delivers a user‑friendly dashboard for operational insights.

Feel free to extend this view further with custom routing, advanced error handling, server‑side caching of locations, or real‑time signal‑R updates for office status!


End of Documentation
šŸš€ Happy Mapping!