Evergreen DokuWiki

Development guidelines for the browser-based staff client interface.

• This list is under construction. Please remove this message when it seems appropriate.

• Avoid synchronous ajax
  • Stick with egNet, egPCRUD, and $http and you're covered.
• Use PCRUD whenever possible – it's faster.
• Avoid global variables
• 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.
• Use promises
  • Using promises allows Angular to manage the connection between UI models and asynchronous data. egNet, egPCRUD, and $http are all promise-based.
  • Example: managing a group of promises:

    $q.all([ 
      egNet.request(...),  
      egPCRUD.retrieve(...), 
      morePromises, 
      ...
    ]).then(function() { console.log('ALL PROMISES RESOLVED') })

• Cache carefully
  • Be mindful of ever-growing caches
• Build applications of tightly-linked UIs and use routing between them.
• URLs should function whether accessed via routing or direct load. This takes some planning.
  • 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.

• 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.

• 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.

  • [% INCLUDE 'path/to/template.tt2' %]

• When a template is not needed on initial page load, especially rarely used templates, load them on-demand via AngularJS templateUrl.

  • $modal.open({templateUrl: './path/to/template', controller:{}})

• For any grey area, use best judgement.