Differences

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

--- dev:browser_staff:examples [2018/06/04 11:32] – [Edit the controller] clarifying that the fielder flattened search and the json_query formats are a little different sandbergja
+++ dev:browser_staff:examples [2023/06/01 13:20] (current) – [Edit the tt2 template] master to main dyrcona
@@ Line 1: / Line 1: @@
 ====== Examples of developing for the Web client ======
+===== Angular =====
-===== Minimum Working Example: Screen that gets data from OpenSrf =====
+==== Minimum Working Example: Basic screen ====
-==== Planning ====
+=== Create a new component ===
-=== Decide on the requirements and UI of your new screen ===
+Components are the building blocks of the Angular staff client.  Each one contains some TypeScript and some view code (called a template, which may or may not be broken up into a separate file).
+To start with, we will create a super simple component that just displays the words "Evergreen is good at math".  To do this, create a new folder called Open-ILS/src/eg2/src/app/staff/math.
+Inside your folder, create a file called eg-math.component.ts with the following content:
+<code>import { Component } from '@angular/core';
+@Component({
+  template: '<p>Evergreen is good at math</p>',
+})
+export class EgMathComponent {
+}</code>
+=== Add your component to a module ===
+Next, components have to be grouped into modules -- basically collections of similar components.  Let's create a math module inside the same folder.  Create a file called math.module.ts with the following content:
+<code>import {NgModule} from '@angular/core';
+import {EgMathComponent} from './eg-math.component';
+import {RouterModule, Routes} from '@angular/router';
+const routes: Routes = [{
+  path: 'eg',
+  component: EgMathComponent
+}];
+@NgModule({
+  imports: [RouterModule.forChild(routes)],
+  exports: [RouterModule],
+  declarations: [EgMathComponent]
+})
+export class MathModule { }</code>
+=== Add your module to the Staff router ===
+Finally, it's time to let the rest of Evergreen's Angular client know where to find your code.  Add this to Open-ILS/src/eg2/src/app/staff/routing.module.ts, within the routes constant:
+<code>{
+    path: 'math',
+    loadChildren: '@eg/staff/math/math.module#MathModule'
+  },</code>
+Re-compile, the client, and you should see your brand new screen at https://[yourdomain.edu]/eg2/en-US/staff/math/eg
+=== Add another component with an OpenSRF call ===
+Create a new .ts file in Open-ILS/src/eg2/src/app/staff/math, called adder.component.ts:
+<code>
+import {Component, OnInit} from '@angular/core';
+import {NetService} from '@eg/core/net.service';
+@Component({
+  selector: 'eg-adder',
+  templateUrl: './adder.component.html',
+})
+export class AdderComponent implements OnInit {
+  sum: number = 0;
+  addTwoNumbers: (first: number, second: number) => void;
+  constructor(
+    private net: NetService
+  ){}
+  ngOnInit() {
+    this.addTwoNumbers = (first: number = 0, second: number = 0) => {
+      this.net.request(
+        'opensrf.math',
+        'add',
+        first, second)
+      .subscribe(response => this.sum = response);
+    }
+  }
+}
+</code>
+This has some differences from our first one.  First of all, it has a selector, which means that we can include it in other components by saying <eg-adder></eg-adder>.  Secondly, it has its template in a separate file, Open-ILS/src/eg2/src/app/staff/math/adder.component.html.  In fact, let's create that now:
+<code>
+<label i18n>First Number: <input #firstNumber type="number"></label>
+<label i18n>Second Number: <input #secondNumber type="number"></label>
+<button (click)="addTwoNumbers(firstNumber.value, secondNumber.value)">Add</button>
+<p>Sum: {{sum}}</p>
+</code>
+Let's update our module to let it know about the new component:
+<code>import {NgModule} from '@angular/core';
+import {EgMathComponent} from './eg-math.component';
+import {AdderComponent} from './adder.component';
+import {RouterModule, Routes} from '@angular/router';
+const routes: Routes = [{
+  path: 'eg',
+  component: EgMathComponent
+}];
+@NgModule({
+  imports: [RouterModule.forChild(routes)],
+  exports: [RouterModule],
+  declarations: [EgMathComponent, AdderComponent]
+})
+export class MathModule { }</code>
+Finally, let's update our first component's template to include a reference to our new component.  To do this, just change the line ''template: '<p>Evergreen is good at math</p>'' to ''template: '<p>Evergreen is good at math</p><eg-adder></eg-adder>'''
+===== AngularJs =====
+==== Minimum Working Example: Screen that gets data from OpenSrf ====
+=== Planning ===
+== Decide on the requirements and UI of your new screen ==
 Our example will ask the user for two numbers, then add them when the user presses a button.
-=== Decide which Evergreen module your screen is part of ===
+== Decide which Evergreen module your screen is part of ==
 For example, is it part of circ? booking? cataloging?  Today's example is under cataloging module.
-==== Creating your screen ====
+=== Creating your screen ===
-=== Add a route for your screen ===
+== Add a route for your screen ==
 Find the app.js for the appropriate module.  The app.js files are in ''Open-ILS/web/js/ui/default/staff'' in the git repository, in ''/openils/var/web/js/ui/default/staff'' for installed systems.
@@ Line 29: / Line 147: @@
 </code>
-=== Create a controller for your screen ===
+== Create a controller for your screen ==
 This can be in the same js file as your route was.  Here's one to add to ''web/js/ui/default/staff/cat/catalog/app.js'':
@@ Line 47: / Line 165: @@
 </code>
-===Create a tt2 template for your screen===
+==Create a tt2 template for your screen==
 Look for an index.tt2 file that includes the JS file you were working on.  Create a new file that begins with ''t_'' in the same directory.  Starting the template with ''t_'' will add the Evergreen Web client header and other goodies from the index.tt2 file in the same directory.  This includes the controller that you created during the last step.
@@ Line 62: / Line 180: @@
 </code>
-===Test your screen===
+==Test your screen==
 It will be available at https://[DOMAIN_NAME]/eg/staff/cat/catalog/math
-=====Add a popup modal to your screen=====
+====Add a popup modal to your screen====
 This example builds on the previous example of an addition screen by adding a button, which, when pressed, opens up a modal asking the user to confirm.
-====Edit the controller====
+===Edit the controller===
 First of all, edit the controller to make sure it can access the egAlertDialog factory:
@@ Line 81: / Line 199: @@
 }</code>
-====Add your string to egCore.strings====
+===Add your string to egCore.strings===
 We want to be able to translate the egAlertDialog text to the language that the user prefers.  To do this, we will define it in the parent .tt2 page (in this case, ''templates/staff/cat/catalog/index.tt2'').
@@ Line 90: / Line 208: @@
 s.SHARE_YOUR_OPINION = "[% l('I think so too!') %]";
 </code>
-====Edit the tt2 template====
+===Edit the tt2 template===
 Here, we'll just add a simple button outside of the <form> that, when clicked, causes our alert to display:
@@ Line 100: / Line 218: @@
 </code>
-Note: Evergreen has several other built-in types of modals, such as egConfirmDialog, egPromptDialog, and egSelectDialog.  You can find a complete list, as well as usage documentation, in this file: https://github.com/evergreen-library-system/Evergreen/blob/master/Open-ILS/web/js/ui/default/staff/services/ui.js
+Note: Evergreen has several other built-in types of modals, such as egConfirmDialog, egPromptDialog, and egSelectDialog.  You can find a complete list, as well as usage documentation, in this file: https://github.com/evergreen-library-system/Evergreen/blob/main/Open-ILS/web/js/ui/default/staff/services/ui.js
-=====Add an egGrid to your screen=====
+====Add an egGrid to your screen====
 One of the best ways to present tabular data in Evergreen is to use an egGrid.  This example builds on the previous two examples by adding an egGrid that displays all the contents of a specific table in the database.  Our grid will display a very simple table called ''biblio.peer_type''.
-====Edit the controller====
+===Edit the controller===
 First of all, edit the controller to make sure it can access the egGridDataProvider factory:
@@ Line 123: / Line 241: @@
 The query is in a [[https://github.com/evergreen-library-system/Evergreen/blob/master/docs/TechRef/Flattener/design.adoc|specific JSON syntax]] that represents an SQL query.  [[documentation:technical:jsontutorial|This tutorial]] for a related (but slightly different) JSON syntax should get you started.
-====Edit the tt2 template====
+===Edit the tt2 template===
 Here, we'll add an eg-grid directive with some additional configuration options:
@@ Line 141: / Line 259: @@
 The ''grid-controls'' option simply refers back to the ''gridControls'' hash we established in our controller.  Finally, the ''persist-key'' allows users to change various settings on the grid and save those preferences.
+====Populate a dropdown menu using Permacrud====
+===Edit the controller===
+This example uses a simple `retrieveAll` call.  If you want to be more selective about the records you pull in, you can put filters, sorting, fleshing, etc. inside the second argument.  In this example, we will retrieve all the contents of the `config.best_hold_order` table.  Add the following to your controller:
+<code>
+    egCore.pcrud.retrieveAll('cbho', {}, {atomic : true}).then(
+        function(list) {
+            $scope.best_hold_order_list = list;
+        });
+</code>
+===Edit the tt2 template===
+Add the following to your template:
+<code>
+<select ng-model="selected_hold_order" ng-options="hold_order.id() as hold_order.name() for hold_order in best_hold_order_list"></select>
+</code>