Browser-Based Staff Client After-Action Report ============================================== :Author: Bill Erickson :Email: berick@esilibrary.com :Date: 2013-12-18 References ---------- * http://yeti.esilibrary.com/dev/pub/techspecs/web-staff-prototype.html[Prototype Tech Specs] * http://git.evergreen-ils.org/?p=working/Evergreen.git;a=shortlog;h=refs/heads/collab/berick/web-staff-proto[Code in Evergreen Working Repository] * http://yeti.esilibrary.com/dev/pub/web-staff-log.html[Development Log] * http://angularjs.org/[AngularJS] * http://getbootstrap.com/[Bootstrap CSS] * http://angular-ui.github.io/bootstrap/[AngularJS for Bootstrap] Prototype Development Goals --------------------------- In addition to basic functionality, a number of specific development goals were listed in the tech specs. Below is a breakdown of how each of these were met and what remains to do for each. Speed / Responsiveness to user actions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * Applications are developed in functional groups. Within each group, page reloads are not required. This allows navigation between tightly-linked functional areas without page reloads, e.g. jumping between the patron items out list and the patron holds list. * All data-fetching server communication runs asynchronously, allowing other browser processing to occur while waiting for responses. This also prevents the possibility of browser lock-up on long-running requests. (See: egNet and egPCRUD). * When possible, batches of data requests are fired at the same time, instead of serially, to maximally leverage browser parallel XMLHttpRequest connections. (E.g. egEnv.load()) * Special care was taken to avoid fetching data from the server until needed, reducing the cost of up-front data loading. * In some cases, primarily in the Record Buckets UI, traditional Perl API calls were replaced with PCRUD calls. PRCUD is much faster than Perl. * The code was implemented to support Javascript minification and it has been confirmed to function correctly. When configured, this reduces page load times. * Apache gzip compression and cache optimizations added to sample Apache configs. These were added because the existing settings were not sufficient to satisfy standard web optimization practices. (See Chrome Audits). Apache configuration cleanup and consolidation should be considered so that other parts of the site get the same benefits. 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 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. 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 ~~~~~~~~~~~~~~~~~~~~~~~~~ **** This is just my opinion. **** 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 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. 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 simply staying within the Angular universe. There are two basic ways to do this: * Avoid global variables/functions * Avoid referencing DOM elements (outside of Angular directives). 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Browser-based applications have access to a number of accessibility features out of the box, like true global font scaling, page zooming, search-in-page, full-text history searching, and broad support for assistive technology software, like screen readers. Ensuring that the application is developed in such a way that all such features may be used to their fullest potential is up to us. The prototype takes simple steps, like applying labels, titles, alt tags and attributes as necessary, but there are larger tasks to address before full-blown development ensues. For example, reviewing the CSS to allow for high-contrast themes, support for cursor-based navigation, and keyboard shortcuts, to name a few. Additionally, basic tests were performed against the prototype using 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 was able to produce the correct textual values in the expected structure, but the interface would clearly benefit form further community review and live screen reader testing, etc. as we look ahead to designing the best information structure and flow for assistive software. Quality Assurance Testing ~~~~~~~~~~~~~~~~~~~~~~~~~ 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * 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 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 dynamic HTML. For example, AngularJS does not rely on the existence of elements, it only responds to the content it encounters. If an HTML element is removed or fails to be added as part of an upgrade, the lack of the element will not break page rendering. [source,html] -----------------------------------------------------------------------------
{{username}}
----------------------------------------------------------------------------- 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. Prototype Testing ----------------- * The prototype can be installed by installing the http://git.evergreen-ils.org/?p=working/Evergreen.git;a=shortlog;h=refs/heads/collab/berick/web-staff-proto[Evergreen Working Branch] and modifying the Apache configuration to match the samples, also in the branch. * My dev server is available for light testing as well: ** https://bill-dev2.esilibrary.com/eg/staff/login?ws=BR1-jupiter ** username: admin; password: demo123 * 'NOTE': The current CSS is set to cause the screen to break into the vertical mobile flow at or below around 970px in width. This may be too aggressive, particularly since we are not primarily targeting mobile devices. The breakpoint can be modified. * Known Issues ** The record bucket UIs use the reporter simple record extracts for bibliographic record display. This is done to more easily support sorting and paging and to speed up data retrieval. This causes two notable issues: *** The data and column labels are not as friendly as they could be (e.g. "Title Proper (normalized)") *** Buckets with duplicate bib records have some issues with paging. *** The solution to these issues (and generally, how we wish to fetch and display bib records going forward, since it's important that we stop using the old-style MVR's) depend on the resolution of https://bugs.launchpad.net/evergreen/+bug/1251394[LP1251394 Metabib Display Fields] //// vim: ft=asciidoc ////