Differences

This shows you the differences between two versions of the page.

--- newdevs:angular_making_calls [2023/08/08 16:12] – created sandbergja
+++ newdevs:angular_making_calls [2024/03/28 23:16] (current) – [NetService example] sandbergja
@@ Line 1: / Line 1: @@
 ====== Calling OpenSRF from the Angular Client ======
-The Angular client doesn't talk to the database directly, it instead communicates with OpenSRF to get the information and perform the actions it needs.  To do this, it uses the `NetService`, which is itself a wrapper around the [[https://git.evergreen-ils.org/?p=OpenSRF.git;a=tree;f=src/javascript;h=3fad8ec8c9df29e7858991fda1469ca033616039;hb=ec2d71a8281a9edb2d0c9556bff31789cce85e53|OpenSRF javascript code]].
+The Angular client doesn't talk to the database directly, it instead communicates with OpenSRF to get the information and perform the actions it needs.  To do this, it uses the ''NetService'', which is itself a wrapper around the [[https://git.evergreen-ils.org/?p=OpenSRF.git;a=tree;f=src/javascript;h=3fad8ec8c9df29e7858991fda1469ca033616039;hb=ec2d71a8281a9edb2d0c9556bff31789cce85e53|OpenSRF javascript code]].
-The Angular client uses two general approaches to interacting with OpenSRF on database-related matters:
+The Angular client uses two services to interacting with OpenSRF on database-related matters:
-  * Using the NetService directly to make a specific OpenSRF method.
+  * The ''NetService'', which directly calls a specific OpenSRF method that you specify in your code.
-  * Using the PcrudService, which provides a general interface for most database operations.
+  * The ''PcrudService'', which provides a one-size-fits-all interface for most database operations, and uses the ''NetService'' internally.
-Using a specific OpenSRF method is preferred in cases in which:
+Calling a specific OpenSRF method is preferred in cases in which:
    * You need to make multiple database calls for a single action in the UI
@@ Line 16: / Line 16: @@
 The PcrudService is great for other cases, especially since it automatically checks the logged-in user's permissions and only provides the access that they are authorized for.
-Since both approaches are used widely in the angular client, we will provide an example of each for each CRUD action below:
+Since both services are used widely in the angular client, we will provide an example of each for each CRUD action below:
 ===== Creating a row in the database =====
+==== PcrudService example ====
 Let's start out with a simple PcrudService request:
-  // Create a new object in memory with the required information
+  /* Create a new object in memory with the required information
+   *
+   * The "ahrn" class is mapped to the action.hold_request_note
+   * table in the database.  These mappings can be found in
+   * the fm_IDL.xml file.
+   */
   const note = this.idl.create('ahrn');
   note.staff('t');
@@ Line 34: / Line 42: @@
   this.pcrud.create(note)
-    // Pcrud calls are asynchronous, so that they don't
+    /* Pcrud calls are asynchronous, so that they don't
-    // block other work that the browser needs to do in
+     * block other work that the browser needs to do in
-    // the staff client.
+     * the staff client.
-    //
+     *
-    // The following alert will happen once the PcrudService
+     * The following alert will happen once the PcrudService
-    // recieves a message back from OpenSRF
+     * receives a message back from OpenSRF
+     */
     .subscribe(() => { alert('You did it!') });
-The above assumes that you have injected the IdlService as this.idl and the PcrudService as this.pcrud.
+The above assumes that you have injected the ''IdlService'' as ''this.idl'' and the ''PcrudService'' as ''this.pcrud'' earlier in the file.
-Here's an example that uses the NetService to create a database object instead, since the work we are doing is more complex and better suited to the Perl layer (reading from one database object, then creating a new database object in a totally different table with certain data taken from the first object):
+==== NetService example ====
+Here's an example that uses the ''NetService'' to create a database object instead, since the work we are doing is more complex and better suited to the Perl layer (reading from one database object, then creating a new database object in a totally different table with certain data taken from the first object):
   this.net.request( 'open-ils.booking',
     'open-ils.booking.resources.create_from_copies',
-    // This OpenSRF method takes two parameters: the user's token and
+    /* This OpenSRF method takes two parameters: the user's token and
-    // an array of item IDs to make bookable
+     * an array of item IDs to make bookable
+     */
     this.auth.token(), [1, 2, 3])
     // Like the PcrudService, the NetService is also asynchronous...
     .subscribe(() => { alert('Those items are bookable now')});
-  // Since the previous alert has to wait until a communication
+  /* Since the previous alert has to wait until a communication
-  // comes back from OpenSRF, the following alert will almost
+   * comes back from OpenSRF, the following alert will almost
-  // certainly appear to the user before the
+   * certainly appear to the user before the
-  // 'Those items are bookable now' alert.
+   * 'Those items are bookable now' alert.
+   */
   alert('loading...');
-The above assumes that you have injected the AuthService as this.auth and the NetService as this.net.
+The above assumes that you have injected the ''AuthService'' as ''this.auth'' and the ''NetService'' as ''this.net''.
 ===== Reading data from the database =====
