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.

...

{panel

:title

=On This Page

}
{toc

:minlevel

Guiding Principles

...

=2}
{panel}

h2. Guiding Principles

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

...

h2. Basic API without [schema

...

UIO + Page Enhancer

|Schema for UIO preferences] support

{section}
{column}
h3. UIO + Page Enhancer
{code:javascript}
fluid.uiOptions(container, {
    gradeNames: [<gradenames of desired panels>],
    pathToTemplates: "my/sites/lib/infusion/templates/",
    pathToTocTemplate: "my/sites/",
    siteThemeClassName: "foofer-doodle-theme"
});
{code}

Page Enhancer Only

{column}
{column}
h3. Page Enhancer Only
{code:javascript}
fluid.pageEnhancer({
    gradeNames: [<grade names for desired settings>],
    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.

Basic API with schema support

UIO + Page Enhancer

{code}
{column}
{section}
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.

h2. Basic API with [schema|Schema for UIO preferences] support

{section}
{column}
h3. UIO + Page Enhancer
{code:javascript}
fluid.uiOptions(container, {
    schema: <path to schema, including filename>,
    pathToTemplates: "my/sites/lib/infusion/templates/",
    pathToTocTemplate: "my/sites/",
    siteThemeClassName: "foofer-doodle-theme"
});

Page Enhancer Only

{code}
{column}
{column}
h3. Page Enhancer Only
{code:javascript}
{code:javascript}
fluid.pageEnhancer({
    schema: <path to schema, including filename>,
    pathToTocTemplate: "my/sites/",
    siteThemeClassName: "foofer-doodle-theme"
});

...

{code}
{column}
{section}

h2. Use Case: 2nd Parties (Infusion-provided panels and settings)

...

Add the provided panels and settings using the default grades.

...

UIO + Page Enhancer (no schema)

{section}
{column}
h3. UIO + Page Enhancer (no schema)
{code:javascript}
fluid.uiOptions(container, {
    gradeNames: ["fluid.uiOptions.defaultPanels"],
    pathToTemplates: "my/sites/lib/infusion/templates/",
    pathToTocTemplate: "my/sites/",
    // TocTemplate filename would be in a separate option
    siteThemeClassName: "foofer-doodle-theme"
});

Page Enhancer Only (no schema)

{code}
{column}
{column}
h3. Page Enhancer Only (no schema)
{code:javascript}
fluid.pageEnhancer({
    gradeNames: ["fluid.uiOptions.defaultSettings"],
    pathToTocTemplate: "my/sites/",
    // TocTemplate filename would be in a separate option
    siteThemeClassName: "foofer-doodle-theme"
});

UIO + Page Enhancer (with schema)

{code}
{column}
{section}

{section}
{column}
h3. UIO + Page Enhancer (with schema)
{code:javascript}
fluid.uiOptions(container, {
    schema: "my/sites/lib/infusion/defaultSchema.json",
    pathToTemplates: "my/sites/lib/infusion/templates/",
    pathToTocTemplate: "my/sites/",
    // TocTemplate filename would be in a separate option
    siteThemeClassName: "foofer-doodle-theme"
});
{code}

Page Enhancer Only (with schema)

{column}
{column}
h3. Page Enhancer Only (with schema)
{code:javascript}
fluid.pageEnhancer({
    schema: "my/sites/lib/infusion/defaultSchema.json",
    pathToTocTemplate: "my/sites/",
    // TocTemplate filename would be in a separate option
    siteThemeClassName: "foofer-doodle-theme"
});

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

3rd parties will have to define their own grades.

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

UIO

{code}
{column}
{section}

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

3rd parties will have to define their own grades.

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

{section}
{column:width=50%}
h4. UIO
{code:javascript}
/**
 * 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?
            }
        },
        doodle: {
            funcName: "my.integration.doodlePanel",
            options: {
                template: "myDoodlePanel.html"
                // if necessary
            }
        }
    }
});
fluid.uiOptions(container, {
    gradeNames: ["fluid.uiOptions.defaultPanels", "my.extra.panels"],
    pathToTemplates: "my/sites/lib/infusion/templates/",
    pathToTocTemplate: "my/sites/",
    // TocTemplate filename would be in a separate option
    siteThemeClassName: "foofer-doodle-theme"
});

{code}
Alternatively, the extra grade could be added using demands:

{code

:javascript

}
fluid.demands("fluid.uiOptions", ["my.integrations"], {
    gradeNames: ["my.extra.panels"],
});
fluid.uiOptions(container, {
    gradeNames: ["fluid.uiOptions.defaultPanels"],
    pathToTemplates: "my/sites/lib/infusion/templates/",
    pathToTocTemplate: "my/sites/",
    // TocTemplate filename would be in a separate option
    siteThemeClassName: "foofer-doodle-theme"
});

Page Enhancer

{code}
{column}
{column}
h4. Page Enhancer
{code:javascript}
/**
 * Define a grade for extra enactors
 * and their default settings
 */
fluid.defaults("my.extra.settings", {
    defaultSiteSettings: {
        foofer: 7,
        doodle: true
    },
    components: {
        foofer: {
            funcName: "my.integration.fooferEnactor",
            options: {
                // if necessary
            }
        },
        doodle: {
            funcName: "my.integration.doodleEnactor",
            options: {
                // if necessary
            }
        }
    }
});
fluid.pageEnhancer({
    gradeNames: ["fluid.uiOptions.defaultSettings", "my.extra.settings"],
    pathToTocTemplate: "my/sites/",
    // TocTemplate filename would be in a separate option
    siteThemeClassName: "foofer-doodle-theme"
});

{code}
Alternatively, the extra grade could be added using demands:

{code

:javascript

}
fluid.demands("fluid.pageEnhancer", ["my.integrations"], {
    gradeNames: ["my.extra.settings"],
});
fluid.pageEnhancer({
    gradeNames: ["fluid.uiOptions.defaultSettings"],
    pathToTocTemplate: "my/sites/",
    // TocTemplate filename would be in a separate option
    siteThemeClassName: "foofer-doodle-theme"
});

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

UIO

{code}
{column}
{section}

h3. Adding panels to the set of included panels (with schema)

{section}
{column:width=50%}
h4. UIO
{code:javascript}
// 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/",
    // TocTemplate filename would be in a separate option
    siteThemeClassName: "foofer-doodle-theme"
});

