← Back to branch summary

~azzar1/unity/add-show-desktop-key

« back to all changes in this revision

Viewing changes to doc/dev/architecture.rst

  • Committer: William Grant
  • Date: 2010-02-15 02:31:08 UTC
  • Revision ID: grantw@unimelb.edu.au-20100215023108-ga1389krlfdwed08
Add quick docs for the object publisher.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/dev/architecture.rst
349
349
Worksheets
350
350
==========
351
351
 
 
352
 
352
353
Database
353
354
========
354
355
 
355
 
..  TODO: Not yet merged
356
 
    Object Publishing
357
 
    =================
 
356
 
 
357
Object Publishing
 
358
=================
 
359
 
 
360
URLs are resolved with a small IVLE-specific object publishing framework --
 
361
that is, resolution is implemented as traversal through an object graph. The
 
362
framework lives in :mod:`ivle.webapp.publisher`, and has an extensive test
 
363
suite.
 
364
 
 
365
This object graph is constructed by the dispatcher. Any plugin class deriving
 
366
from ViewPlugin will be searched for ``forward_routes``, ``reverse_routes``
 
367
and ``views`` sequences. Everything is class-based -- an object's routes
 
368
and views are determined by its class.
 
369
 
 
370
Forward routes handle resolution of URLs to objects. Given a source object
 
371
and some path segments, the route must calculate the next object.
 
372
A forward route is a tuple of ``(source class, intermediate path segments,
 
373
function, number of subsequent path segments to consume)``, or simply a
 
374
reference to a decorated function (see :mod:`ivle.webapp.admin.publishing`
 
375
for decoration examples). The function must return the next object in the
 
376
path.
 
377
 
 
378
A reverse route handles URL generation for an object. Given just an object,
 
379
it must return a tuple of ``(previous object, intermediate path segments)``.
 
380
This creates a chain of objects and path segments until the root is reached.
 
381
Due to IVLE's lack of a utility framework, reverse routes at the root of the
 
382
URL space need to refer to the root object with the magical
 
383
:mod:`ivle.webapp.publisher.ROOT`. 
 
384
 
 
385
Views are registered with a tuple of ``(source class, intermediate path segments,
 
386
view class)``.
 
387
 
 
388
In all of the above, "intermediate path segments" can either be a single
 
389
segment string, or a sequence of multiple strings representing multiple
 
390
segments.
 
391
 
 
392
.. note::
 
393
   While many applications prefer a pattern matching mechanism, this did not
 
394
   work out well for IVLE. Our deep URL structure and multitude of nested
 
395
   objects with lots of views meant that match patterns had to be repeated
 
396
   tediously, and views required many lines of code to turn a match into a
 
397
   context object. It also made URL generation very difficult.
 
398
 
 
399
   The simple object publishing framework allows views to be registered with
 
400
   just one line of code, getting their context object for free. URL
 
401
   generation now comes at a cost of approximately one line of code per class,
 
402
   and breadcrumbs are easy too. The reduced code duplication also improves
 
403
   robustness.