web-staff-report.txt

   1 Browser-Based Staff Client After-Action Report
   2 ==============================================
   3 :Author:    Bill Erickson
   4 :Email:     berick@esilibrary.com
   5 :Date:      2013-12-18
   6
   7 References
   8 ----------
   9
  10  * http://yeti.esilibrary.com/dev/pub/techspecs/web-staff-prototype.html[Prototype Tech Specs]
  11  * http://git.evergreen-ils.org/?p=working/Evergreen.git;a=shortlog;h=refs/heads/collab/berick/web-staff-proto[Code in Evergreen Working Repository]
  12  * http://yeti.esilibrary.com/dev/pub/web-staff-log.html[Development Log]
  13  * http://angularjs.org/[AngularJS]
  14  * http://getbootstrap.com/[Bootstrap CSS]
  15  * http://angular-ui.github.io/bootstrap/[AngularJS for Bootstrap]
  16
  17 Prototype Development Goals
  18 ---------------------------
  19
  20 In addition to basic functionality, a number of specific development goals
  21 were listed in the tech specs.  Below is a breakdown of how each of these
  22 were met and what remains to do for each.
  23
  24 Speed / Responsiveness to user actions
  25 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  26
  27  * Applications are developed in functional groups.  Within each group,
  28    page reloads are not required.  This allows navigation between
  29    tightly-linked functional areas without page reloads, e.g. jumping
  30    between the patron items out list and the patron holds list.
  31
  32  * All data-fetching server communication runs asynchronously, allowing
  33    other browser processing to occur while waiting for responses.  This
  34    also prevents the possibility of browser lock-up on long-running
  35    requests.  (See: egNet and egPCRUD).
  36
  37  * When possible, batches of data requests are fired at the
  38    same time, instead of serially, to maximally leverage browser
  39    parallel XMLHttpRequest connections.  (E.g. egEnv.load())
  40
  41  * Special care was taken to avoid fetching data from the server until
  42    needed, reducing the cost of up-front data loading.
  43
  44  * In some cases, primarily in the Record Buckets UI, traditional Perl API
  45    calls were replaced with PCRUD calls.  PRCUD is much faster than Perl.
  46
  47  * The code was implemented to support Javascript minification and it has
  48    been confirmed to function correctly.  When configured, this reduces
  49    page load times.
  50
  51  * Apache gzip compression and cache optimizations added to sample Apache
  52    configs.  These were added because the existing settings were not
  53    sufficient to satisfy standard web optimization practices.  (See Chrome
  54    Audits).  Apache configuration cleanup and consolidation should be
  55    considered so that other parts of the site get the same benefits.
  56
  57
  58 TODO Items
  59 ^^^^^^^^^^
  60
  61  * Improved support for streaming and paging need to be added to some API calls
  62  * New API calls could be developed to better deliver targeted data sets to
  63    reduce the overall number of API calls.
  64  * To leverage streaming responses (which can reduce the number of API calls,
  65    in some cases by a wide margin, and allow long-running calls, like
  66    Vandelay imports), support for WebSockets is still suggested.
  67
  68
  69 Standards Compliance
  70 ~~~~~~~~~~~~~~~~~~~~
  71
  72  * Prototype developed for and tested with Chrome and Firefox.
  73   ** Incidentally, also confirmed to work on Safari and Opera.
  74  * No exotic components were used.
  75
  76
  77 Ease/Speed of Development
  78 ~~~~~~~~~~~~~~~~~~~~~~~~~
  79
  80 ****
  81 This is just my opinion.
  82 ****
  83
  84 Learning AngularJS (and Bootstrap) is neither easy or terribly
  85 difficult, but it does take some getting used to, especially if you
  86 are accustomed to writing code for the existing Dojo-driven Evergreen
  87 interfaces.  However, once you're used to it, building interfaces is
  88 considerably easier in Angular, basically because there is less
  89 code to write.
  90
  91 Probably the biggest hurdle for new developers will be resisting the urge to
  92 fall back on manual DOM manipulation and bypassing the Angular environment
  93 altogether, when it suits his/her needs.  This should be avoided, as a mix of Angular and non-Angular
  94 code will be difficult to support in the long run.  There are varying levels
  95 of Angular code purity and the more Angular-correct the code is, the easier
  96 unit testing, etc. will be, but more important than Angular perfection is
  97 simply staying within the Angular universe.
  98
  99 There are two basic ways to do this:
 100
 101  * Avoid global variables/functions
 102  * Avoid referencing DOM elements (outside of Angular directives).
 103
 104 With these rules in place, you're pretty much forced to ask, "what would
 105 Angular do?"
 106
 107 Getting Help
 108 ^^^^^^^^^^^^
 109
 110 There are numerous online resources, including tutorials, videos,
 111 and documentation for AngularJS (and Bootstrap).  Compared to Dojo,
 112 AngularJS has a much more visible online community presence.  For
 113 example, as of today (2013-12-18) there are 19,803 threads tagged with
 114 "AngularJS" on http://stackoverflow.com/tags[Stack Overflow], compared
 115 with 6,096 tagged with "Dojo".  (This says nothing about the quality of
 116 the questions, of course, only that there are more of them.  It could
 117 be that Angular is more difficult, thus more questions, but my personal
 118 experience with Dojo suggests otherwise).  This is especially telling
 119 when you consider that Angular is about half the age of Dojo and has
 120 much fewer features.
 121
 122 Practically every challenge I've encountered with Angular was resolved
 123 with a quick Google search.
 124
 125 Comprehensive Support for Internationalization / Localization
 126 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 127
 128 Much like the HTML and CSS templates, the prototype uses the same i18n
 129 structure as the TPAC.  All strings are defined in the templates and
 130 are thus translated via the TPAC-standard .po file process.
 131
 132 Two Items of Note
 133 ^^^^^^^^^^^^^^^^^
 134
 135  * There is one example of dynamic (key-based) string use, described
 136    http://yeti.esilibrary.com/dev/pub/web-staff-log.html#_i18n_exeriment[here]
 137  * Angular also supports a pluralization directive, which gives us the
 138    opportunity to apply dynamic plurilization.  There is an example of
 139    this http://git.evergreen-ils.org/?p=working/Evergreen.git;a=blob;f=Open-ILS/src/templates/staff/cat/bucket/record/t_bucket_info.tt2;h=1adee8c5b7fa1d0508d345a03bc383b7f9816f82;hb=refs/heads/collab/berick/web-staff-proto[here (see: ng-pluralize)]
 140
 141
 142 Accessibility / Screen Reader support
 143 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 144
 145 Browser-based applications have access to a number of accessibility
 146 features out of the box, like true global font scaling, page zooming,
 147 search-in-page, full-text history searching, and broad support for
 148 assistive technology software, like screen readers.
 149
 150 Ensuring that the application is developed in such a way that all such
 151 features may be used to their fullest potential is up to us.  The
 152 prototype takes simple steps, like applying labels, titles, alt tags and
 153 attributes as necessary, but there are larger tasks to address before
 154 full-blown development ensues.  For example, reviewing the CSS to allow
 155 for high-contrast themes, support for cursor-based navigation, and
 156 keyboard shortcuts, to name a few.
 157
 158 Additionally, basic tests were performed against the prototype using
 159 https://addons.mozilla.org/en-us/firefox/addon/fangs-screen-reader-emulator/[Firefox Fangs Screen Reader Emulator].  Fangs produced the expected output, in as much as it
 160 was able to produce the correct textual values in the expected structure,
 161 but the interface would clearly benefit form further community review and
 162 live screen reader testing, etc. as we look ahead to designing the best
 163 information structure and flow for assistive software.
 164
 165 Quality Assurance Testing
 166 ~~~~~~~~~~~~~~~~~~~~~~~~~
 167
 168 Unit test components live in the repository under Open-ILS/tests/staffweb/.
 169 The basics are described in the
 170 http://yeti.esilibrary.com/dev/pub/web-staff-log.html#_2013_12_13_unit_tests_with_angularjs_karma_jasmine[web log entry].
 171
 172 TODO Items
 173 ^^^^^^^^^^
 174
 175 Investigate end-to-end live testing, as this is likely the only way to
 176 provide automated testing for most of the code.
 177
 178 Mobile / Responsive Design Best Practices
 179 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 180
 181  * The prototype uses Bootstrap CSS, which is designed specifically for
 182    supporting mobile-friendly UIs, for the vast majority of CSS.
 183  * All layout is div (grid) based, using Bootstrap column definitions for
 184    mobile flow.
 185  * Some data is represented with tables, as they naturally perform better
 186    than divs at displaying tabular data.  However, the future of such
 187    tables is unclear.  It's possible they will be replaced with more
 188    feature-rich, div-based tabular structure.
 189  * The interfaces are not designed specifically to look great on mobile
 190    devices.  However, UIs which need to be mobilized, should be much
 191    simpler to modify than non-Bootstrap UIs
 192  * I have confirmed that the UIs work on my Android phone.  Some UIs look OK,
 193    but any UIs we wish to make truly mobile-friendly would need additional
 194    work.
 195
 196 Ease of Local Customization
 197 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 198
 199 Customization of the staff prototype works much like the TPAC.  It
 200 uses override-able Template Toolkit templates and template-driven CSS.
 201 Additionally, with the use of AngularJS for template content, it is
 202 considerably easier to customize the templates, because the link
 203 between the script and the templates is less strict than with traditional
 204 dynamic HTML.
 205
 206 For example, AngularJS does not rely on the existence of elements, it
 207 only responds to the content it encounters.  If an HTML element is
 208 removed or fails to be added as part of an upgrade, the lack of the
 209 element will not break page rendering.
 210
 211 [source,html]
 212 -----------------------------------------------------------------------------
 213 <!-- old school -->
 214 <div id='username'><div>
 215 <!-- this DIES if <div..> is not present -->
 216 <script>$('username').innerHTML = "peggysue"</script>
 217
 218 <!-- angular -->
 219 <div>{{username}}</div>
 220 <!-- all is well -->
 221 <script>$scope.username = 'peggysue'</script>
 222 -----------------------------------------------------------------------------
 223
 224
 225 Consistent Look and Feel Across Interfaces
 226 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 227
 228 Bootstrap CSS classes are used wherever possible.  Very little local CSS
 229 was created.  The local CSS we do have is template-driven, like the TPAC.
 230 Similarly, Bootstrap versions of standard HTML elements (e.g. <input>)
 231 are used across all UIs for visual consistency.
 232
 233 Prototype Testing
 234 -----------------
 235
 236  * The prototype can be installed by installing the
 237 http://git.evergreen-ils.org/?p=working/Evergreen.git;a=shortlog;h=refs/heads/collab/berick/web-staff-proto[Evergreen Working Branch]
 238    and modifying the Apache configuration to match the samples, also
 239    in the branch.
 240  * My dev server is available for light testing as well:
 241   ** https://bill-dev2.esilibrary.com/eg/staff/login?ws=BR1-jupiter
 242   ** username: admin; password: demo123
 243  * 'NOTE': The current CSS is set to cause the screen to break into the
 244    vertical mobile flow at or below around 970px in width.  This may be too
 245    aggressive, particularly since we are not primarily targeting mobile
 246    devices.  The breakpoint can be modified.
 247  * Known Issues
 248   ** The record bucket UIs use the reporter simple record extracts for
 249      bibliographic record display.  This is done to more easily support
 250      sorting and paging and to speed up data retrieval.  This causes two
 251      notable issues:
 252      *** The data and column labels are not as friendly as they could be
 253          (e.g. "Title Proper (normalized)")
 254      *** Buckets with duplicate bib records have some issues with paging.
 255      *** The solution to these issues (and generally, how we wish to fetch
 256          and display bib records going forward, since it's important that
 257          we stop using the old-style MVR's) depend on the resolution of
 258          https://bugs.launchpad.net/evergreen/+bug/1251394[LP1251394 Metabib Display Fields]
 259
 260 ////
 261 vim: ft=asciidoc
 262 ////