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.
On This Page
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/",
pathToTocTemplate: "my/sites/",
siteThemeClassName: "foofer-doodle-theme"
});
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.starterSettingsPanels",
"fluid.uiOptions.starterSettingsSchema"],
pathToTemplates: "my/sites/lib/infusion/templates/",
pathToTocTemplate: "my/sites/",
siteThemeClassName: "foofer-doodle-theme"
});
Page Enhancer Only
fluid.pageEnhancer({
gradeNames: ["fluid.uiEnhancer.starterEnactors",
"fluid.uiOptions.starterSettingsSchema"],
pathToTocTemplate: "my/sites/",
siteThemeClassName: "foofer-doodle-theme"
});
UIO + Page Enhancer
fluid.uiOptionsPlusPageEnhancer(container, {
gradeNames: ["fluid.uiOptions.starterSettingsPanels",
"fluid.uiEnhancer.starterEnactors",
"fluid.uiOptions.starterSettingsSchema"],
pathToTemplates: "my/sites/lib/infusion/templates/",
pathToTocTemplate: "my/sites/",
siteThemeClassName: "foofer-doodle-theme"
});
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", {
defaultSiteSettings: {
foofer: 7,
doodle: true
},
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
}
}
});
/**
* Add the enactors, panels and schema
*/
fluid.uiOptionsPlusPageEnhancer(container, {
gradeNames: ["fluid.uiEnhancer.starterEnactors",
"fluid.uiOptions.starterSettingsPanels",
"fluid.uiOptions.starterSettingsSchema",
"my.extra.enactors",
"my.extra.panels",
"my.extra.settingsSchema"],
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.enactors", "my.extra.panels", "my.extra.settingsSchema"],
});
fluid.uiOptionsPlusPageEnhancer(container, {
gradeNames: ["fluid.uiEnhancer.starterEnactors",
"fluid.uiOptions.starterSettingsPanels",
"fluid.uiOptions.starterSettingsSchema"],
pathToTemplates: "my/sites/lib/infusion/templates/",
pathToTocTemplate: "my/sites/",
siteThemeClassName: "foofer-doodle-theme"
});