[DRAFT] Dossiers

devguide.md

@@ -47,6 +47,25 @@ The script also “calculates” the values for the `connection-modes` table for
 
 It also does some slugification and destination-name normalization, since our handling of dots and dashes hasn't been consistent over time. Finally, it checks to see if there’s a folder for each destination. If it finds a new one, the script makes a folder with a “stub” markdown file for that destination, and then adds a line for it to an "incompleteDocs.txt" file. (It doesn't check to see if it's already listed, just appends to the file.)
 
+### Connection Modes in the Catalog script
+
+As part of the Dossiers project we worked on making the Connection Modes table more readable. Originally we were going to have per-page liquid run, but these modes don't change often so it would've added a lot of build time for very little benefit. Instead we pushed it into `catalog.js`.
+Once the connection modes device and cloud arrays are set, we do a bunch of calculations, and add a text summary, a number which corresponds to that summary for easier programmatic writing, and a rough category.
+
+| Case | Summary                                | Type        | Message                                                                                                                                                     |
+| ---- | -------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 0    | No data available                      | none        | No connection mode information available.                                                                                                                   |
+| 1    | Both device, no cloud                  | device-only | accepts device-mode data from both Analytics.js and mobile sources. It does not accept data in cloud-mode.                                                  |
+| 2    | AJS (web device) only                  | device-only | accepts device-mode data only from Analytics.js.                                                                                                            |
+| 3    | Mobile device mode only                | device-only | accepts device-mode data only from a mobile source.                                                                                                         |
+| 4    | Accepts from all                       | all         | accepts cloud-mode data from all Segment source types. It can accept device-mode data from both web and mobile sources.                                     |
+| 5    | All cloud types                        | cloud-only  | accepts cloud-mode data from all Segment source types. It does not offer device-mode connections.                                                           |
+| 6    | Mobile and Server cloud only           | cloud-only  | accepts data from any Segment mobile or server source in cloud mode. It does not accept data from a web source, and does not offer device-mode connections. |
+| 7    | Web and mobile cloud only              | cloud-only  | accepts only cloud-mode data from web and mobile sources.                                                                                                   |
+| 8    | Mobile cloud only                      | cloud-only  | accepts only cloud-mode data from mobile sources.                                                                                                           |
+| 9    | All cloud types, 1 device mode         | mixed       | accepts data in cloud-mode from all source types, and can accept data in device-mode from [Analytics.js or mobile] sources.                                 |
+| 10   | Web and mobile cloud, 1 device         | mixed       | accepts data in cloud-mode from web and mobile sources, and can accept data in device-mode from [Analytics.js or mobile] sources.                           |
+| 11   | Mobile and server cloud, mobile device | mixed       | accepts data in cloud-mode from mobile and server sources, and can accept data in device-mode from mobile sources.                                          |
 
 ## Developer information
 
@@ -63,9 +82,10 @@ default.html
     |- destination.html
     |- source.html
   |- main.html