Page Enhancer

{code}
{column}
{column}
h4. Page Enhancer
{code: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/",
    // TocTemplate filename would be in a separate option
    siteThemeClassName: "foofer-doodle-theme"
});

Using a subset of defaults

Proposed API

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

To create UIO and a page enhancer:

Access to the default panels would be made easy through a "flavour" of uiOptions (similar to flavours of Reorderer):

{code}

{section}
{column:width=50%}
Access to the default panels would be made easy through a "flavour" of uiOptions (similar to flavours of Reorderer):
{code:javascript}
fluid.uiOptionsWithDefaultPanels(container, {
    pathToTemplates: "my/sites/lib/infusion/templates/",
    pathToTocTemplate: "my/sites/",
    siteThemeClassName: "foofer-doodle-theme"
});

which would be equivalent to

{code}
{column}
{column}
which would be equivalent to
{code:javascript}
fluid.uiOptions(container, {
    gradeNames: ["fluid.uiOptions.defaultPanels"],
    pathToTemplates: "my/sites/lib/infusion/templates/",
    pathToTocTemplate: "my/sites/",
    siteThemeClassName: "foofer-doodle-theme"
});

{code}
{column}
{section}

h3. Using a subset of defaults





{html}
<!--
{html}
----

h3. Proposed API

Until [schema|Schema for UIO preferences] support is implemented, integrators need a way to say "just give me the settings I saw in the demo."

h4. To create UIO and a page enhancer:
{code:javascript}
fluid.uiOptions(container, {
    gradeNames: [<gradenames of desired panels>],
    pathToTemplates: "my/sites/lib/infusion/templates/",
    pathToTocTemplate: "my/sites/", // filename would be in a separate option
    siteThemeClassName: "foofer-doodle-theme"
});

To create only a page enhancer:

Access to the default setting would be made easy through a "flavour" of enhancer (similar to flavours of Reorderer):

{code}

{section}
{column:width=50%}
Access to the default setting would be made easy through a "flavour" of enhancer (similar to flavours of Reorderer):
{code:javascript}
fluid.pageEnhancerWithDefaultSetting({
    pathToTocTemplate: "my/sites/", // filename would be in a separate option
    siteThemeClassName: "foofer-doodle-theme"
});

which would be equivalent to

{code}
{column}
{column}
which would be equivalent to
{code:javascript}
fluid.pageEnhancer({
    gradeNames: ["fluid.uiEnhancer.defaultSettings"],
    pathToTocTemplate: "my/sites/", // filename would be in a separate option
    siteThemeClassName: "foofer-doodle-theme"
});

