Updated plugin development documentation

Author: soal

docs_source/plugin_components/plugin_components_development.md

@@ -121,4 +121,124 @@ Example below can give you an idea how to create component for Mapbox GL JS plug
 
 **[VueMaboxGeocoder](https://github.com/soal/vue-mapbox-geocoder) — wrapper for [mapbox-gl-geocoder](https://github.com/mapbox/mapbox-gl-geocoder)**:
 
+```js
+// First, there is no separate HTML to render, so we don't need template and SFC, so it's just JS file
+
+import MapboxGeocoder from "@mapbox/mapbox-gl-geocoder";
+import { $helpers } from "vue-mapbox"; // Get $helpers from VueMapbox
+
+// Define list of mapbox-gl-geocoder events
+const geocoderEvents = {
+  clear: "clear",
+  loading: "loading",
+  results: "results",
+  result: "result",
+  error: "error"
+};
+
+export default {
+  name: "GeocoderControl",
+  mixins: [$helpers.asControl], // MapboxGeocoder is a control, so we use mixin
+
+  inject: ["mapbox", "map"], // Here we inject objects provided by MglMap
+
+  props: {
+    // MapboxGeocoder requires access token
+    accessToken: {
+      type: String,
+      required: true
+    },
+    input: {
+      type: String,
+      default: null
+    },
+    proximity: {
+      type: Object,
+      default: null
+    }
+    // ...here goes other props...
+  },
+
+  data() {
+    return {
+      initial: true
+    };
+  },
+
+  // Here we watch for props and and apply changes to MapboxGeocoder if needed
+  watch: {
+    input: {
+      handler(next, prev) {
+        if (this.control && next !== prev) {
+          this.control.setInput(next);
+        }
+      },
+      immediate: true
+    },
+    proximity(next, prev) {
+      if (this.control && next !== prev) {
+        this.control.setProximity(next);
+      }
+    }
+  },
+
+  created() {
+    this.control = null; // Here we will store MapboxGeocoder instance. We don't want Vue reactivity system mess with it, so we store it non-reactive
+    if (this.accessToken && !this.mapbox.accessToken) {
+      this.mapbox.accessToken = this.accessToken;
+    }
+    this.control = new MapboxGeocoder(this.$props); // Creating MapboxGeocoder instance and pass props as options to it
+    this.control.on("results", this.$_updateInput); // We need to update synchronized prop "input" when user enters some query to search field
+
+    // Now we can add control to the map
+    this.$_deferredMount();
+  },
+
+  beforeDestroy() {
+    this.control.off("results", this.$_updateInput);
+    // Also, control will be removed from map in beforeDestroy() lifecycle hook in `asControl` mixin
+  },
+
+  methods: {
+    $_deferredMount() {
+      // Because this component placed in MglMap sub-tree, map already initialized and injected above
+      this.map.addControl(this.control);
+      if (this.input) {
+        // Set input in MapboxGeocoder if there is default data
+        this.control.setInput(this.input);
+      }
+      // Emit added event. `$_emitEvent` method is came from `asControl` mixin
+      this.$_emitEvent("added", { geocoder: this.control });
+      this.$_bindSelfEvents(Object.keys(geocoderEvents)); // Bin events to emit them as Vue events
+      this.initial = false; // Initialization done
+    },
+
+    $_bindSelfEvents(events) {
+      // $_bindSelfEvents is provided by `asControl` mixin. but we need to replace it because MapboxGeocoder do not follow Mapbox Gl JS events schema and we need custom processing for them
+      const vm = this;
+      // Here we use this.$listeners to subscribe only on events that user listens on component
+      Object.keys(this.$listeners).forEach(eventName => {
+        if (events.includes(eventName)) {
+          this.control.on(eventName, vm.$_emitControlEvent.bind(vm, eventName));
+        }
+      });
+    },
+
+    // Process event to line up with VueMapbox events format
+    $_emitControlEvent(eventName, eventData) {
+      return this.$_emitSelfEvent({ type: eventName }, eventData);
+    },
+
+    $_updateInput(results) {
+      if (!this.initial) {
+        const input = results.query ? results.query.join("") : "";
+        this.$emit("update:input", input); // update synchormized prop "input"
+      }
+    }
+
+    //...here goes other public methods
+  }
+};
+```
+
 <!-- ## Component API recommendations -->