-Examples coming soon
+==== PcrudService example ====
+   this.pcrud.search(
+       // The IDL class we want to search: this is shelving locations
+       'acpl',
+       // The filters we want to pass (the SQL WHERE clause).
+       // This uses the
+       {opac_visible: 't'}
+    ).subscribe((location) => console.log(location.name()));
+Each shelving location is considered to be a different RxJS event, so the above
+code will log each shelving location to the console separately.  If you want
+to wait for them to finish and log them all at once in an array, you can do so
+with the RxJS toArray operator:
+    this.pcrud.search(
+        'acpl',
+        {opac_visible: 't'}
+    ).pipe(toArray()
+    ).subscribe((locations) => {
+        // Only log the name field, not the whole object
+        console.log(locations.map((location) => location.name()))
+    });
+More information about the JSON query syntax is [[documentation:tutorials:json_query#the_where_clause|available in the tutorial]].
+The above assumes that you have injected the ''PcrudService'' as ''this.pcrud'' earlier in the file.
+==== NetService example ====
+Some interfaces need data in very specific formats, or need to use complicated JOINs
+when querying the database.  In these cases, a nice approach is to create a custom
+OpenSRF method in Perl and use the angular NetService to call it.  In this example,
+we're calling the 'open-ils.acq.purchase_order.retrieve' OpenSRF method to gather a
+ton of information about the purchase order with ID #1.  Refer to the OpenSRF method's
+documentation to know which parameters you need to send with your request.
+    this.net.request(
+        'open-ils.acq',
+        'open-ils.acq.purchase_order.retrieve',
+        this.auth.token(),
+, {
+            flesh_provider: true,
+            flesh_notes: true,
+            flesh_po_items: true,
+            flesh_po_items_further: true,
+            flesh_price_summary: true,
+            flesh_lineitem_count: true
+        }
+    ).subscribe(po => console.log(po));
+The above assumes that you have injected the ''NetService'' as ''this.net'' and the ''AuthService'' as ''this.auth'' earlier in the file.
 ===== Updating data in the database =====
+==== PcrudService example ====
-Examples coming soon
+The basic workflow for updating data in the database is to:
+  - Retrieve the object you wish to change.
+  - Make your changes in memory.
+  - Use the Pcrud service's ''update'' method to save the change to the database.
+The following example retrieves the item with ID #1, changes its barcode to 1234567 in memory, then saves the updated barcode to the database:
+    this.pcrud.retrieve('acp', 1)
+        .pipe(switchMap((item) => {
+            item.barcode('1234567');
+            return this.pcrud.update(item);
+    })).subscribe();
+Notice that we use the rxjs ''switchMap'' operator to switch our observable halfway through, from a `retrieve` call to an `update` call.  This helps us to avoid nesting RxJs subscriptions within each other, which can get very complicated to troubleshoot.
+==== NetService example ====
+Here is an example of refreshing the contents of an automatically-generated carousel (the one with ID 201):
+    this.net.request('open-ils.actor',
+                  'open-ils.actor.carousel.refresh',
+                  this.auth.token(),
+).subscribe(() => {
+        alert('I feel so refreshed now!');
+    });
 ===== Deleting data in the database =====
-Examples coming soon
+==== PcrudService example ====
+As with updating objects, you will need to retrieve an object and have a copy in memory before you can delete it.  The following example searches for all shelving locations called "Microfilm" and then deletes them, one by one:
+  this.pcrud.search('acpl',
+                     {name: 'Microfilm'})
+       .pipe(switchMap((location) => {
+           return this.pcrud.remove(location);
+       })).subscribe();
+==== NetService example ====
+Here's an example of deleting record bucket #13 from the database, along with all its bucket entries (assuming the currently logged in user has the DELETE_CONTAINER permission):
+   this.net.request('open-ils.actor',
+                    'open-ils.actor.container.full_delete',
+                    this.auth.token(),
+                    'biblio',
+).subscribe(() => {
+        alert('Your bucket is gone!');
+    });
+===== Troublsehooting OpenSRF calls in your browser =====
+When troubleshooting an angular screen that makes OpenSRF calls, it
+can be helpful to use your browser's dev tools to see exactly which
+request the Angular code made, and exactly what response it got
+back.  In both Firefox and Chrome, this can be done via the Network
+tab in your devtools.
+==== Firefox ====
+  - Open [[https://firefox-source-docs.mozilla.org/devtools-user/|the developer tools]]
+  - Open the Network tab
+  - Perform the action in the UI that you are troubleshooting (e.g. navigate to the screen you are working on, press the button that is causing problems, etc.)
+  - In the devtools, press the WS button to limit to Websockets traffic.
+  - Select the websocket request from the list of requests (sometimes there are multiple, I'm not sure why).
+  - On the response tab, you will see a list of all traffic that happened within the websocket.  You can select each message to get more details about the payload it contained.  The Up arrow symbol indicates a message that the Angular client sent to OpenSRF, while the Down arrow symbol indicates a message that OpenSRF sent to the Angular client.
+==== Chrome, Edge, and other Chromium-based browsers ====
+  - Open [[https://developer.chrome.com/docs/devtools/open/|the developer tools]]
+  - Open the Network tab
+  - Perform the action in the UI that you are troubleshooting (e.g. navigate to the screen you are working on, press the button that is causing problems, etc.)
+  - In the devtools, press the WS button to limit to Websockets traffic.
+  - Select the websocket request from the list of requests.
+  - On the messages tab, you will see a list of all traffic that happened within the websocket.  You can select each message to get more details about the payload it contained.  The Up arrow symbol indicates a message that the Angular client sent to OpenSRF, while the Down arrow symbol indicates a message that OpenSRF sent to the Angular client.