{code}
{column}
{section}
h4. To create only a page enhancer:
{code:javascript}
fluid.pageEnhancer({
    gradeNames: [<grade names for desired settings>],
    pathToTocTemplate: "my/sites/", // filename would be in a separate option
    siteThemeClassName: "foofer-doodle-theme"
});

Once schemas are being used

...

{code}
{column}
{section}

h4. Once [schemas|Schema for UIO preferences] are being used

To create UIO and a page enhancer using out-of-the-box schema for default panels:

...

{code

:javascript

}
fluid.uiOptions(container, {
    pathToSchema: "my/sites/lib/infusion/defaultSchema.json",
    pathToTemplates: "my/sites/lib/infusion/templates/",
    pathToTocTemplate: "my/sites/", // filename would be in a separate option
    siteThemeClassName: "foofer-doodle-theme"
});
{code}

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

...

{code

:javascript

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

...

{code}

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

...

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

...

h3. Proposed API

...

h4. Add panels to UIO

...

{code

:javascript

}
// Define a grade with the extra panels and their default settings
fluid.defaults("my.extra.panels", {
    defaultSiteSettings: {
        foofer: 7,
        doodle: true
    },
    components: {
        foofer: {
            funcName: "my.integration.fooferPanel",
            options: {
                template: "myFooferPanel.html" // why can't panels load their own templates?
                // if necessary
            }
        },
        doodle: {
            funcName: "my.integration.doodlePanel",
            options: {
                template: "myDoodlePanel.html"
                // if necessary
            }
        }
    }
});
{code}
To add the grade to UIO, use one of the following:

...

{section}
{column:width=50%}
{code:javascript}
// Add the grade to UIOptions as part of creation
fluid.uiOptions(container, {
    gradeNames: ["fluid.uiOptions.defaultPanels", "my.extra.panels"],
    pathToTemplates: "my/sites/lib/infusion/templates/",
    pathToTocTemplate: "my/sites/", // filename would be in a separate option
    siteThemeClassName: "foofer-doodle-theme"
});

{code}
{column}
{column}
{code:javascript}
// Add the grade to UIOptions through demands
fluid.demands("fluid.uiOptions", "my.integration", {
    gradeNames: ["my.extra.panels"]
});
// create UIO
fluid.uiOptions(container, {
    gradeNames: ["fluid.uiOptions.defaultPanels"],
    pathToTemplates: "my/sites/lib/infusion/templates/",
    pathToTocTemplate: "my/sites/", // filename would be in a separate option
    siteThemeClassName: "foofer-doodle-theme"
});

Add settings to UIE

{code}
{column}
{section}

h4. Add settings to UIE

{code:javascript}
// Define a grade for the extra enactors and their default settings
fluid.defaults("my.extra.settings", {
    defaultSiteSettings: {
        foofer: 7,
        doodle: true
    },
    components: {
        foofer: {
            funcName: "my.integration.fooferEnactor",
            options: {
                // if necessary
            }
        },
        doodle: {
            funcName: "my.integration.doodleEnactor",
            options: {
                // if necessary
            }
        }
    }
});
{code}

To add the grade to UIE, use one of the following:

...

{section}
{column}
{code:javascript}
// Add the grade to UIEnhancer as part of creation
fluid.pageEnhancer({
    gradeNames: ["fluid.uiEnhancer.defaultSettings", "my.extra.settings"],
    pathToTocTemplate: "my/sites/",
    siteThemeClassName: "foofer-doodle-theme"
});

{code}
{column}
{column}
{code:javascript}
// add grade to UIEnhancer through demands
fluid.demands("fluid.uiEnhancer", "my.integrations" {
    gradeNames:["my.extra.settings"] 
});
// create UIEnhancer
fluid.pageEnhancer({
    gradeNames: ["fluid.uiEnhancer.defaultSettings"],
    pathToTocTemplate: "my/sites/",
    siteThemeClassName: "foofer-doodle-theme"
});

Once schemas are being used

Use Case: Users of customized UIO (4th parties)

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

...

{code}
{column}
{section}

h4. Once [schemas|Schema for UIO preferences] are being used



h2. Use Case: Users of customized UIO (4th parties)

h3. Guiding Principles

h3. Proposed API


{html}
-->
{html}

h2. Use Case: Localization

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

h3. Proposed API

There would be no change in the API to translate the interface.