Designing a new UIO API

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

Guiding Principles

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

• It should not require knowledge of the Framework.
• It should not require knowledge of subcomponents in the UIO component tree.
• 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 to create a page enhancer without UIO (in the case of a full-page UIO available elsewhere, through a link).

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:

fluid.uiOptions(container, {
    usePrepackagedSettings: true,
    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:

fluid.pageEnhancer({
    usePrepackagedSettings: true,
    pathToTocTemplate: "my/sites/", // filename would be in a separate option
    siteThemeClassName: "foofer-doodle-theme"
});

Once schemas are being used and one exists for the default collection of preferences:

To create UIO and a page enhancer:

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

To create only a page enhancer:

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 new settings

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 independent of initializing UIO i.e. through demands blocks only.

• This should not involve modifying options to the UIO initialization call.
• 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.

Proposed API

// this *could* be implemented as a grade, and then just specify the grade in the demands block
fluid.demands("fluid.pageEnhancer", "my.integration", {
    defaultSiteSettings: {
        foofer: 7,
        doodle: true
    },
    components: {
        foofer: {
            funcName: "my.integration.fooferEnactor",
            options: {
                // if necessary
            }
        },
        doodle: {
            funcName: "my.integration.doodleEnactor",
            options: {
                // if necessary
            }
        }
    }
});
fluid.demands("fluid.uiOptions", "my.integration", {
    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
            }
        }
    }
});

Use Case: Remove settings

Guiding Principles

Proposed API

fluid.demands("fluid.uiOptions", "my.integration", {
    components: {
        panelIwantToRemove: {
            type: "fluid.emptySubcomponent"
        }
    }
});

fluid.demands("fluid.uiEnhancer", "my.integration", {
    components: {
        panelIwantToRemove: {
            type: "fluid.emptySubcomponent"
        }
    }
});

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

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