Page Comparison

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).

...

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"
});

fluid.pageEnhancer({
    gradeNames: [<grade names of desired enactors>,
                 <gradenames of schema for settings>],
    pathToTocTemplate: "my/sites/",
    siteThemeClassName: "foofer-doodle-theme"
});

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 provided "starter-set" of panels and settings included in Infusion using the default starter grades.

fluid.uiOptions(container, {
    gradeNames: ["fluid.uiOptions.starterSettingsPanels",
                 "fluid.uiOptions.starterSettingsSchema"starterSettings"],
    pathToTemplates: "my/sites/lib/infusion/templates/",
    pathToTocTemplate: "my/sites/",
    siteThemeClassName: "foofer-doodle-theme"
});
});

fluid.pageEnhancer({
    gradeNames: ["fluid.uiEnhancer.starterEnactors",
                 "fluid.uiOptions.starterSettingsSchema"starterSettings],
    pathToTocTemplate: "my/sites/",
    siteThemeClassName: "foofer-doodle-theme"
});

fluid.uiOptionsPlusPageEnhancer(container, {
    gradeNames: ["fluid.uiOptions.starterSettingsPanelsstarterSettings"],
    pathToTemplates: "my/sites/lib/infusion/templates/",
           "fluid.uiEnhancer.starterEnactorspathToTocTemplate: "my/sites/",
                 "fluid.uiOptions.starterSettingsSchema"],
    pathToTemplates: "my/sites/lib/infusion/templates/",
    pathToTocTemplate: "my/sites/",
    siteThemeClassName: "foofer-doodle-theme"
});
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 extrathe panelsschema for *your andsettings
their default settings
 * */
fluid.defaults("my.extra.panelssettingsSchema", {
    defaultSiteSettingsschema: {...}
});
/**
 * Define a grade for foofer:extra 7,panels
 * and their default settings
  doodle: true*/
fluid.defaults("my.extra.panels", {
    },
    components: 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.settingsSchemaenactors", {
    schemacomponents: {...}
});
fluid.uiOptions(container, {
        gradeNamesfoofer: ["fluid.uiOptions.starterSettingsPanels", {
            funcName: "my.integration.fooferEnactor",
     "fluid.uiOptions.starterSettingsSchema",       // any other configuration as necessary
      "my.extra.panels"  },
        doodle: {
       "my.extra.settingsSchema"],     pathToTemplatesfuncName: "my/sites/lib/infusion/templates/.integration.doodleEnactor",
    pathToTocTemplate: "my/sites/",
        // any other configuration as necessary
        }
   siteThemeClassName: "foofer-doodle-theme" }
});

fluid.demands("fluid.uiOptions", ["my.integrations"], {
    gradeNames: [/**
 * A grade that combines my enactors, panels and schema.
 */
fluid.defaults("my.extra.panelssettings", "my.extra.settingsSchema"],
});
fluid.uiOptions(container, {
    gradeNames: ["fluidmy.uiOptionsextra.starterSettingsPanelsenactors",
                 "fluidmy.uiOptionsextra.starterSettingsSchemapanels"],
    gradeNames: ["fluid.uiOptions.defaultPanels"],        pathToTemplates: "my/sites/lib/infusion/templates/",     pathToTocTemplate: "my/sites/",
    siteThemeClassName: "foofer-doodle-theme"
});

.extra.settingsSchema"]
});
/**
 * DefineAdd a grade for extra enactors
 * and their default settings
 the enactors, panels and schema
 */
