web api preso cont.

Signed-off-by: Bill Erickson <berickxx@gmail.com>

diff --git a/api_presentation/web_apis.asciidoc b/api_presentation/web_apis.asciidoc
index d1c261e..96e976f 100644 (file)
--- a/api_presentation/web_apis.asciidoc
+++ b/api_presentation/web_apis.asciidoc
@@ -50,7 +50,8 @@ XML file which describes the structure of Evergreen classes.
   reporter:label="Organizational Unit"
   oils_persist:field_safe="true">
                                                                            
-  <fields oils_persist:primary="id" oils_persist:sequence="actor.org_unit_id_seq">
+  <fields oils_persist:primary="id" 
+    oils_persist:sequence="actor.org_unit_id_seq">
     <field reporter:label="ID" name="id" reporter:datatype="id"/>
     <field reporter:label="Name" name="name" 
       reporter:datatype="text" oils_persist:i18n="true"/>
@@ -85,7 +86,7 @@ XML file which describes the structure of Evergreen classes.
             name="transit" oils_persist:virtual="true" />
 ---------------------------------------------------------------------------
 
-== Scripting (pre-browser client)
+== Scripting (Dojo)
 
 [source,js]
 ---------------------------------------------------------------------------
@@ -102,7 +103,7 @@ dojo.forEach(fieldmapper.IDL.classes.aou.fields,
 ---------------------------------------------------------------------------
 
 
-== Scripting (browser client)
+== Scripting (Angular)
 
 [source,js]
 ---------------------------------------------------------------------------
@@ -118,6 +119,15 @@ angular.forEach(egCore.idl.classes.aou.fields,
 );
 ---------------------------------------------------------------------------
 
+== Perl
+
+[source,perl]
+---------------------------------------------------------------------------
+use OpenILS::Utils::Fieldmapper;
+my $org = new Fieldmapper::actor::org_unit();
+$org->name($name);
+---------------------------------------------------------------------------
+
 == Accessing the IDL
 
  * Source file /openils/conf/fm_IDL.xml
@@ -132,7 +142,7 @@ angular.forEach(egCore.idl.classes.aou.fields,
 
 [source,sh]
 ---------------------------------------------------------------------------
-srfsh# request open-ils.pcrud open-ils.pcrud.retrieve.au "<auth>", 1
+srfsh# request open-ils.pcrud open-ils.pcrud.retrieve.aou "<auth>", 1
 ---------------------------------------------------------------------------
 
  * Create, Retrieve, Update, Delete.
@@ -142,10 +152,10 @@ srfsh# request open-ils.pcrud open-ils.pcrud.retrieve.au "<auth>", 1
 
 == PCRUD IDL Configuration
 
- . What classes are accessible to PCRUD
- . What actions on each class are permitted to PCRUD
- . What permisssion(s) are required to perform each action
- . What field to use as the context org unit for permission checks
+ . Classes
+ . Actions
+ . Permissions
+ . Context org unit
 
 == PCRUD IDL Example
 [source,xml]
@@ -209,7 +219,7 @@ srfsh# request open-ils.pcrud open-ils.pcrud.retrieve.au "<auth>", 1
 srfsh# request open-ils.pcrud open-ils.pcrud.retrieve.aou "<auth>", 1 
 
 srfsh# request open-ils.pcrud open-ils.pcrud.search.aou 
-    "<auth>", {"id":{"!=":null}}
+    "<auth>", {"ou_type":2,"id":{">":2}}
 
 srfsh# request open-ils.pcrud open-ils.pcrud.create.aou 
     "<auth>", {"__c":"aou","__p":[null,"11","12","7","12",...]}
@@ -285,7 +295,8 @@ Received Data: {
 == ANONYMOUS PCRUD
 
  * Access to public data for unauthenticated clients
- * Slight speed bump by avoiding open-ils.auth call and perm checks
+ * Improves speed by avoiding open-ils.auth call and perm checks
+ * Read-only
 
 [source,xml]
 ---------------------------------------------------------------------------
@@ -297,7 +308,7 @@ Received Data: {
 srfsh# request open-ils.pcrud open-ils.pcrud.retrieve.aou "ANONYMOUS", 1
 ---------------------------------------------------------------------------
 
-== PCRUD JavaScript Interface (pre-browser client)
+== PCRUD JavaScript Interface (Dojo)
 
 [source,js]
 ---------------------------------------------------------------------------
@@ -307,15 +318,22 @@ pcrud.retrieve('aou', 1, {oncomplete : function(org) { ... }});
 pcrud.update(some_org, {oncomplete : function(resp) { ... }});
 
 pcrud.search('aou', {parent_ou : 1}, {   
-    oncomplete : function(r) {
-        var orgs = openils.Util.readResponse(r);
-        console.log('org units: ' + orgs);
+    oncomplete : function() {...}, 
+    onerror    : function() {...},
+    onresponse : function(r) { // streams in XUL client only
+        var org = openils.Util.readResponse(r);
+        console.log('one org unit: ' + org);
     }
 });
 
 ---------------------------------------------------------------------------
 
-== PCRUD JavaScript Interface (browser client)
+== A Quick Note on Promises
+
+ * Read this: https://docs.angularjs.org/api/ng/service/$q
+ * See also: http://yeti.esilibrary.com/dev/pub/web-staff-log.html#_2013_12_04_promises_in_angularjs
+
+== PCRUD JavaScript Interface (Angular)
 
  * Uses promises
  * Defaults to streaming searches
@@ -329,7 +347,7 @@ egCore.pcrud.search('aou', {parent_ou : 1})
 .then(
     function() {...},   // oncomplete
     function() {...},   // onerror
-    function(one_org) { // onresponse
+    function(one_org) { // onresponse -- streams universally supported
         console.log('one org unit: ' + one_org);
     }
 });
@@ -337,12 +355,9 @@ egCore.pcrud.search('aou', {parent_ou : 1})
 
 == When Not To Use PCRUD
 
- * PCRUD is powerful enough to implement most logic in the client, but 
-   it's not always the best choice.
- * Avoid putting complex logic in client code (e.g. web code) which 
-   may be needed by other client code.  Use the API.  
- * With web development in particular, sufficiently complex logic will
-   be faster as an API call, since less data has to traverse the network.
+ * PCRUD is powerful and fast, but it's not a replacement for an API.
+ * Be wary of large amounts of data traversing the network
+ * Avoid sequestering re-usable code in a client application.
 
 == Fielder