-    |- catalog.html
-    |- home.html
-    |- page.html
+    |- catalog.html - used for connections catalog pages only
+    |- home.html - for main landing page only
+    |- page.html - used for all pages outside Connections catalogs, without an explicit override
+    |- search.html - search results page only
 ```
 
 ### Platform Config API + Catalog

scripts/catalog.js

@@ -54,7 +54,9 @@ const getConnectionModes = (destination) => {
       web: false,
       mobile: false,
       server: false
-    }
+    },
+    summary: "testing",
+    cmode_type: ""
   }
   destination.components.forEach(component => {
     switch (component.type) {
@@ -90,11 +92,103 @@ const getConnectionModes = (destination) => {
         break
     }
   })
+
+  // summarize connection modes in plain english.
+  // start with no-cloud
+  if (connectionModes.cloud.web == false && connectionModes.cloud.mobile == false && connectionModes.cloud.server == false){
+    // first check if no info at all available - these need backfill
+    if (connectionModes.device.web == false && connectionModes.device.mobile == false) {
+      connectionModes.summary = "No connection mode information available."
+      connectionModes.case = "0"
+      connectionModes.cmode_type = "none"
+    }
+    // handle has-device-modes: three cases
+    else if (connectionModes.device.web == true || connectionModes.device.mobile == true){
+      connectionModes.cmode_type = "device-only"
+      if (connectionModes.device.web == true && connectionModes.device.mobile == true) {
+        connectionModes.summary = "accepts device-mode data from both Analytics.js and mobile sources. It does not accept data in cloud-mode."
+        connectionModes.case = "1"
+      }
+      if (connectionModes.device.web == true && connectionModes.device.mobile == false) {
+        connectionModes.summary = "accepts device-mode data only from Analytics.js."
+        connectionModes.case = "2"
+      }
+      if (connectionModes.device.web == false && connectionModes.device.mobile == true) {
+        connectionModes.summary = "accepts device-mode data only from a mobile source."
+        connectionModes.case = "3"
+      }
+    }
+
+  }
+  //next check if all are true.
+  else if (connectionModes.cloud.web == true && connectionModes.cloud.mobile == true && connectionModes.cloud.server == true && connectionModes.device.web == true && connectionModes.device.mobile == true) {
+    connectionModes.cmode_type = "all"
+    connectionModes.summary = "accepts cloud-mode data from all Segment source types. It can accept device-mode data from both web and mobile sources."
+    connectionModes.case = "4"
+  }
+
+  //next handle all cloud-only (no-device-mode) cases
+  else if ((connectionModes.device.web == false && connectionModes.device.mobile == false) && (connectionModes.cloud.web == true || connectionModes.cloud.mobile == true || connectionModes.cloud.server == true)) {
+    connectionModes.cmode_type = "cloud-only"
+    // accepts all cloud-mode
+    if (connectionModes.cloud.web == true && connectionModes.cloud.mobile == true && connectionModes.cloud.server == true){
+      connectionModes.summary = "accepts cloud-mode data from all Segment source types. It does not offer device-mode connections."
+      connectionModes.case = "5"
+    }
+    //edge-case-y: only mobile and server cloud
+    else if (connectionModes.cloud.web == false && connectionModes.cloud.mobile == true && connectionModes.cloud.server == true){
+      connectionModes.summary = "accepts data from any Segment mobile or server source in cloud mode. It does not accept data from a web source, and does not offer device-mode connections."
+      connectionModes.case = "6"
+    }
+    //edge-case-y: web and mobile cloud, no server.
+    else if (connectionModes.cloud.web == true && connectionModes.cloud.mobile == true && connectionModes.cloud.server == false){
+      connectionModes.summary = "accepts only cloud-mode data from web and mobile sources."
+      connectionModes.case = "7"
+    }
+    //edge-case-y: mobile cloud only.
+    else if (connectionModes.cloud.web == false && connectionModes.cloud.mobile == true && connectionModes.cloud.server == false){
+      connectionModes.summary = "accepts only cloud-mode data from mobile sources."
+      connectionModes.case = "8"
+    }
+  }
+
+  //handle mixed-case - in the dossier, use the case, or type: "mixed" to invoke a check for what type of device mode
+  else if ((connectionModes.cloud.web == true || connectionModes.cloud.mobile == true || connectionModes.cloud.server == true) && (connectionModes.device.mobile == true || connectionModes.device.web == true)){
+// remove "both" as that would be covered under ALL
+    if (!(connectionModes.device.mobile == true && connectionModes.device.web == true)){
+      connectionModes.cmode_type = "mixed"
+      // all cloud-mode plus one device
+      if ((connectionModes.cloud.web == true && connectionModes.cloud.mobile == true && connectionModes.cloud.server == true) && (connectionModes.device.mobile == true || connectionModes.device.web == true)){
+        if (connectionModes.device.mobile == true || connectionModes.device.web == false){
+          connectionModes.summary = "accepts data in cloud-mode from all source types, and can accept data in device-mode from mobile sources."
+        }
+        else if (connectionModes.device.mobile == false || connectionModes.device.web == true){
+          connectionModes.summary = "accepts data in cloud-mode from all source types, and can accept data in device-mode from Analytics.js sources."
+        }
+        connectionModes.case = "9"
+      }
+      // edge-case-y: cloud web and mobile, no server, one device
+      else if ((connectionModes.cloud.web == true && connectionModes.cloud.mobile == true && connectionModes.cloud.server == false) && (connectionModes.device.mobile == true || connectionModes.device.web == true)){
+        if (connectionModes.device.mobile == true || connectionModes.device.web == false){
+          connectionModes.summary = "accepts data in cloud-mode from web and mobile sources, and can accept data in device-mode from mobile sources."
+        }
+        else if (connectionModes.device.mobile == false || connectionModes.device.web == true){
+          connectionModes.summary = "accepts data in cloud-mode from web and mobile sources, and can accept data in device-mode from Analytics.js sources."
+        }
+        connectionModes.case = "10"
+      }
+      // edge-case-y: cloud mobile and server, device mobile, no web
+      else if (connectionModes.cloud.web == false && connectionModes.cloud.mobile == true && connectionModes.cloud.server == true && connectionModes.device.mobile == true && connectionModes.device.web == false){
+        connectionModes.summary = "accepts data in cloud-mode from mobile and server sources, and can accept data in device-mode from mobile sources."
+        connectionModes.case = "11"
+      }
+    }
+  }
+
   return connectionModes
 }
 
 /**
- *
  * If catalog item does not exist, create folder and index.md file for it, and record it as incomplete for later fill in
  */
 const doesCatalogItemExist = (item) => {
@@ -266,25 +360,25 @@ const updateDestinations = async () => {
       display_name: destination.display_name,
       slug,
       name: destination.name,
+      url,
       description: destination.description,
       hidden: isCatalogItemHidden(url),
-      url,
       status: destination.status,
+      previous_names: destination.previous_names,
       logo:  {
         url: destination.logos.logo
       },
       mark: {
         url: destination.logos.mark
       },
       categories: tempCategories,
+      methods: destination.methods,
       components: destination.components,
       platforms: destination.platforms,
       browserUnbundlingSupported: destination.browserUnbundlingSupported,
       browserUnbundlingPublic: destination.browserUnbundlingPublic,
-      methods: destination.methods,
-      settings,
       connection_modes,
-      previous_names: destination.previous_names
+      settings
     }
 
     destinationsUpdated.push(updatedDestination)