Page Comparison

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

Panel

title	On This Page

Table of Contents

maxlevel	2
minlevel	2

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

...

Section

Column

UIO Only

Code Block

	javascript
	javascript


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

Column

Page Enhancer Only

Code Block

	javascript
	javascript


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

Section

Column

width	25%

Column

UIO + Page Enhancer

Code Block

	javascript
	javascript


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

Column

width	25%

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.

...

Section

Column

UIO Only

Code Block

	javascript
	javascript


fluid.uiOptions(container, {
    gradeNames: ["fluid.uiOptions.starterSettingsPanelsstarterSettings"],
    pathToTemplates:     "my/sites/lib/infusion/templates/"
});

NOTE: The starterSettings grade combines the grades for the starter panels and the starter schema.

Column

Page Enhancer Only

Code Block

	javascript
	javascript

fluid.pageEnhancer({
    gradeNames:   ["fluid.uiOptionsuiEnhancer.starterSettingsSchema"starterSettings],
    pathToTemplatespathToTocTemplate: "my/sites/lib/infusion/templates/",
    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

Section

Column

width	25%

Column

UIO + Page Enhancer

Only

Code Block

	javascript
	javascript


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

Section

Column

width	25%

Column

Code Block

javascript


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

Column

width	25%

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)

Section

/** * 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

NOTE: The starterSettings grade combines the grades for the starter enactors, panels and schema.

QUESTION: What should we name this/these combined grades?

Column

width	50%

UIO

Code Block

javascript

Column

width	25%

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.

Section

Column

width	20%

Column

Code Block

	javascript
	javascript

/**
 * 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:     "fluid.uiOptions.starterSettingsSchema",{
                //  "my.extra.panels",if necessary:
                template: "mymyFooferPanel.extra.settingsSchema"],html"
               pathToTemplates: "my/sites/lib/infusion/templates/", why can't panels load pathToTocTemplate: "my/sites/",
their own templates?
   siteThemeClassName: "foofer-doodle-theme" });

Alternatively, the extra grade could be added using demands:

Code Block

javascript

 fluid.demands("fluid.uiOptions", ["my.integrations"], {     }
    gradeNames: ["my.extra.panels", "my.extra.settingsSchema"], }); fluid.uiOptions(container, {   // any gradeNames: ["fluid.uiOptions.starterSettingsPanels",
 other configuration as necessary
        },
      "fluid.uiOptions.starterSettingsSchema"],  doodle: {
 gradeNames: ["fluid.uiOptions.defaultPanels"],     pathToTemplates: "my/sites/lib/infusion/templates/",     pathToTocTemplatefuncName: "my/sites/.integration.doodlePanel",
    siteThemeClassName: "foofer-doodle-theme"
});

Column

Page Enhancer

Code Block

javascript


/**
 * Define a grade for extra enactors
 * and their default settings
 */
fluid.defaults("my.extra.enactors", {
    defaultSiteSettings: {        options: {
                template: "myDoodlePanel.html"
          foofer: 7,     // if necessary
 doodle: true     },     components:}
{         foofer: {  // any other configuration as necessary
     funcName: "my.integration.fooferEnactor",  }
    }
});
/**
 * Define //a anygrade otherfor configurationextra asenactors
necessary */
fluid.defaults("my.extra.enactors", {
    components: },{
        doodlefoofer: {
            funcName: "my.integration.doodleEnactorfooferEnactor",
            // any other configuration as necessary
        },
      }
});
fluid.pageEnhancer({  doodle: {
            gradeNamesfuncName: ["fluidmy.uiEnhancerintegration.starterEnactorsdoodleEnactor",
            // any other configuration  "fluid.uiEnhancer.starterSettingsSchema",as necessary
        }
    }
});
/**
 "my.extra.enactors",
                 * A grade that combines my enactors, panels and schema.
 */
fluid.defaults("my.extra.settingsSchema]settings", {
    pathToTocTemplategradeNames: ["my/sites/.extra.enactors",
    siteThemeClassName: "foofer-doodle-theme" });

Alternatively, the extra grade could be added using demands:

Code Block

javascript


fluid.demands("fluid.pageEnhancer", ["my.integrations"], {         gradeNames: ["my.extra.enactorspanels",
                 "my.extra.settingsSchema"],
});"]
});
/**
 * Add the enactors, panels and schema
 */
fluid.pageEnhanceruiOptionsPlusPageEnhancer(container, {
    gradeNames: ["fluid.uiEnhanceruiOptions.starterEnactorsstarterSettings",
                 "fluidmy.uiEnhancerextra.starterSettingsSchemasettings"],
    pathToTemplates: "my/sites/lib/infusion/templates/",
    pathToTocTemplate: "my/sites/",
    siteThemeClassName: "foofer-doodle-theme"
});

...

Column

width	20%

Alternatively, the extra grades could be added using demands:

Section

Column

width	50%20%

UIO

Page Enhancer

Column

Code Block

	javascript
	javascript


// The grade definition would be the same as above

fluid.uiOptionsfluid.demands("fluid.uiOptions", ["my.integrations"], {
    gradeNames: ["my.extra.settings"],
});
fluid.uiOptionsPlusPageEnhancer(container, {
    // XXX: Would custom schema include 'default' panels?gradeNames: ["fluid.uiOptions.starterSettings"],
    pathToTemplates: "my/sites/lib/infusion/templates/",
    schemapathToTocTemplate: "my/sites/mySchema.json",
    pathToTemplates: "my/sites/lib/infusion/templates/",
    pathToTocTemplate: "my/sites/",
    siteThemeClassName: "foofer-doodle-theme"
});

Column

Code Block

javascript


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

...

siteThemeClassName: "foofer-doodle-theme"
});

Column

width	20%

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.

Section

Column

width	50%

UIO

Empty Subcomponents

Code Block

	javascript
	javascript


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

Column

Page Enhancer

Code Block

javascript


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

Column

width	50%

Individual Grades

Code Block

	javascript
	javascript

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)

Section

Column

width	50%

UIO

Code Block

javascript


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

Column

Page Enhancer

Code Block

javascript


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

...

Versions Compared

Old Version 39

New Version Current

Key

Guiding Principles

UIO Only

Page Enhancer Only

UIO + Page Enhancer

UIO Only

Page Enhancer Only

UIO + Page Enhancer

UIO + Page Enhancer

Use Case: 3rd Parties (adding or removing panels)

Adding panels to the set of included panels (no schema)

UIO

Use Case: 3rd Parties Adding Panels To The Starter Set

Page Enhancer

Page Enhancer

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

Empty Subcomponents

Page Enhancer

Individual Grades

Using a subset of the included panels (with schema)

UIO

Page Enhancer