This page is NOT documentation of the UI Options API. It is a working document. The UI Options API is currently undergoing revision, and there is no API documentation as yet.
This page presents a proposal for a new API for User Interface Options. It lays out what we would like to expect of an integrator.
Guiding Principles
- A schema exists to define the settings, their defaults, ranges, etc.
- Any options that might be set should be top-level.
- Option names should make sense.
- Integrators should not have to create both a page enhancer and the fat panel individually; If they want the fat panel, the page enhancer would be assumed and should be instantiated on the page automatically.
- Integrators should be able to create a page enhancer without UIO (in the case of a full-page UIO available elsewhere, through a link).
The options shown here represent the minimal options that an integrator would have to provide. Other options will also be available.
Basic API
UIO Only
fluid.uiOptions(container, {
gradeNames: [<gradenames of desired panels>,
<gradenames of schema for settings>],
pathToTemplates: "my/sites/lib/infusion/templates/"
});
Page Enhancer Only
fluid.pageEnhancer({
gradeNames: [<grade names of desired enactors>,
<gradenames of schema for settings>],
pathToTocTemplate: "my/sites/",
siteThemeClassName: "foofer-doodle-theme"
});
UIO + Page Enhancer
fluid.uiOptionsPlusPageEnhancer(container, {
gradeNames: [<gradenames of desired panels>,
<grade names of desired enactors>,
<gradenames of schema for settings>],
pathToTemplates: "my/sites/lib/infusion/templates/",
pathToTocTemplate: "my/sites/",
siteThemeClassName: "foofer-doodle-theme"
});
If no grade names are specified, the default state of the components would be no panels, no settings. It's unlikely anyone would ever use it without grade names.
Use Case: 2nd Parties (Infusion-provided "starter-set" of panels and settings)
Add the "starter-set" of panels and settings included in Infusion using the starter grades.
UIO Only
fluid.uiOptions(container, {
gradeNames: ["fluid.uiOptions.starterSettings"],
pathToTemplates: "my/sites/lib/infusion/templates/"
});
NOTE: The starterSettings grade combines the grades for the starter panels and the starter schema.
Page Enhancer Only
fluid.pageEnhancer({
gradeNames: ["fluid.uiEnhancer.starterSettings],
pathToTocTemplate: "my/sites/",
siteThemeClassName: "foofer-doodle-theme"
});
NOTE: The starterSettings grade combines the grades for the starter enactors and the starter schema.
UIO + Page Enhancer
fluid.uiOptionsPlusPageEnhancer(container, {
gradeNames: ["fluid.uiOptions.starterSettings"],
pathToTemplates: "my/sites/lib/infusion/templates/",
pathToTocTemplate: "my/sites/",
siteThemeClassName: "foofer-doodle-theme"
});
NOTE: The starterSettings grade combines the grades for the starter enactors, panels and schema.
QUESTION: What should we name this/these combined grades?
Use Case: 3rd Parties Adding Panels To The Starter Set
Note: 3rd parties will have to define their own grades for new settings, panels, enactors.
Note: All further examples will only use the "UIO + Page Enhancer" version: fluid.uiOptionsPlusPageEnhancer(). The pattern holds.
/**
* Define a grade for the schema for your settings
*/
fluid.defaults("my.extra.settingsSchema", {
schema: {...}
});
/**
* Define a grade for extra panels
* and their default settings
*/
fluid.defaults("my.extra.panels", {
components: {
foofer: {
funcName: "my.integration.fooferPanel",
options: {
// if necessary:
template: "myFooferPanel.html"
// why can't panels load their own templates?
}
// any other configuration as necessary
},
doodle: {
funcName: "my.integration.doodlePanel",
options: {
template: "myDoodlePanel.html"
// if necessary
}
// any other configuration as necessary
}
}
});
/**
* Define a grade for extra enactors
*/
fluid.defaults("my.extra.enactors", {
components: {
foofer: {
funcName: "my.integration.fooferEnactor",
// any other configuration as necessary
},
doodle: {
funcName: "my.integration.doodleEnactor",
// any other configuration as necessary
}
}
});
/**
* A grade that combines my enactors, panels and schema.
*/
fluid.defaults("my.extra.settings", {
gradeNames: ["my.extra.enactors",
"my.extra.panels",
"my.extra.settingsSchema"]
});
/**
* Add the enactors, panels and schema
*/
fluid.uiOptionsPlusPageEnhancer(container, {
gradeNames: ["fluid.uiOptions.starterSettings",
"my.extra.settings"],
pathToTemplates: "my/sites/lib/infusion/templates/",
pathToTocTemplate: "my/sites/",
siteThemeClassName: "foofer-doodle-theme"
});
Alternatively, the extra grades could be added using demands:
fluid.demands("fluid.uiOptions", ["my.integrations"], {
gradeNames: ["my.extra.settings"],
});
fluid.uiOptionsPlusPageEnhancer(container, {
gradeNames: ["fluid.uiOptions.starterSettings"],
pathToTemplates: "my/sites/lib/infusion/templates/",
pathToTocTemplate: "my/sites/",
siteThemeClassName: "foofer-doodle-theme"
});
Use Case: 3rd Parties Wanting A Subset Of The Starter Set
There are three possible ways to do this:
- Cut-and-paste: Copy the code that defines the "starter" grades, rename the grades, delete the parts you don't want, and use these new grades instead of the starter grades (not really recommended).
- Empty subcomponents: Use the starter grades and override the excluded subcomponents with
fluid.emptySubcomponent - Individual grades: Use the individual settings grades desired instead of the starter set.
The last two of these methods will be shown here, excluding the colour-and-contrast setting and the layout setting.
Empty Subcomponents
fluid.uiOptionsPlusPageEnhancer(container, {
gradeNames: ["fluid.uiOptions.starterSettings"],
components: {
// Override the settings panels
contrast: {
type: "fluid.emptySubcomponent"
},
layoutControls: {
type: "fluid.emptySubcomponent"
},
// Override the enactors
theme: {
type: "fluid.emptySubcomponent"
},
tableOfContentsEnactor: {
type: "fluid.emptySubcomponent"
}
}
pathToTemplates: "my/sites/lib/infusion/templates/",
pathToTocTemplate: "my/sites/",
siteThemeClassName: "foofer-doodle-theme"
});
Individual Grades
fluid.defaults("my.panelSet", {
gradeNames: [
// Specify each of the four desired panels directly
"fluid.uiOptions.textSizer",
"fluid.uiOptions.lineSpacer",
"fluid.uiOptions.textFont",
"fluid.uiOptions.linksControls",
// Specify each of the four desired enactors directly
"fluid.uiEnhancer.textSizer",
"fluid.uiEnhancer.lineSpacer",
"fluid.uiEnhancer.textFont",
"fluid.uiEnhancer.linksControls",
// Use the full schema
"fluid.uiOptions.starterSettingsSchema"
]
});
fluid.uiOptionsPlusPageEnhancer(container, {
gradeNames: ["my.panelSet"],
pathToTemplates: "my/sites/lib/infusion/templates/",
pathToTocTemplate: "my/sites/",
siteThemeClassName: "foofer-doodle-theme"
});