Documenting how to customize UIO and UIE
antranig.basman at colorado.edu
Wed Aug 31 17:45:42 UTC 2011
+1 for documenting those things which it makes sense for our users to configure, and which have planned them
-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.
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?
> 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
More information about the fluid-work