Versions Compared

Old Version 40

changes.mady.by.user Anastasia Cheetham

Saved on

compared with

New Version Current

changes.mady.by.user Anastasia Cheetham

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3
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.

...

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

});
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
width25%
 
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
width25%
 

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.

Section
Column
width25%
 
Column

UIO + Page Enhancer

Only

Code Block
javascript
javascript

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

Section

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

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

Column
width25%
Column
 

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
width20%
 
Column
Code Block
javascript
javascript

fluid.uiOptionsPlusPageEnhancer(container, {
    gradeNames: ["fluid.uiOptions.starterSettingsPanels",
      /**
 * Define a grade for the schema for your settings
 */
fluid.defaults("my.extra.settingsSchema", {
          "fluid.uiEnhancer.starterEnactors",
                 "fluid.uiOptions.starterSettingsSchema"],
    pathToTemplates: "my/sites/lib/infusion/templates/",schema: {...}
});
/**
 * Define a grade for extra panels
 * and their default settings
 */
fluid.defaults("my.extra.panels", {
    components: {
        foofer: {
            pathToTocTemplatefuncName: "my/sites/.integration.fooferPanel",
     siteThemeClassName: "foofer-doodle-theme"
});
Column
width25%

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
Column
width50%

UIO

Code Block
javascriptjavascript

/**
 * Define a grade for extra panels
 * and their default settings
 */
fluid.defaults("my.extra.panels", {
    defaultSiteSettings: {       options: {
                // if necessary:
                template: "myFooferPanel.html"
               foofer: 7,// why can't panels load their own templates?
 doodle: true     },     components:}
{         foofer: {  // any other configuration as necessary
       funcName: "my.integration.fooferPanel" },
        doodle: {
  options: {         funcName: "my.integration.doodlePanel",
        //   if necessaryoptions: {
                template: "myFooferPanelmyDoodlePanel.html"
                // whyif can'tnecessary
panels load their own templates?        }
    }             // any other configuration as necessary
        },
    }
});
/**
 doodle:* {Define a grade for extra enactors
       funcName: */
fluid.defaults("my.integrationextra.doodlePanelenactors", {
    components: {
     options: {  foofer: {
             templatefuncName: "myDoodlePanelmy.htmlintegration.fooferEnactor",
            // any other  // if necessaryconfiguration as necessary
        },
        doodle: {
             }funcName: "my.integration.doodleEnactor",
            // any other configuration as necessary
        }
    }
});
fluid.defaults("my.extra.settingsSchema", {
    schema: {...}
});
fluid.uiOptions(container
/**
 * A grade that combines my enactors, panels and schema.
 */
fluid.defaults("my.extra.settings", {
    gradeNames: ["fluidmy.uiOptionsextra.starterSettingsPanelsenactors",
                 "fluidmy.uiOptionsextra.starterSettingsSchemapanels",
                 "my.extra.settingsSchema"]
});
/**
 * Add the enactors, panels and schema
 */
fluid.uiOptionsPlusPageEnhancer(container, {
    gradeNames: ["fluid.uiOptions.starterSettings",
                 "my.extra.settingsSchemasettings"],
    pathToTemplates: "my/sites/lib/infusion/templates/",
    pathToTocTemplate: "my/sites/",
    siteThemeClassName: "foofer-doodle-theme"
});
Column
width20%
 

Alternatively, the extra

...

grades could be added using demands:

Section
Column
width20%
 

Page Enhancer

Alternatively, the extra grade could be added using demands:

Column
Code Block
javascript
javascript

fluid.demands("fluid.uiOptions", ["my.integrations"], {
    gradeNames: ["my.extra.panels", "my.extra.settingsSchema"settings"],
});
fluid.uiOptionsuiOptionsPlusPageEnhancer(container, {
    gradeNames: ["fluid.uiOptions.starterSettingsPanelsstarterSettings"],
    pathToTemplates: "my/sites/lib/infusion/templates/",
           "fluid.uiOptions.starterSettingsSchema"]pathToTocTemplate: "my/sites/",
    gradeNamessiteThemeClassName: ["fluid.uiOptions.defaultPanels"],
    pathToTemplates: "my/sites/lib/infusion/templates/",
    pathToTocTemplate: "my/sites/",
    siteThemeClassName: "foofer-doodle-theme"
});
Column
Code Block
javascriptjavascript

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

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)

...

width50%

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

...

"foofer-doodle-theme"
});
Column
width20%
 

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.

Section
Column
width50%
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
javascriptjavascript

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

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
width50%

UIO

Code Block
javascriptjavascript

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

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

...