Comments and mockups

docs/examples/01. Decomposing UI Components/samples/01.js

@@ -1,3 +1,9 @@
+/**
+ * @fileoverview
+ * In this example, we replace the standard offer list
+ * with an alternative implementation that shows offers
+ * as markers on a map
+ */
 const {
   SearchBox,
   SearchBoxComposer,
@@ -6,6 +12,12 @@ const {
   util
 } = ourCoffeeSdk;
 
+/**
+ * A custom offer list component that
+ * renders data on the map instead of a static
+ * list. This class implements the `IOfferListComponent`
+ * interface from scratch.
+ */
 class CustomOfferList {
   constructor(context, container, offerList) {
     this.context = context;
@@ -14,11 +26,21 @@ class CustomOfferList {
     this.offerList = null;
     this.map = null;
 
+    /**
+     * We listen to the map events (marker selection)
+     * and translate it as an offer selection event.
+     * This is the requirement from the `IOfferListComponent`
+     * interface
+     */
     this.onMarkerClick = (markerId) => {
       this.events.emit("offerSelect", {
         offerId: markerId
       });
     };
+    /**
+     * We are free to implement the business logic in
+     * any that suits our needs
+     */
     this.setOfferList = ({ offerList: newOfferList }) => {
       if (this.map) {
         this.map.destroy();
@@ -26,6 +48,9 @@ class CustomOfferList {
       }
       this.offerList = newOfferList;
       if (newOfferList) {
+        // We're displaying data on a map (a dummy one),
+        // using the additional data we pass through the
+        // customized composer (see below)
         this.map = new DummyMapApi(this.container, [
           [16.355, 48.2],
           [16.375, 48.214]
@@ -46,6 +71,21 @@ class CustomOfferList {
         "offerPreviewListChange",
         this.setOfferList
       ),
+      // We listen to the
+      // 'offerFullViewToggle' event on
+      // the parent composer context
+      // to select or deselect the corresponding
+      // marker.
+      //
+      // Note the important pattern:
+      // when the marker is clicked, we DO NOT
+      // mark it as selected, but only emit an
+      // event. This is because the offer list
+      // does not own the logic of selecting
+      // offers.
+      // It is the composer's responsibility
+      // to decide, whether this event should
+      // result in opening a panel or not
       context.events.on(
         "offerFullViewToggle",
         ({ offer }) => {
@@ -57,6 +97,9 @@ class CustomOfferList {
     ];
   }
 
+  /**
+   * As required in the `IOfferListComponent` interface
+   */
   destroy() {
     if (this.map) {
       this.map.destroy();
@@ -67,6 +110,14 @@ class CustomOfferList {
   }
 }
 
+/**
+ * We need to subclass a standard `SearchBoxComposer`
+ * to achieve to important goals:
+ *   * Use the custom offer list we created instead
+ *     of the standard component
+ *   * Enrich the preview data with the geographical
+ *     coordinates of the coffee shop
+ */
 class CustomComposer extends SearchBoxComposer {
   buildOfferListComponent(
     context,
@@ -93,6 +144,10 @@ class CustomComposer extends SearchBoxComposer {
   }
 }
 
+/**
+ * We're subclassing `SearchBox` to use our
+ * enhanced composer
+ */
 class CustomSearchBox extends SearchBox {
   buildComposer(context, container, options) {
     return new CustomComposer(context, container, options);