Documenting how to customize UIO and UIE

[Antranig Basman]

+1 for documenting those things which it makes sense for our users to configure, and which have planned them 
to configure
-1 for documenting those things which it doesn't make sense to configure and/or which our current 
architecture doesn't support easily configuring

We didn't implementing munging for UIEnhancer since its hierarchy is not *very* deep - only 2 levels. Most 
of the options available on the subcomponents there are sensibly configurable.
We implemented munging for UIOptions since its hierarchy is not only very deep but also liquid - the exact 
position of different subcomponents moves about not only between configurations but also during 
implementation work in a way that users shouldn't be expected to predict.

It's a fair assumption that anything which has been munged is something which should be documented.

The "onReady" event present on uiOptionsLoader should be documented, and the other events are private.

Also, anything which is an option (rather than a subcomponent) in UIEnhancer is something which should be 
documented. Including options on its subcomponents.

As a negative point, we are not expecting any of the subcomponent structure itself within UIOptions and 
UIEnhancer to be ordinarily configurable by users. The design of UIOptions and of the framework is not yet 
sufficiently flexible to allow the implementation to successfully adapt to most changes in component 
structure. The only except to this seems to be the settingsStore for UIEnhancer.

Given the bulk of this hierarchy is IoC driven, users *can* muck in and configure anything they want by 
inspecting the defaults and demands configuration for the component - without having to fork or monkey-patch 
our code - but we are not supporting this and they should know that this configuration won't remain stable 
for 1.5. However we should point out to them that this option is there - since if they are at the stage of 
desperation where they are considering forking or monkey-patching, they will be well beyond being influenced 
by considerations of API stability.

Cheers,
Antranig

On 31/08/2011 10:03, Michelle D'Souza wrote:
> Given that we are expecting to overhaul the API for UIO in 1.5, I feel that we should be selective in what we document in 1.4. It seems to me that the top level UIO API is about as deep as we want to go.
>
> I think it would help if I had a little more information about the current situation. Do you know what implementers are configuring now? Any thoughts on what they will likely want to configure right away? Which of the examples you gave cannot be configured in the top level API?
>
> Thanks,
>
> Michelle
>
>
> On 2011-08-31, at 11:08 AM, Cheetham, Anastasia wrote:
>
>>
>> UI Options and UI Enhancer have various options and subcomponents that are technically amenable to configuration. However, we've decided that for 1.4, we are *not* expecting or recommending that integrators actually do any configuration: We want them to just use it out of the box and leave it at that (correct me if I'm wrong, of course).
>>
>> My first question is this:
>>
>> Should we be documenting all the options/subcomponents that could technically be configured, or should we deliberately avoid any mention of anything we *don't* want people to play with?
>>
>> My second question would be:
>>
>> If the latter course is decided upon, which options/subcomponents will we consider "public" (and therefore documented) for 1.4?
>>
>> Here is a starting list of potential customizations that integrators might want to carry out. Which of would we support for 1.4, which not? Are there others we will support, and therefore need to document?
>>
>> - custom text on the show/hide button of fat-panel UIO
>> - custom path to a preview file for full-with-preview
>> - custom contents of drop-downs
>>    - addition of font families
>>    - addition of themes
>> - custom default site settings
>> - custom path to table-of-contents template file
>> - custom ranges on the sliders
>>    - larger max font size
>>    - larger max line spacing
>> - custom settings store (i.e. something other than a cookie)
>>
>>
>> --
>> Anastasia Cheetham     Inclusive Design Research Centre
>> acheetham at ocad.ca            Inclusive Design Institute
>>                                         OCAD University
>>
>> _______________________________________________________
>> fluid-work mailing list - fluid-work at fluidproject.org
>> To unsubscribe, change settings or access archives,
>> see http://lists.idrc.ocad.ca/mailman/listinfo/fluid-work
>
> ------------------------------------------------------
> Michelle D'Souza
> Inclusive Software Developer Researcher
> Inclusive Design Research Centre
>
> _______________________________________________________
> fluid-work mailing list - fluid-work at fluidproject.org
> To unsubscribe, change settings or access archives,
> see http://lists.idrc.ocad.ca/mailman/listinfo/fluid-work