[Freeipa-devel] Development approach.

[Adam Young]

I've attempted to document what I think our approach should be for the 
FreeIPA Web UI.  THe document is here:

https://fedorahosted.org/freeipa/wiki/UIApproach


For those adverse to clicking links, I'll inline it below as well.  
Please comment on specific section.

This page is just a draft, pending approval of the rest of the FreeIPA 
team.

The general approach to Web UI development for IPA springs from the fact 
that Javascript is a fundamental aspect of web programming. Instead of 
using a Server side scripting language to drive development, and then 
attempting to shoehorn Javascript into that language, we are using 
Javascript as the primary programming language of the site. The command 
line interface (CLI) has already specified a large body of xml-rpc based 
APIs. We will focus on the Web UI and using same API, called via 
JSON-RPC, a format somewhat friendlier to the Javascript language.

The current state of the art in Web design has embraced a concept called 
Progressive Enhancement (PE). Under Progressive Enhancement, a site is 
first developed with no Javascript and minimal Cascading Style Sheet 
(CSS) support. The goal is to build a fully functioning site that works 
on the widest away of browsers, with the trade off that it will have 
only the most rudimentary of features. While we are diverging a little 
bit from this approach, our default requirement for a minimal subset of 
Javascript will support all major browsers, and has been tested on such 
a minimal browser as is supported on the Palm Pre wireless device. From 
this baseline, we will then follow the recommendations of PE, testing 
the browsers for any capabilities we will require for features such as 
auto-complete, tabbed browsing, and enhanced text editing. This approach 
should maximize the number of browsers capable of using the web UI.

The landing page should have a simple name, such as *ipa.xhtml*. The 
file requires no servers side scripting to render. Instead, all dynamic 
content, including navigation, is driven by Javascript in the browser.

Each of the subordinate pages are currently implemented as HTML 
fragments that are included into the main page using

    $('#content').load(bodycontent);

where content is the id for the DIV tag that contains the main content 
area, under the menu, and *bodycontent* is a string that names the page 
to be loaded.

The page fragments are not in themselves valid xhtml, as that would 
require additional parsing in order to get them to render. They have the 
extension of .inc. For the most part, they are completely static HTML, 
coupled with a simple script tag that knows how to populate the 
fragment. Because common functions should be shared across multiple 
pages, the main body of work should not be inside the page fragments. 
Constant refactoring should occur to keep the fragments as light as 
possible.

The menu for the site is a custom component based on the concept of a 
dynamic site map. In short, the site map is a tree structure, where each 
node maps to a page. This tree is used to generate the tabs that are the 
navigational structure of the site, as well as the links on these tabs. 
The nodes of the site map May be hided or reordered based on the role of 
the logged in user. The links map to the page fragments discussed above.

IPA has a plugin architecture that allows the site deployer to customize 
the objects managed by IPA. This poses an interesting challenge for the 
UI. For basic functionality, it is relatively simple to specify the set 
of fields presented for managing one of the base objects (user, host, 
group). Once the user starts modifying the field set, we have several 
potential scenarios.

1. The user may add additional fields that they want to see on the web 
UI. 2. The user may modify one of the existing fields such that default 
validation rules no longer hold true 3. The user may remove fields from 
the objects.

A first approximation would be to generate the UI based on the Plugin 
Data itself. The drawbacks of this approach are: splitting UI 
development over two languages, and forcing the CLI to conform to rules 
that may only make sense for the web UI. In addition, this approach was 
attempted in the past, and ended up with a very "data drive, CRUD style" 
approach that didn't map to the work flow users really need to make the 
site usable.

We will take a page from the Progressive Enhancement book, and test the 
JSON returned from the server in order to see what values are accepted. 
This will help solve problems 1 and 3 above.

For deleted fields, we can determine if a given field is essential. If 
an essential field has been removed, we will report a meaningful error 
message to the end user, and disable either the entire site, or some 
subset of functionality, based on business rules.

For fields added but not exposed by the UI, we will add a single warning 
message to the log upon first access. After this, we will set a cookie 
in the browser and ignore these warnings, except perhaps to have some 
indicator on the page the there are unhandled fields.

A validation rule is a business rule, and thus spans both the UI and 
business-logic layers. For field that have validation rules that have 
changed, the best approach is to share the validation between the 
browser and the back end scripting language. As such, validation rules 
should be represented in a subset of Regular Expressions supported both 
by the server side language (Python) and by Javascript. The validation 
rules themselves are then exposed via JSON-RPC to the Browser.

For development and unit testing, all content that is fetched from 
JSON-RPC calls can be replaced with canned responses from files in a 
subdirectory named *sampledata*. To switch between sampledata and live 
JSON calls, alternately create or remove a file from the web root 
directory named *ipadebug.js* that contains the single value 
"ipadebug=true". This file is tracked via gitignore so that no-one 
accidentally checks it in. The Makefile that assembles the files from 
the web directories will ignore the files in sampledata. If we wish to 
deploy the sample data files for unit testing purposes, we can always 
create a separate RPM for them that does not get built or deployed be 
default.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/freeipa-devel/attachments/20100628/98abd10c/attachment.htm>