From: Bill Erickson Date: Wed, 18 Dec 2013 16:13:55 +0000 (-0500) Subject: web staff: after-action report, cont. X-Git-Url: https://old-git.evergreen-ils.org/?a=commitdiff_plain;h=3bae9f767648ce60ddc6a4becf0535fc9583f02a;p=working%2FEvergreen.git web staff: after-action report, cont. Signed-off-by: Bill Erickson --- diff --git a/web-staff-report.txt b/web-staff-report.txt index 51f1b2e41b..c593b5c4b5 100644 --- a/web-staff-report.txt +++ b/web-staff-report.txt @@ -1,5 +1,8 @@ Browser-Based Staff Client After-Action Report ============================================== +:Author: Bill Erickson +:Email: berick@esilibrary.com +:Date: 2013-12-18 References ---------- @@ -57,7 +60,7 @@ TODO Items * Improved support for streaming and paging need to be added to some API calls * New API calls could be developed to better deliver targeted data sets to - reduce the overrall number of API calls. + reduce the overall number of API calls. * To leverage streaming responses (which can reduce the number of API calls, in some cases by a wide margin, and allow long-running calls, like Vandelay imports), support for WebSockets is still suggested. @@ -68,6 +71,8 @@ Standards Compliance * Prototype developed for and tested with Chrome and Firefox. ** Incidentally, also confirmed to work on Safari and Opera. + * No exotic components were used. + Ease/Speed of Development ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -80,15 +85,15 @@ Learning AngularJS (and Bootstrap) is neither easy or terribly difficult, but it does take some getting used to, especially if you are accustomed to writing code for the existing Dojo-driven Evergreen interfaces. However, once you're used to it, building interfaces is -considerably easier in Angular, basically because there is much less +considerably easier in Angular, basically because there is less code to write. Probably the biggest hurdle for new developers will be resisting the urge to fall back on manual DOM manipulation and bypassing the Angular environment -altogether, when it suits his/her needs. A mix of Angular and non-Angular -code will be difficult to support in the long run. There are verying levels +altogether, when it suits his/her needs. This should be avoided, as a mix of Angular and non-Angular +code will be difficult to support in the long run. There are varying levels of Angular code purity and the more Angular-correct the code is, the easier -unit testing, etc will be, but more important than Angular perfection is +unit testing, etc. will be, but more important than Angular perfection is simply staying within the Angular universe. There are two basic ways to do this: @@ -99,31 +104,89 @@ There are two basic ways to do this: With these rules in place, you're pretty much forced to ask, "what would Angular do?" +Getting Help +^^^^^^^^^^^^ + +There are numerous online resources, including tutorials, videos, +and documentation for AngularJS (and Bootstrap). Compared to Dojo, +AngularJS has a much more visible online community presence. For +example, as of today (2013-12-18) there are 19,803 threads tagged with +"AngularJS" on http://stackoverflow.com/tags[Stack Overflow], compared +with 6,096 tagged with "Dojo". (This says nothing about the quality of +the questions, of course, only that there are more of them. It could +be that Angular is more difficult, thus more questions, but my personal +experience with Dojo suggests otherwise). This is especially telling +when you consider that Angular is about half the age of Dojo and has +much fewer features. + +Practically every challenge I've encountered with Angular was resolved +with a quick Google search. + Comprehensive Support for Internationalization / Localization ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -TODO +Much like the HTML and CSS templates, the prototype uses the same i18n +structure as the TPAC. All strings are defined in the templates and +are thus translated via the TPAC-standard .po file process. + +Two Items of Note +^^^^^^^^^^^^^^^^^ + + * There is one example of dynamic (key-based) string use, described + http://yeti.esilibrary.com/dev/pub/web-staff-log.html#_i18n_exeriment[here] + * Angular also supports a pluralization directive, which gives us the + opportunity to apply dynamic plurilization. There is an example of + 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)] + Accessibility / Screen Reader support ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -TODO +* Use of labels, titles, alt text, etc. as necessary. +* Basic tests were performed with +https://addons.mozilla.org/en-us/firefox/addon/fangs-screen-reader-emulator/[Firefox Fangs Screen Reader Emulator] + +Of all the dev goals, this is the one I have the least confidence in +for the prototype, simply because of my lack of experience. Further +research is under way, but the code would benefit from community review, +live screen reader testing, etc. before any more development occurs. Quality Assurance Testing ~~~~~~~~~~~~~~~~~~~~~~~~~ -TODO +Unit test components live in the repository under Open-ILS/tests/staffweb/. +The basics are described in the +http://yeti.esilibrary.com/dev/pub/web-staff-log.html#_2013_12_13_unit_tests_with_angularjs_karma_jasmine[web log entry]. + +TODO Items +^^^^^^^^^^ + +Investigate end-to-end live testing, as this is likely the only way to +provide automated testing for most of the code. Mobile / Responsive Design Best Practices ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -TODO + * The prototype uses Bootstrap CSS, which is designed specifically for + supporting mobile-friendly UIs, for the vast majority of CSS. + * All layout is div (grid) based, using Bootstrap column definitions for + mobile flow. + * Some data is represented with tables, as they naturally perform better + than divs at displaying tabular data. However, the future of such + tables is unclear. It's possible they will be replaced with more + feature-rich, div-based tabular structure. + * The interfaces are not designed specifically to look great on mobile + devices. However, UIs which need to be mobilized, should be much + simpler to modify than non-Bootstrap UIs + * I have confirmed that the UIs work on my Android phone. Some UIs look OK, + but any UIs we wish to make truly mobile-friendly would need additional + work. Ease of Local Customization ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Customization of the staff prototype works much like the TPAC. It -uses overridable Template Toolkit templates and template-driven CSS. +uses override-able Template Toolkit templates and template-driven CSS. Additionally, with the use of AngularJS for template content, it is considerably easier to customize the templates, because the link between the script and the templates is less strict than with traditional @@ -153,6 +216,8 @@ Consistent Look and Feel Across Interfaces Bootstrap CSS classes are used wherever possible. Very little local CSS was created. The local CSS we do have is template-driven, like the TPAC. +Similarly, Bootstrap versions of standard HTML elements (e.g. ) +are used across all UIs for visual consistency. //// vim: ft=asciidoc