web staff : log templates (in progress)

Signed-off-by: Bill Erickson <berick@esilibrary.com>

diff --git a/web-staff-log.txt b/web-staff-log.txt
index e059fcd..49949d2 100644 (file)
--- a/web-staff-log.txt
+++ b/web-staff-log.txt
@@ -785,6 +785,132 @@ egNet.request(service, method, params).then(
 For the full technical rundown, see also 
 http://docs.angularjs.org/api/ng.$q[Angular $q Docs].
 
+2013-12-06 Template Cornucopia
+------------------------------
+
+Using Angular on top of Template Toolkit gives us lots of options for
+managing templates. TT lets us INCLUDE (etc.) shared templates on the 
+server.  AngularJS lets us ng-include (etc.) both inline templates
+(i.e. delivered within the main document) and lazy-loaded templates,
+fetched as needed from the server.
+
+When to use each approach comes down to how each template is used in the
+application.  Is it needed on page load?  Is it needed on every page?
+Is it needed often, but not on page load?  Is it needed rarely?  You
+have to weigh the cost of adding the template contents into the main
+page body (does it add a lot of bytes?) to the cost of (potentially)
+having to fetch it over the network as a separate document.
+
+Some examples:
+
+Classic TT Template
+~~~~~~~~~~~~~~~~~~~
+
+In the prototype, I'm loading the navigation template (t_navbar.tt2)
+within the base document, i.e. the document used as the base template
+for all top-level index files.
+
+[source,sh]
+-----------------------------------------------------------------------------
+[% INCLUDE "staff/t_navbar.tt2" %]
+-----------------------------------------------------------------------------
+
+I'm doing this because the navbar is used on every page.  It makes no 
+sense to load the template as a separate file from the server, because
+that just increases the network overhead.
+
+Inline Angular Template
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Modal dialogs in Angular have to be represented as separate, addressable
+Angular templates.  To give a chunk of HTML an "address", it can be
+inserted into a <script> block with an ID and a type of "text/ng-template".
+
+[source,html]
+-----------------------------------------------------------------------------
+<script type="text/ng-template" id="uncat_alert_dialog">                       
+  <div class="modal-dialog">
+    <div class="modal-content">
+      <!-- ... content ... -->
+    </div>
+  </div>
+</script>
+-----------------------------------------------------------------------------
+
+The modal dialog is then invoked like so:
+
+[source,js]
+-----------------------------------------------------------------------------
+// typically, templateURL refers to a (duh) URL, but inline
+// templates can be loaded by ID.
+$modal.open({templateUrl : 'uncat_alert_dialog', controller : [...]}); 
+-----------------------------------------------------------------------------
+
+****
+$modal is an angular-ui-bootstrap service.  It's not part of core AngularJS.
+****
+
+Lazy-Loaded Angular Template
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These behave much like inline templates, except the template file is 
+fetched from the server as needed.  
+
+To change the inline template example above into a lazy-loaded template,
+move the template to it's own web-accessible file:
+
+[source,html]
+-----------------------------------------------------------------------------
+<!-- create a new file at circ/checkin/t_uncat_alert_dialog.tt2 -->
+<div class="modal-dialog">
+  <div class="modal-content">
+    <!-- ... content ... -->
+  </div>
+</div>
+-----------------------------------------------------------------------------
+
+Then load the file by URL instead of ID.
+
+[source,js]
+-----------------------------------------------------------------------------
+$modal.open({
+    templateUrl : './circ/checkin/t_uncat_alert_dialog', 
+    controller : [...]
+}); 
+-----------------------------------------------------------------------------
+
+Templates All The Way Down
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Finally, here's an example where TT and Angular templates are used 
+together to deliver a modal dialog.
+
+staff/parts/alert_dialog.tt2 is a TT template for modeling a simple
+alert dialog, whose text content is passed in by the containing template.
+As before, to manage the dialog in Angular, it needs an address, so we
+insert the contents of the TT template into an Angular template script.
+
+[source,html]
+-----------------------------------------------------------------------------
+<script type="text/ng-template" id="uncat_alert_dialog">                       
+[% 
+    INCLUDE 'staff/parts/alert_dialog.tt2' 
+    dialog_body = l('Copy "{{args.copy_barcode}}" was mis-scanned or is not cataloged') 
+%]   
+</script>
+-----------------------------------------------------------------------------
+
+Note that this is kind of a contrived example.  In the long run,
+these types of reusable template chunks will likely live in Angular
+directives, which allow you to embed templates in the JS and create new
+HTML elements.  (Imagine an <alert-dialog> directive).  Once we resolve
+the best i18n approach for such dynamic UI components (I have some
+thoughts), this will probably be the better approach for these.
+structure.
+
+Given a little time and experimentation, I believe we can find some
+reasonable guidelines on how and when to use each approach.
+
 Future Topics...
 ----------------