[Freeipa-devel] webUI code restructuring [wall of text, diagrams, ... you've been warned!]

[Dmitri Pal]

Pavel Zuna wrote:
> Last week I started working on integrating the jQuery UI and jQuery
> BBQ libraries into the project. I played around with them a little bit
> and it turned out, that they are really great and bring a lot of value.
>
> jQuery UI is a library of widgets like tabs, dialogs, tree views and a
> lots of other cool stuff.
>
> jQuery BBQ is a plugin for URL query string manipulation. It's main
> advantage to us, is that it enables to get/push states (URL fragment
> changes). This means that we don't have to reconstruct the whole state
> every time. It is also friendly to the Back button and other standard
> features of internet browsers.
>
> Both libraries are mature and easy to use.
>
> At first, I though "OK, that's cool! I'll just rewrite the navigation
> file and we're set." In the end, I had to rewrite almost everything
> due to not very well defined interfaces and dependencies. It took me
> more than a week including the week-end, but I had one of those
> creative blasts and I had fun doing it. :)
>
> I thought this is a good opportunity to restructure the webUI code. We
> are at the point were we've identified a great deal of emerging
> patterns in the code and we aren't too far yet. It was only about 2000
> lines or so.
>
> Since I'm probably going back to IPA backend work with Rob in the
> upcoming weeks, I thought it would be nice to reach a certain
> milestone in the webUI. This is my shot at it.
>
> Anyway, here's the design I propose (and have already implemented, so
> that you can see the benefits for yourselves):
>
> Take a look at the diagram I attached to this mail.
>
> Basically I split the code into two parts. One specific to our project
> and one with re-usable code, that goes on top the of IPA framework
> (ipalib; plugable architecture and all that). Module dependencies
> (arrows with holes in them) and roles are now clearly defined.
>
> I'm going to create another diagram depicting the code flow for better
> understanding.
>
> I'm also going to privately send everyone on the team a link to a live
> demo. I don't feel like it should be on this public list. You can of
> course checkout the whole code there.
>
>
> Now, how does the code work and how do we use/modify it for feature XYZ?
> ------------------------------------------------------------------------
>
> Everything is tied together in the webui.js file. This file includes
> basically only two functions and a definition list used to generate
> tabs. The functions are the application entry point (the document
> ready event handler), where all initialization is performed, and the
> "main loop" (the document hashchange event handler) used to track
> changes in the state of the webUI. The definition list contains a list
> of tabs and callbacks to generate their content.
>
> Callback for generating tab content take only one parameter: the div
> that represent the tab content. They shouldn't care about anything
> else than their own tab! The div should be enough to identify
> everything, that's required (for example what kind of IPA business
> object is handled there).
>
> The only callback currently used is the `ipa_entity_setup` function
> from entity.js. It is a generic wrapper, that takes information from
> entity specific files (user.js, group.js, ...) + metadata and uses it
> to create facets. It basically glues functionality of all CRUD widgets
> files.
>
> The entity specific files are the place to make modifications like
> adding/removing attributes to an object, change the order of
> attributes, change what attributes are listed in a search, generate
> special input elements for attributes that require them (attribute
> callbacks).
>
> Some examples:
> * We need a new attribute for object X, that displays a calendar for
> selecting dates.
> => add attribute to details definition list of object X, define
> attribute callback to generate the calendar
> * We need a new field to be displayed in the dialog when adding object Y.
> => add attribute to add definition list of object Y, define attribute
> callback
> to generate the field if it has some special requirements
> * We need to handle a new state in the webUI
> => Modify the "main loop" in webui.js
> * We need a whole new tab with something different that what we have now
> => add tab to navigation definition list in webui.js, create a
> callback, that
> generates what's supposed to be the tabs content
>
> And so on...
>
> Everything is customizable, but the defaults are good enough for 90%
> of cases.
>
>
> What is a webUI state?
> ----------------------
> It's a certain combination of values in the URL fragment (that's the
> portion of URLs after the # sign). Using the URL fragment saves us
> from reloading the web pages (and all those bulky javascript files)
> every time the user does something. We're going fully AJAX.
>
>
> How to change a webUI state in the code?
> ----------------------------------------
> Before we always had to reconstruct the whole URL. Doing ugly things
> like:
> document.location = document.location - fragmet + something +
> '&thisandthat=' something_else + // and more
>
> Now we can just do:
> $.bbq.pushState({something: somevalue});
> And to retrieve:
> something = $.bbq.getState('something');
>
> Much nicer and we don't have to worry about overwriting states by
> mistake.
>
>
> How does this whole thing integrate with what we have in master?
> ----------------------------------------------------------------
> If we decide to adopt it, I'm going to create a patch that goes over
> the current master branch. It shouldn't be a big problem; a matter of
> 2-3 hours of work.
>
> I already integrated some of Adam's latest patches (associations,
> automatic sampledata retrieval, ...).
>
>
> So is this just code restructuring or does it have some new features?
> ---------------------------------------------------------------------
> It has better transisions between webUI states. All the advantages of
> jQuery UI and jQuery BBQ.
>
> We have nice dialogs for adding new objects.
>
> The content of different tabs is independent. You can click on Group,
> check something and click back to user without loosing the user tab
> state.
>
> All webUI states are bookmarkable! You can save your session by simply
> creating a bookmark.
>
>
> What to do, if this is adopted?
> -------------------------------
> I think there will be 4 main areas, where most work will be distributed.
>
> - It's almost time to add CSS styles to make the UI look usable
> - Callbacks for all kinds of special attributes and adding new IPA
> objects to the UI
> - Maintenance of core scripts
> - Adding completely new features like work-flows, wizards,
> localization, ...
>
> If I'm to go back to IPA backend work with Rob in the upcoming weeks.
> I suggest we let Andy handle the CSS, callbacks and adding new objects
> (at least for now). Adam could work closely with the UXD team on new
> features. I don't want to drop the UI work completely, so I could take
> maintenance and helping out with whatever is needed.
>
> This is just a suggestion btw.
>
>
>
> Enough text. Waiting for comments. :)
>
> Pavel
>
> ------------------------------------------------------------------------
>
Very impressive!

-- 
Thank you,
Dmitri Pal

Engineering Manager IPA project,
Red Hat Inc.


-------------------------------
Looking to carve out IT costs?
www.redhat.com/carveoutcosts/