Designing a new UIO API

[Antranig Basman]

Hi, Justin and Anastasia - thanks for preparing this page, this looks like a great start. Here are a few 
areas where the work can be extended in order to cover more of the cases we will encounter -

i) There is too sharp a distinction between things which are "built-in" and things which are provided by 
integrators. We anticipate that in real life, almost ALL practical uses of UIO will be in the scenarios 
labelled under the headings "adding settings" and "removing settings". Therefore we need a smoother bridge 
than the one provided between "out of the box" and "by an integrator".

Whilst the point "It should not require knowledge of the Framework" is admirable in principle, in practice 
it is impossible to deliver on since the main value in providing the framework is to aid integrators! But of 
course we should strongly minimise the knowledge required in order to get simple configurations of UIO off 
the ground. In practice I think the route proposed, via the "usePrepackagedSettings" flag is not a viable 
compromise, since it gives too much privileged status to the so-called "out of the box" configuration and 
sets a bar which cannot easily be achieved by integrators wishing to create their own "out of the box" 
configurations which they wish to appear "just as good" as anything produced by the framework. I'll refer to 
this point again later - in the meantime, I think the use of some grade names in the "out of the box" 
configuration is unavoidable. We need to set a "best practice" both for integrators (3rd parties) as well as 
users of integrators (4th parties) which is easy to achieve for everyone.

So on point ii) It should not require knowledge of subcomponents in the UIO component tree is clearly 
desirable, but right now this is only achievable for "out of the box". The route proposed for "integrators" 
in the "add settings" and "remove settings" sections clearly requires knowledge of the subcomponents not 
only by the integrators (3rd party) but the users of integrators (4th party) - this is undesirable, and we 
should advertise the means to integrators how they can remove the need for knowledge of subcomponents to 4th 
parties.

iii) The proposed API currently makes no mention to one of the most important areas of configuration, which 
is currently being worked on in Yura's branch - how it is that integrators define and configure the default 
values for settings, both "out of the box" and other - Yura could do with some guidance as to what this 
configuration is expected to look like.

I'd like to see this page organised into 3 sections, broadly modelled on the ones that are there already -

a) What to do to make use of the "out of the box" UIO (2nd parties)
b) What an integrator can do to add and remove settings, or configure a completely fresh UIO (3rd parties)
c) What the resulting API structure looks like to users of b) (4th parties)

Ideally the page should highlight how very similar the resulting API looks between parts a) and c) - that 
is, "no privileged status for 1st parties" (that is, us).

In terms of details of the settings that will go in section b) -

1) I and I think most of us prefer the use of new grade names rather than the use of demands blocks. The new 
framework features (FLUID-4916 etc. ) make it much easier to achieve effects this way with less of the 
complexity involved with demands blocks, which should be reserved for complex integration problems (like 
those suffered by 5th parties etc.) - so the section "adding new settings" should be rewritten with this in 
mind. The current "out of the box" configuration is being packaged as a set of grade names and this should 
be surfaced in the section a) descriptions as well (so that it can become similar to section c).

2) The answer to the query in the comment about template loading is the restrictions imposed by the lack of 
the asynchronous ginger world, described in FLUID-4982. Until this work is done, all the prerequisites of a 
component need to be available AT the moment it begins to instantiate, hence the reason its templates can't 
be loaded by itself. Even assuming FLUID-4982 is not resolved at the time we next make a delivery of 
UIOptions, we should be able to ease this work by means of delivering suitably coordinated gradeNames.

As an overall strategy, I see in the various branches that have been either approved or are still in the 
pipeline, the "ant sides" have individually been packaging the "out of the box" configuration as separate 
gradeNames such as "fluid.uiEnhancer.defaultActions" etc. - all that we need in order to get as close as 
necessary to the "one stop shop" for UIO which is aimed at by the "usePrepackagedSettings" flag is to 
construct a new "overall grade" which ties together all of the 3 default grades (as well as the template 
URLs they require) into a single package which can be applied by the user (2nd or 4th party) in a single place.

Thanks,
Antranig

On 02/05/2013 13:52, Cheetham, Anastasia wrote:
>
> Justin and I have updated the UIO API proposal wiki page with code snippets illustrating the proposed API:
>
>      http://wiki.fluidproject.org/display/fluid/Designing+a+new+UIO+API
>
> Please have a look and provide your feedback.
>