fluid.defaults("my.extra.enactors"uiOptionsPlusPageEnhancer(container, {
    defaultSiteSettingsgradeNames: {["fluid.uiOptions.starterSettings",
        foofer: 7,         doodle: true"my.extra.settings"],
      }pathToTemplates: "my/sites/lib/infusion/templates/",
    components: {
        foofer: {
            funcName: "my.integration.fooferEnactorpathToTocTemplate: "my/sites/",
            // any other configuration as necessary
        },
        doodle:siteThemeClassName: "foofer-doodle-theme"
});

Alternatively, the extra grades could be added using demands:

fluid.demands("fluid.uiOptions", ["my.integrations"], {
            funcNamegradeNames: ["my.integrationextra.doodleEnactorsettings"],
  
         // any other configuration as necessary
        }
    }
});
fluid.pageEnhanceruiOptionsPlusPageEnhancer(container, {
    gradeNames: ["fluid.uiEnhanceruiOptions.starterEnactorsstarterSettings"],
                 "fluid.uiEnhancer.starterSettingsSchemapathToTemplates: "my/sites/lib/infusion/templates/",
                 "my.extra.enactorspathToTocTemplate: "my/sites/",
    siteThemeClassName:             "my.extra.settingsSchema],
    pathToTocTemplate: "my/sites/",
    siteThemeClassName: "foofer-doodle-theme"
"foofer-doodle-theme"
});

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"
});

...

Use Case: 3rd Parties Wanting A Subset Of The Starter Set

There are three possible ways to do this:

1. 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).
2. Empty subcomponents: Use the starter grades and override the excluded subcomponents with fluid.emptySubcomponent
3. 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.

/**fluid.uiOptionsPlusPageEnhancer(container, {
 * Define a grade including only desired panels
 */
fluid.defaults("my.panels", {gradeNames: ["fluid.uiOptions.starterSettings"],

    components: {
        textSizer:// {Override the settings panels
         typecontrast: "fluid.uiOptions.textSizer",{
            // any other configuration as necessarytype: "fluid.emptySubcomponent"
        },
        lineSpacerlayoutControls: {
            type: "fluid.uiOptions.lineSpacer",emptySubcomponent"
        },

        // any otherOverride configurationthe asenactors
necessary        theme: }{
    } }); fluid.uiOptions(container, {     gradeNamestype: ["myfluid.panelsemptySubcomponent"],
     pathToTemplates: "my/sites/lib/infusion/templates/",  },
  pathToTocTemplate: "my/sites/",     siteThemeClassNametableOfContentsEnactor: "foofer-doodle-theme"
});

/**
 * Define a grade including only desired enactors
 */
fluid.defaults("my.settings", {
  {
            type: "fluid.emptySubcomponent"
        }
    }

    textSizepathToTemplates: {"my/sites/lib/infusion/templates/",
    pathToTocTemplate: "my/sites/",
    siteThemeClassName: "foofer-doodle-theme"
   type: "fluid.uiOptions.enactor.textSizer",
});

fluid.defaults("my.panelSet", {
    gradeNames: [
     // any other configuration// asSpecify necessaryeach of the four desired panels  directly
 },         textFont: {
   "fluid.uiOptions.textSizer",
        type: "fluid.uiOptions.enactor.classSwapperlineSpacer",
        "fluid.uiOptions.textFont",
   // any other configuration as necessary "fluid.uiOptions.linksControls",
        }
    } }); fluid.pageEnhancer({  // Specify each gradeNames: ["my.settings"],
    pathToTocTemplate: "my/sites/",of the four desired enactors directly
       siteThemeClassName: "foofer-doodle-theme"
});

Using a subset of the included panels (with schema)

// The grade definition would be the same as above

fluid.uiOptions(container, {fluid.uiEnhancer.textSizer",
        "fluid.uiEnhancer.lineSpacer",
        "fluid.uiEnhancer.textFont",
       schema: "my/sites/mySchema.json"fluid.uiEnhancer.linksControls",
        
 pathToTemplates: "my/sites/lib/infusion/templates/",     pathToTocTemplate: "my/sites/", Use the full  siteThemeClassName: "foofer-doodle-theme"
});

// The grade definition would be the same as above

fluid.pageEnhancer(schema
        "fluid.uiOptions.starterSettingsSchema"
    ]
});
fluid.uiOptionsPlusPageEnhancer(container, {
    schemagradeNames: ["my.panelSet"],
    pathToTemplates: "my/sites/mySchema.json"/lib/infusion/templates/",
    pathToTocTemplate: "my/sites/",
    siteThemeClassName: "foofer-doodle-theme"
});

...