Evergreen DokuWiki

Development guidelines for the browser-based staff client interface.

• Note: 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. 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.
• 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.
• Avoid adding items to the controller's $scope that are not needed by the UI. This causes unnecessary overhead.

• 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.
• (Needs discussion) 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.

• 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.
• Use i18n filters for dates and money: e.g.

  <div>{{ due_date | date:'shortDate' }}</div>

  • The exact filter options may change w/ settings, etc.

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