š 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
- Overview & Purpose
- Key Functional Areas
- Dependencies & Technologies
- Data Models & ViewModels
- API Endpoints Overview
- JavaScript Helper Methods & Utilities
- Error Handling & Alerts
- ThirdāParty Integrations
- Sample Code Blocks
- Usage Examples
- UML Sequence Diagram
- 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 analert("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
- Add the View
- Place
FieldOfficeMap.cshtmlunderViews/JDE/. - In
JDEController, add an action:public IActionResult FieldOfficeMap() { return View(); }
- Place
- Ensure API Exists
- Implement
LocationController.GetFieldLocations()returningIEnumerable<FieldOfficeDto>.
- Implement
- Bing Maps Key
- Replace
<YOUR_BING_KEY>in the bottom script loader.
- Replace
- 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.
- Launch your app and browse to
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!