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.

Use Case: Out-of-the-box, default settings, no customization (2nd parties

Guiding Principles

Setting UIO up out-of-the-box – using default panels, with no customizations – should be simple:

...

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 may want 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.

...

Proposed API

Until schema support is implemented, integrators need a way to say "just give me the settings I saw in the demo."

...

Other options will also be available.

Basic API

fluid.uiOptions(container, {
    gradeNames: [<gradenames of desired panels>

,
    

<gradenames 

of 

schema 

for 

settings>],
    

pathToTemplates: "

my/sites/lib/infusion/templates/"
});

...

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>,
        

To create only a page enhancer:

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

fluid.

uiOptions(container, {
    

gradeNames: 

["fluid.uiOptions.starterSettings"],
    pathToTemplates: "my/sites/lib/infusion/templates/"
});

...

fluid.pageEnhancer({
    gradeNames: ["fluid.

uiEnhancer.

starterSettings],
    pathToTocTemplate: "my/sites/",

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

Once schemas are being used:

...

fluid.

uiOptionsPlusPageEnhancer(container, {
    

gradeNames: 

["fluid.uiOptions.starterSettings"],
    pathToTemplates: "my/sites/lib/infusion/templates/",
    pathToTocTemplate: "my/sites/",

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

To create only a page enhancer using out-of-the-box schema for default settings:

...

fluid.pageEnhancer({
    pathToSchema: "my/sites/lib/infusion/defaultSchema.json",
    pathToTocTemplate: "my/sites/", // filename should be in a separate option
    siteThemeClassName: "foofer-doodle-theme"
});

Use Case: Add/remove settings, configure a fresh UIO (3rd parties)

Guiding Principles

Adding panels requires creating components, etc. and therefore requires knowledge of the Framework. For this use case, we expect that integrators understand components, options structures, demands, etc.

• Adding panels should be done through grades, either at invocation time or by adding a grade through a demands block.
• Templates for new panels should be able to be located anywhere i.e. not required to be added to wherever the default templates are.

Consider the use case of the WordPress FSS Theme (which adds UIO to a site) and the VideoPlayer WordPress plugin (which wants to add the media panel to UIO). We want independent modules, plugins, portlets, etc. to be able to add panels to UIO without UIO knowing about it, without other modules, plugins, portlets, etc. knowing about it, without multiple plugins conflicting.

...

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", {
    

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
        }
   

}

});
/**
 * A grade that combines my enactors, panels and schema.

 */
fluid.defaults("my.extra.settings", {
    

gradeNames: ["my.extra.enactors",
        

        "my.extra.panels",
    

"my.extra.settingsSchema"]
});
/**
 * Add the enactors, panels and schema
 */
fluid.uiOptionsPlusPageEnhancer(container, {
    

gradeNames: ["fluid.uiOptions.starterSettings",
             

    "my.extra.settings"],
    

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.settings"],
});
fluid.uiOptionsPlusPageEnhancer(container, {
    gradeNames: ["fluid.uiOptions.starterSettings"],
    pathToTemplates: "my/sites/lib/infusion/templates/",
    pathToTocTemplate: "my/sites/",
    siteThemeClassName: "foofer-doodle-theme"
});

Once schemas are being used:

...

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, {
    

gradeNames: 

["fluid.uiOptions.starterSettings"],

    components: {
        // Override the settings panels
        contrast: {
            type: "fluid.emptySubcomponent"
        },
        layoutControls: {
            type: "fluid.emptySubcomponent"
        },

        // Override the enactors
        theme: {
            type: "fluid.emptySubcomponent"
        },
        tableOfContentsEnactor: {
            type: "fluid.emptySubcomponent"
        }
    }

    pathToTemplates: "my/sites/lib/infusion/templates/",
    pathToTocTemplate: "my/sites/",

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

...

fluid.

defaults("my.panelSet", {
    

gradeNames: [
        // Specify each of the four desired panels directly
        "fluid.uiOptions.textSizer",
        "fluid.uiOptions.lineSpacer",
        "fluid.uiOptions.textFont",
        "fluid.uiOptions.linksControls",
        
        // Specify each of the four desired enactors directly
        "fluid.uiEnhancer.textSizer",
        "fluid.uiEnhancer.lineSpacer",
        "fluid.uiEnhancer.textFont",
        "fluid.uiEnhancer.linksControls",
        
        // Use the full schema
        "fluid.uiOptions.starterSettingsSchema"
    ]
});
fluid.uiOptionsPlusPageEnhancer(container, {
    gradeNames: ["my.panelSet"],
    

pathToTemplates: "my/sites/lib/infusion/templates/",

pathToTocTemplate: "my/sites/",
    siteThemeClassName: "foofer-doodle-theme"
});

Use Case:

...

Guiding Principles

Proposed API

Use Case: Localization

Guiding Principles

Integrators should be able to translate a single strings bundle that would take care of the entire interface.

• The strings will all be in a single .js files that places the message bundle in the global namespace.
• To translate, the integrator either
  • creates a copy of the file and edits the link in the header to reference translated file (preferred), or
  • edits the original file.

Proposed API

...

4th Parties (users of customized UIOs)