Documentation: SidebarTreeMap Component (English)
1. Overview
SidebarTreeMap is a high-level layout component that combines a hierarchical tree-based sidebar with the powerful MejikDataMap controller. It is the ultimate tool for creating applications that require visual filtering of searchable and paginated geospatial data.
This component operates on an “inversion of control” pattern. Its primary role is to aggregate parameters from all user interactions (tree selection, map movement, search, pagination) and pass them to a parent-provided loader function, which is responsible for the actual data fetching.
2. Features
- Geospatial Filtering: The map view is dynamically updated based on the selected node in the sidebar tree.
- Parent-Controlled Data Loading: Provides maximum flexibility by letting the parent component handle the API calls via a
loaderfunction prop. - State Aggregation: Combines filter state from the tree, viewport state (bounding box, zoom) from the map, and UI state (search, pagination) from
MejikDataMapbefore calling the loader. - Full Pass-Through Functionality: All unrecognized props (like
selectionMode,visibleLayers) and events (like@more-info-click) are passed directly toMejikDataMap, allowing full customization of the map’s features from the parent page. - CRUD Events: Emits events for tree management, allowing the parent to handle create, edit, and delete logic.
3. Props
| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
nodesUrl | String | Yes | - | The API endpoint (POST) for fetching the tree structure data for the sidebar. |
sidebarTitle | String | No | 'Layers' | The title displayed at the top of the sidebar. |
treeServerSearch | Bool | No | false | If true, the search term is sent to nodesUrl for server-side searching. |
contentTitle | String | No | 'Map for' | The prefix for the main content area’s title (e.g., “Map for [Node Name]”). |
filterKey | String | No | 'categoryId' | The query parameter key to use when filtering by the selected node’s ID. |
loader | Function | Yes | - | A function in the parent that fetches map data. It receives an object with all map and filter parameters. |
geoJsonFeatures | Array | No | [] | An array of GeoJSON features to display on the map, provided by the parent via the loader. |
totalRows | Number | No | 0 | The total number of features available on the server, used for pagination. |
isLoading | Boolean | No | false | A boolean to show/hide the map’s loading overlay. Passed from the parent. |
4. Pass-Through Props & Events
This component acts as a transparent proxy toMejikDataMap. Any prop not listed above will be passed directly down. This means you can control all of LeafletMap’s features from here.
Examples of Pass-Through Props:
:selection-mode="'multi'":visible-layers="['live-position']":selected-features.sync="mySelectionArray":center="[newLat, newLng]"
MejikDataMap and LeafletMap (e.g., @feature-click, @more-info-click) are automatically passed up to the parent.
5. The loader Function Contract
The parent component must provide a loader function. This function is called whenever the data needs to be refreshed. It receives one argument: a params object with all aggregated parameters:
6. Emitted Events (Originating from SidebarTreeMap)
| Event | Payload | Description |
|---|---|---|
@node-selected | (nodeObject) | Fired when a user selects a node in the sidebar tree. |
@add-node | { parentId, parentNode } | Fired to signal the parent to open a form for creating a new tree node. |
@edit-node | (nodeObject) | Fired when the user clicks the “edit” icon on a tree node. |
@delete-node | (nodeObject) | Fired after confirmation when the user clicks the “delete” icon. |
@tree-fetch-error | (errorObject) | Fired if fetching the tree data from nodesUrl fails. |
7. Usage Example
Dokumentasi: Komponen SidebarTreeMap (Bahasa Indonesia)
1. Gambaran Umum
SidebarTreeMap adalah komponen tata letak tingkat tinggi yang menggabungkan sidebar berbasis pohon hierarkis dengan pengontrol MejikDataMap yang kuat. Ini adalah alat utama untuk membuat aplikasi yang memerlukan pemfilteran visual dari data geospasial yang dapat dicari dan dipaginasi.
Komponen ini beroperasi dengan pola “inversion of control”. Peran utamanya adalah untuk menggabungkan parameter dari semua interaksi pengguna (pemilihan pohon, pergerakan peta, pencarian, paginasi) dan meneruskannya ke fungsi loader yang disediakan oleh induk, yang bertanggung jawab untuk pengambilan data yang sebenarnya.
2. Fitur
- Filter Geospasial: Tampilan peta diperbarui secara dinamis berdasarkan node yang dipilih di sidebar.
- Pemuatan Data Dikontrol Induk: Memberikan fleksibilitas maksimum dengan membiarkan komponen induk menangani panggilan API melalui prop fungsi
loader. - Agregasi State: Menggabungkan state filter dari pohon, state viewport (bounding box, zoom) dari peta, dan state UI (pencarian, paginasi) dari
MejikDataMapsebelum memanggil loader. - Fungsionalitas Penerusan Penuh (Pass-Through): Semua props (seperti
selectionMode,visibleLayers) dan event (seperti@more-info-click) yang tidak dikenali diteruskan langsung keMejikDataMap, memungkinkan kustomisasi penuh fitur peta dari halaman induk. - Event CRUD: Memancarkan event untuk manajemen pohon, memungkinkan induk menangani logika buat, edit, dan hapus.
3. Props
| Prop | Tipe | Wajib | Default | Deskripsi |
|---|---|---|---|---|
nodesUrl | String | Ya | - | Endpoint API (POST) untuk mengambil data struktur pohon untuk sidebar. |
sidebarTitle | String | Tidak | 'Layers' | Judul yang ditampilkan di bagian atas sidebar. |
treeServerSearch | Bool | Tidak | false | Jika true, istilah pencarian dikirim ke nodesUrl untuk pencarian di sisi server. |
contentTitle | String | Tidak | 'Map for' | Awalan untuk judul area konten utama (misalnya, “Peta untuk [Nama Node]”). |
filterKey | String | Tidak | 'categoryId' | Kunci parameter query yang akan digunakan saat memfilter berdasarkan ID node yang dipilih. |
loader | Function | Ya | - | Sebuah fungsi di induk yang mengambil data peta. Fungsi ini menerima objek dengan semua parameter peta dan filter. |
geoJsonFeatures | Array | Tidak | [] | Array fitur GeoJSON untuk ditampilkan di peta, disediakan oleh induk melalui loader. |
totalRows | Number | Tidak | 0 | Jumlah total fitur yang tersedia di server, digunakan untuk paginasi. |
isLoading | Boolean | Tidak | false | Boolean untuk menampilkan/menyembunyikan overlay loading peta. Diteruskan dari induk. |
4. Props & Event Penerus (Pass-Through)
Komponen ini bertindak sebagai perantara transparan keMejikDataMap. Setiap prop yang tidak tercantum di atas akan diteruskan langsung ke bawah. Ini berarti Anda dapat mengontrol semua fitur LeafletMap dari sini.
Contoh Props Penerus:
:selection-mode="'multi'":visible-layers="['live-position']":selected-features.sync="arraySeleksiSaya":center="[latBaru, lngBaru]"
MejikDataMap dan LeafletMap (misalnya, @feature-click, @more-info-click) secara otomatis diteruskan ke atas ke induk.
5. Kontrak Fungsi loader
Komponen induk wajib menyediakan fungsi loader. Fungsi ini dipanggil setiap kali data perlu diperbarui. Ia menerima satu argumen: objek params dengan semua parameter yang digabungkan:
6. Event yang Di-emit (Berasal dari SidebarTreeMap)
| Event | Payload | Deskripsi |
|---|---|---|
@node-selected | (nodeObject) | Dipicu saat pengguna memilih sebuah node di sidebar. |
@add-node | { parentId, parentNode } | Dipicu untuk memberi sinyal ke induk agar membuka form untuk membuat node baru. |
@edit-node | (nodeObject) | Dipicu saat pengguna mengklik ikon “edit” pada sebuah node. |
@delete-node | (nodeObject) | Dipicu setelah konfirmasi saat pengguna mengklik ikon “hapus”. |
@tree-fetch-error | (errorObject) | Dipicu jika pengambilan data pohon dari nodesUrl gagal. |
