Differences

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

--- dev:browser_staff:manifesto [2014/01/08 10:21] – Staring browser staff manifesto erickson
+++ dev:browser_staff:manifesto [2022/02/10 13:34] (current) – external edit 127.0.0.1
@@ Line 3: / Line 3: @@
 Development guidelines for the browser-based staff client interface.
-  * This list is under construction.  Please remove this message when it seems appropriate.
+  * **Note**: This list is under construction.  Please remove this message when it seems appropriate.
 === Javascript ===
@@ Line 10: / Line 10: @@
     * Stick with egNet, egPCRUD, and $http and you're covered.
   * Use PCRUD whenever possible -- it's faster.
-  * Avoid global variables
+  * Avoid global variables. Instead use Angular services for app-global data management.
   * Avoid DOM manipulation outside of Angular directives
     * There is one case in prototype code where this was unavoidable.  It's documented inline w/ Angualar bug reference.
@@ Line 28: / Line 28: @@
     * For example, in the prototype the URL "staff/circ/patron/123" draws information for patron id=123.  It is normally accessed via routing, with data already fetched.  When loading this page directly, the UI is forced to fetch patron 123 (and associated data), since the patron data will not already be loaded within in a new page.
   * Use angular and angular-ui only.  Avoid loading new 3rd-party libraries without community approval.
+  * Avoid adding items to the controller's $scope that are not needed by the UI.  This causes unnecessary overhead.  Specifically, avoid linking large nested objects to the scope, since each $digest run has to clone and compare versions of the object as part of the $watch process.
@@ Line 34: / Line 35: @@
   * For dynamic UI elements, use http://angular-ui.github.io/bootstrap/ since this code is already loaded and available.
     * if something doesn't look/work right, document it in the code and fall back to stock Bootstrap markup.
+  * Do not use HTML tables for page layout.  Use Bootstrap rows and columns instead.
+  * Actions which modify the URL should be presented as text links (a/href), while controls which perform in-page actions (e.g. open a modal dialog) should be rendered as buttons.
 === Templates ===
-  * When a template is needed on page load, use a server-side / Template Toolkit INCLUDE to include the template within the body of the main page.
+  * When a template is needed on page load, use a server-side Template Toolkit INCLUDE to include the template within the body of the main page.
     * <code html>[% INCLUDE 'path/to/template.tt2' %]</code>
   * When a template is not needed on initial page load, especially rarely used templates, load them on-demand via AngularJS templateUrl.
     * <code javascript>$modal.open({templateUrl: './path/to/template', controller:{}})</code>
   * For any grey area, use best judgement.
+  * Use i18n filters for dates and money:   e.g. <code html><div>{{ due_date | date:'shortDate' }}</div></code>
+    * The exact filter options may change w/ settings, etc.
+=== Tips and Gotchas ===
+  * Disable all browser caching during development.
+    * Chrome aggressively caches on-demand templates.
+    * In Chrome, in the JS console, click on the configure icon and choose "disable cache while developer tools are open" -- and leave your developer tools open.
+  * Beware multiple ng-view directives in the page -- this will cause looping and will probably kill your browser!
+  * $location.path(...) values always starts with a "/" -- otherwise, hijinks ensue.
+  * Test on-demand templates by fetching them directly in the browser first.  E.g.  http://host/eg/staff/circ/patron/t_precat_dialog
+  * Bootstrap does not support nested menus, since they are not mobile friendly.
+  * If your browser window is too small, you will see the mobile layout.  Make your browser bigger.