Amend design doc with an example that you can actually test without...

... adding new pcrud controllers to your IDL.

Signed-off-by: Lebbeous Fogle-Weekley <lebbeous@esilibrary.com>

diff --git a/docs/TechRef/Flattener/design.txt b/docs/TechRef/Flattener/design.txt
index 2ba84bb..087b188 100644 (file)
--- a/docs/TechRef/Flattener/design.txt
+++ b/docs/TechRef/Flattener/design.txt
@@ -24,19 +24,20 @@ Implemented as a JSON object, each property name will represent a data element t
 
 Example Map
 ~~~~~~~~~~~
-Assuming a core class of circ:
+Assuming a core class of acp:
 
 --------------------------------------------------------------------------------
 {
-    "patron_barcode":   "usr.card.barcode",
+    "barcode":          "barcode",
     "circ_lib_name":    "circ_lib.name",
     "circ_lib":         "circ_lib.shortname",
-    "xact_start":       { "path": "xact_start", "sort": true, "display": true },
-    "id":               "id",
-    "checkin_time":     { "path": "checkin_time", "filter": true, "sort": true }
+    "call_number":      { "path": "call_number.label", "sort": true, "display": true },
+    "tcn":              { "path": "call_number.record.tcn_value", "filter": true, "sort": true }
 }
 --------------------------------------------------------------------------------
 
+'Yes I realize that this example ignores call number prefixes and suffixes, but it's just an example.'
+
 Based on this mapping structure simplified queries can be constructed by the caller, which will then be expanded in the flattening service to produce join and where clauses that can be used by open-ils.pcrud.
 
 Example Query
@@ -44,7 +45,7 @@ Example Query
 Assuming the above example map:
 
 -------------------------------------
-{   "xact_start":   { ">": "today" },
+{   "tcn":   { ">": "100" },
     "circ_lib": "BR1"
 }
 -------------------------------------
@@ -56,29 +57,42 @@ Expanded PCrud Query
 ~~~~~~~~~~~~~~~~~~~~
 
 ---------------------------------------
-{   "xact_start":       {">": "today"},
-    "+circ_lib_aou":    {"name": "BR1"}
+{
+    "+__circ_lib_aou": {"shortname":"BR1"},
+    "+__tcn_bre":{"tcn_value":{">":"100"}}
 }, {
+    "flesh_fields": {
+        "acp":["call_number", "circ_lib"]
+    },"flesh":1,
     "join": {
-        "circ_lib_aou": {
-            "class": "aou",
-            "fkey": "circ_lib"
+        "__circ_lib_name_aou": {
+            "fkey":"circ_lib",
+            "class":"aou",
+            "field":"id"
+        },
+        "__call_number_acn":{
+            "fkey":"call_number",
+            "class":"acn",
+            "field":"id"
         },
-        "usr_au": {
-            "class": "au",
-            "fkey": "usr",
-            "join": { "usr_card_ac": {
-                        "class": "ac",
-                        "fkey": "card"
-                    }
+        "__tcn_acn":{
+            "fkey":"call_number",
+            "class":"acn",
+            "field":"id",
+            "join":{
+                "__tcn_bre":{
+                    "fkey":"record",
+                    "class":"bre",
+                    "field":"id"
+                }
             }
+        },
+        "__circ_lib_aou":{
+            "fkey":"circ_lib",
+            "class":"aou",
+            "field":"id"
         }
-    },
-    "flesh_fields": {
-        "circ" : ["circ_lib","usr"],
-        "aou" : ["card"]
-    },
-    "flesh": 2
+    }
 }
 ---------------------------------------
 
@@ -92,18 +106,19 @@ Parameters:
 
 - Authentication token (as for pcrud)
 - IDL class
-- "circ"
+ * e.g. "acp"
 - Path map hash
- * e.g. {"patron_barcode":"usr.card.barcode","circ_lib_name":"circ_lib.name", "circ_lib":"circ_lib.shortname","xact_start":{ "path": "xact_start", "sort": true, "display": true},"id":"id","checkin_time":   { "path": "checkin_time", "filter": true, "sort": true }}
+ * e.g. { "barcode": "barcode", "circ_lib_name": "circ_lib.name", "circ_lib": "circ_lib.shortname", "call_number": { "path": "call_number.label", "sort": true, "display": true }, "id": "id", "tcn": { "path": "call_number.record.tcn_value", "filter": true, "sort": true } }
 - Simplified query hash
- * e.g. {"xact_start": { ">": "today" }, "circ_lib": "BR1"}
+ * e.g. {"tcn": {">": "100" }, "circ_lib": "BR1"}
 - Simplified sort/limit/offset hash
- * e.g. { "sort":[{"checkin_time":"desc"},{"circ_lib":"asc"}],"limit":10}
- * or {"sort":{"checkin_time":"desc"}}
+ * e.g. { "sort":[{"circ_lib":"desc"},{"call_number":"asc"}],"limit":10 }
+ * or {"sort":{"call_number":"desc"}}
  * or {"sort": "circ_lib"}
  * or {"sort": ["circ_lib", {"checkin_time": "desc"}]}
 
 Returns:
 
 - stream (or array, for .atomic) of hashes having the shape described in the path map
- * e.g.  {"patron_barcode":"3123456789012","circ_lib_name":"Branch 1", "circ_lib":"BR1","xact_start":"2011-10-17T12:00:00-05:00,"id":"123"}
+ * e.g.  { "call_number":"PR3533.B61994", "circ_lib_name":"Example Branch 1", "barcode":"23624564258", "id":7, "circ_lib":"BR1" }
+