QuerySimple & HelperSimple Widgets

MapSimple Suite: High-Performance Search & Analysis for ArcGIS Experience Builder

Version: 1.19.0-r021.50
Compatibility: ArcGIS Experience Builder Developer Edition 1.19.0+
Author: Adam Cabrera

Try It Live

View Live Demo

Experience the QuerySimple widget in action with real parcel data, map highlighting, and full search functionality.

1. Major Features: Advanced Functionality for Enterprise Portals

Hierarchical Query Grouping (The Two-Dropdown UI)

To eliminate “List Fatigue” in complex applications with dozens of search requirements, MapSimple utilizes a specialized Two-Dropdown Architecture:

Logical Organization: Architects can group related queries into clusters such as “Property Info,” “Zoning,” or “Environmental Data.” This allows a single widget instance to house 30+ searches without overwhelming the user.
Conditional UI Rendering: The secondary query dropdown only renders once a primary category is selected, preserving vertical screen real estate.
Granular Control: Every query is configured with a groupId for clustering, a searchAlias for user-friendly labeling, and a numeric order for precise display priority.

Streamlined Deep-Linking (Simplifying URL Parameters)

Standard Experience Builder URL parameters provide great flexibility, but managing them for high-volume public portals can be complex. HelperSimple provides a clean abstraction layer:

Friendly URLs: Maps technical database fields (e.g., PROP_KEY_NUM) to user-friendly “ShortIds” (e.g., pin).
Reactive Hash (#) Handling: By utilizing the Hash fragment, the widget enables snappy updates that do not trigger a full page reload. It detects the hashchange event and executes searches instantly.
Deep Link Discovery: An info button (ℹ️) appears next to layer titles to show users exactly how to format a deep link for that specific layer.

The Duplicate Button (80% Less Setup Time)

Migrating large Web AppBuilder applications often requires manually re-creating dozens of similar queries.

Instant Cloning: Configure one query completely—including filters, display formats, and spatial tools—and click the Duplicate (📋) button.
Smart Offsets: Clones are created with all settings preserved, including hash parameters which are auto-suffixed to prevent collisions.

2. Spatial Precision & UX Refinement

Streamlined Input: “Enter” to Execute & Smart Validation

We have prioritized keyboard-first navigation to match modern web expectations:

Execute on Enter: Typing in a search field and hitting the “Enter” key now triggers the query execution immediately, removing the friction of a manual click.
Input-Driven Validation: The “Apply” button remains hidden until a valid value is entered in the textbox. This prevents accidental “Select All” queries that could hang the browser or flood the server.

Dynamic Zoom Control (User-Overridable Auto-Zoom)

While architects can set a default “Zoom to Results” behavior in the configuration, this is exposed as a toggleable checkbox for the end-user.

Workflow Flexibility: If a user is performing rapid-fire data entry (entering multiple PINs sequentially), they may not want the map jumping and re-centering with every result. This allows the user to suppress map movement for data-heavy tasks.

High-Volume Result Loading

Unlike standard widgets that rely on lazy-loading or “Load More” buttons, MapSimple delivers the entire results list at once.

Engine Viability: Because of the SQL optimizations and memory stripping, the query engine can handle large payloads without the traditional overhead, allowing for a seamless “spreadsheet-like” browsing experience.

Graphics Layer Advantage: Zoom & Identify

Decoupling results from operational map layers provides a significant workflow improvement:

Identify with Layers Off: Because results render on a graphics layer, clicking a result will Zoom and Identify even if the source operational layer is hidden in the Layer List.
Zero TOC Clutter: No temporary “result layers” are created in the map’s Table of Contents.

Label Point Centering (Irregular Polygon Logic)

Standard zooming often relies on the geometric centroid, which can place the map center and popup outside of the feature for irregular, L-shaped, or “U-shaped” polygons.

The Refinement: MapSimple utilizes the Label Point (Point on Surface) for centering and popup placement. This ensures that the map focus always lands within the actual boundaries of the feature.

3. Performance Architecture

Universal SQL Optimizer (93.4% Latency Reduction)

Standard implementations often use LOWER(FIELD) for case-insensitivity, which prevents the database from using its attribute indexes, forcing a “Full Table Scan.”

The Fix: MapSimple “unwraps” the query and performs client-side normalization to uppercase.
The Result: On a layer with 2M+ records, search times dropped from 21.1s to 1.4s.

The Hook and Shell Pattern

The suite follows a strict separation of concerns to ensure enterprise-grade stability:

The Shell (UI Orchestration): The widget.tsx acts as a thin “Shell” for the interface, responsible only for UI coordination.
The Hooks (Functional Managers): Logic is housed in specialized Manager classes:
- UrlConsumptionManager: Handles deep link parsing and ShortId mapping.
- AccumulatedRecordsManager: Manages the complex New/Add/Remove logic.
- GraphicsLayerManager: Directs map highlighting and Identify popup tracking.
Stability Wins: This decoupling prevents state management issues and ensures a clean unmount cycle via a Headless Yield pattern.

The 93% Memory Floor

We optimized the architecture to prevent “heap bloat” during large searches.

The Fix: The zoom logic surgically extracts only the extent bounds (xmin, xmax, ymin, ymax) and discards heavy geometry objects immediately.
The Result: Memory retention per query dropped from 11.21 MB to 1.76 MB.

4. Developer Diagnostics: The “Glass Box” Suite

The suite features production-safe logging controlled via the URL. Append ?debug=all or specific flags (e.g., HASH, TASK, RESULTS-MODE) to your URL to see real-time telemetry in the console.