Allow the initial state of the addressbook to be encoded in a URL

(In [14240]) Branching to 'initial-addressbook-state-2396'

The motivation for this is that Blendix wants to have "Edit" links all over the place alongside person names, which take you to the address book with the edit form for that person loaded. The solution implemented in initial-addressbook-state-2396 extends OrganizerFragment to be aware of urls structured like:

organizer-url/person-name/initial-state

where initial-state is currently only allowed to be "edit". So e.g. organizer-url/pjd/edit would result in the person called "pjd" being initially selected, and his edit form being shown. The xmantissa.people.ORGANIZER_VIEW_STATES constants may seem like overkill, especially since there is only one constant at the moment, but it was the least awkward, most extensible way I could think of. Client code would do:

organizer.urlForViewState(person, ORGANIZER_VIEW_STATES.EDIT)

to get a url for editing person.

The overall idea here is great, but I've got a lot to say about it because I've given this general idea some thought before.

URL-structure-wise, I'd strongly prefer URLs structured like organizer-url?select-person=bob&initial-state=edit. Adding slashes makes relative links break, requires nevow to do extra lookup work, makes it difficult for different systems to cooperate, makes changes more difficult (what if you want to add a third argument?) and most of all, doesn't really reflect the nature of what's going on.

In this case, you really should be invoking the entity at organizer-url but giving it some parameters as to how to customize itself, not invoking a sub-resource of it. I'd rather not instantiate a new organizer fragment for each step - passing constructor arguments in the client makes sense, because it's being created with a certain hint, but on the server, it ought to be a mutation method rather than the constructor.

ORGANIZER_VIEW_STATES does seem a little like overengineering, but I don't mind. It's hardly an unreasonable amount of work to prepare for future expansion in that way ;). If I had a nickel for every ad-hoc enum in Python though... we should really add something consistent in Epsilon to make those easier to work with and debug. (Not really germane to this branch, even as a separate ticket, just sayin'.)

Reverting the change in ScrollTable.js doesn't cause any tests to fail. It should have a test of its own, and so should PersonScroller.loaded.

• The new test in Mantissa/xmantissa/js/Mantissa/Test/TestRegionModel.js, test_loadedDeferred, should document when the Deferred is called back.
• Passing arguments like this in URLs isn't very great. I have some general ideas for a better implementation (if the URL is the only place we can reliably keep state, then we should just keep a key into a state tracking object there, and this should all be abstracted away from application-level code: passing parameters should be simple, it shouldn't involve generating or examining an URL), but maybe we don't want to pause and implement that now. In any case, this is the one and only thing which does this in the application now, and I am certainly in favor of not generalizing prematurely.
  • The query parameters accepted/required by the address book fragment should be documented prominently somewhere.
  • A note about how this isn't a generally desirable approach should be added to the code, on both sides, so that if we do run into this use-case again, this isn't mistaken for a template of the correct way to do it.
  • GenericNavigationAthenaPage?.beforeRender doesn't return anything - Page.beforeRender can return a Deferred which delays rendering of the rest of the page: if this isn't supported on INavigableFragment.beforeRender (which doesn't exist?) then it should be documented.
  • urlForViewState doesn't quote viewState. I guess it doesn't have to now, since edit doesn't need quoting. It'd be nice if it used an URL object to build up that URL too, since strings are lame.

The comment in urlForViewState is missing a word or two - encoding state like this a url.

OrganizerFragmentBeforeRenderTestCase could use an in-memory Store (pass filesdir=self.mktemp() instead of self.mktemp()) and run less slowly.

Otherwise looks good. No need for re-review.

(In [14320]) Branching to 'initial-addressbook-state-2396-2'

(In [14324]) merge initial-addressbook-state-2396-2. allows the initial state of the address book to be encoded in its url, and includes a method on Organizer for generating these urls. Also implements beforeRender notification for live fragments wrapped by GenericNavigationAthenaPage?. author: moe, reviewer: exarkun, glyph. closes #2396

(note #2518)

(#2522 → #2518)