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 or removing panels)
Note: 3rd parties will have to define their own grades for new settings, panels, enactors.
Adding panels to the set of included panels (no schema)
UIO
/**
* 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
}
}
});
fluid.defaults("my.extra.settingsSchema", {
schema: {...}
});
fluid.uiOptions(container, {
gradeNames: ["fluid.uiOptions.starterSettingsPanels",
"fluid.uiOptions.starterSettingsSchema",
"my.extra.panels",
"my.extra.settingsSchema"],
pathToTemplates: "my/sites/lib/infusion/templates/",
pathToTocTemplate: "my/sites/",
siteThemeClassName: "foofer-doodle-theme"
});
Alternatively, the extra grade could be added using demands:
fluid.demands("fluid.uiOptions", ["my.integrations"], {
gradeNames: ["my.extra.panels", "my.extra.settingsSchema"],
});
fluid.uiOptions(container, {
gradeNames: ["fluid.uiOptions.starterSettingsPanels",
"fluid.uiOptions.starterSettingsSchema"],
gradeNames: ["fluid.uiOptions.defaultPanels"],
pathToTemplates: "my/sites/lib/infusion/templates/",
pathToTocTemplate: "my/sites/",
siteThemeClassName: "foofer-doodle-theme"
});
Page Enhancer
/**
* Define a grade for extra enactors
* and their default settings
*/
fluid.defaults("my.extra.enactors", {
defaultSiteSettings: {
foofer: 7,
doodle: true
},
components: {
foofer: {
funcName: "my.integration.fooferEnactor",
// any other configuration as necessary
},
doodle: {
funcName: "my.integration.doodleEnactor",
// any other configuration as necessary
}
}
});
fluid.pageEnhancer({
gradeNames: ["fluid.uiEnhancer.starterEnactors",
"fluid.uiEnhancer.starterSettingsSchema",
"my.extra.enactors",
"my.extra.settingsSchema],
pathToTocTemplate: "my/sites/",
siteThemeClassName: "foofer-doodle-theme"
});
Alternatively, the extra grade could be added using demands:
fluid.demands("fluid.pageEnhancer", ["my.integrations"], {
gradeNames: ["my.extra.enactors", "my.extra.settingsSchema"],
});
fluid.pageEnhancer({
gradeNames: ["fluid.uiEnhancer.starterEnactors",
"fluid.uiEnhancer.starterSettingsSchema"],
pathToTocTemplate: "my/sites/",
siteThemeClassName: "foofer-doodle-theme"
});
Adding panels to the set of included panels (with schema)
UIO
// The grade definition would be the same as above
fluid.uiOptions(container, {
// XXX: Would custom schema include 'default' panels?
schema: "my/sites/mySchema.json"
pathToTemplates: "my/sites/lib/infusion/templates/",
pathToTocTemplate: "my/sites/",
siteThemeClassName: "foofer-doodle-theme"
});
Page Enhancer
// The grade definition would be the same as above
fluid.pageEnhancer({
// XXX: Would custom schema include 'default' panels?
schema: "my/sites/mySchema.json"
pathToTocTemplate: "my/sites/",
siteThemeClassName: "foofer-doodle-theme"
});
Using a subset of the included panels (no schema)
UIO
/**
* Define a grade including only desired panels
*/
fluid.defaults("my.panels", {
components: {
textSizer: {
type: "fluid.uiOptions.textSizer",
// any other configuration as necessary
},
lineSpacer: {
type: "fluid.uiOptions.lineSpacer",
// any other configuration as necessary
}
}
});
fluid.uiOptions(container, {
gradeNames: ["my.panels"],
pathToTemplates: "my/sites/lib/infusion/templates/",
pathToTocTemplate: "my/sites/",
siteThemeClassName: "foofer-doodle-theme"
});
Page Enhancer
/**
* Define a grade including only desired enactors
*/
fluid.defaults("my.settings", {
textSize: {
type: "fluid.uiOptions.enactor.textSizer",
// any other configuration as necessary
},
textFont: {
type: "fluid.uiOptions.enactor.classSwapper",
// any other configuration as necessary
}
}
});
fluid.pageEnhancer({
gradeNames: ["my.settings"],
pathToTocTemplate: "my/sites/",
siteThemeClassName: "foofer-doodle-theme"
});
Using a subset of the included panels (with schema)
UIO
// The grade definition would be the same as above
fluid.uiOptions(container, {
schema: "my/sites/mySchema.json"
pathToTemplates: "my/sites/lib/infusion/templates/",
pathToTocTemplate: "my/sites/",
siteThemeClassName: "foofer-doodle-theme"
});
Page Enhancer
// The grade definition would be the same as above
fluid.pageEnhancer({
schema: "my/sites/mySchema.json"
pathToTocTemplate: "my/sites/",
siteThemeClassName: "foofer-doodle-theme"
});