[Freeipa-devel] WebUI documentation

[Adam Young]

On 06/11/2015 01:58 PM, Drew Erny wrote:
> I'm looking for documentation that provides a broader overview of the 
> way the WebUI fits together and works. I have the source, of course, 
> and I've been through Petr Voborni's documentation found at 
> https://pvoborni.fedorapeople.org/doc/. That documentation explains 
> some narrower concepts (like how navigation fits in, or what a facet 
> alone does), but I'm having trouble finding documentation that broader 
> and more general in scope. I'm looking for something that will show me 
> how the machinery of the WebUI works, what the layers of the 
> application look like and do, etc. Does something like this exist?
>
Probably not to the level you are asking.  If Peter didn't write it, it 
does not exist.  Most of the design discussions took place on the 
mailing list back when I was on the projects...fourish years ago now.

There was some significant reworking since I've been gone, so I don't 
want to tell you anything that is out-and-out-wrong, but I think my 
understanding if it is still fairly accurate.

I was a Javascript neophyte when the project started, and there was a 
lot of advice going different directions.  We started off by reading 
Javascript, The Good Parts, and the approach in that book should be 
apparant thoughtout the code base...I'm not saying I would do it that 
way now.  Actually, just imagine me saying that expression on loop 
throughout.  Web Dev today has come a long way in a short while.

The CLI and Web API was already established when we started.  The CLI 
used XML RPC, but someone had gotten JSON RPC to work.  Aside from that, 
the two interfaces would be using the same mechanism to talk to the 
server;  no server side scripting, and not security issues in the client 
that were not on the web and vice-versa.   The application is very 
driven from the LDAP schemas for the objects it is managing.  The 
challenge on the Web UI was to make it consumable by a new user.

We wanted to take the values from the RPC as the starting point. Because 
we got things in JSON RPC, we had to transform them via Javascript into 
even the most basic of HTML.  The goal was that the displays would be as 
declaritive as possible.  Any field could be shown in just a simple text 
input if editable, and as a text label if not.  We'd make heavy use of 
tables for the list pages and Definition Lists for the others, with all 
Layout in CSS.


AJAX calls to the JSON-RPC  server starting with the ones necessary to 
do layout and figure out which parts of the site to show a user.   A 
huge METADATA call told us pretty much everything about every field of 
the application.  Since all the objects were stored in LDAP, each field 
has an indicator saying if it is writable or not.  The default, though, 
was to not have a read-only and a writable view;  if you can edit a 
field, it was shown as editable, with an indicator st when the edited 
value was out of sync with the original, and a reset button on both the 
field and the facet level.


At first there were two main facets;  search/list and details. With  
things like groups, we came up with a third, which was for managing 
associations.  Some other use cases were more appropriately handled with 
dialogs, such as adding a new entity.  The add use cases attempted to 
capture only the essential information to create the new entity, and 
then give the user the ability to add another, or edit the one they just 
added with a single click.  The goal was to minimize clicks to get a job 
done.



I'd recommend looking at a simple entity, like policy, which handles the 
kerberos ticket policy.