First Discovery Editor API

Owned by Justin Obara
Last updated: Sept 02, 2015 by Alan HarnumVersion comment
6 min read

First Discovery Editor Overview

The First Discovery Tool is a type of Preferences Editor designed to be an entry point for users who are new to customizing a user interface to match their own needs and preferences. It is intended to inform users of some of the various customization options and allow a user to create an initial set of preferences that meets their current needs and preferences.

On This Page
See Also
Still need help?

Join the infusion-users mailing list and ask your questions there.

Adding a First Discovery Editor

The First Discovery Editor should be bound to an instance of a Preferences Editor by supplying it as the loaderGrade in an Auxiliary Schema.

 

Adding to an Auxiliary Schema:

fluid.defaults("my.auxSchema", {
	auxiliarySchema: {
		"loaderGrades": ["gpii.firstDiscovery.firstDiscoveryEditor"]
	}
});

 

Instantiating the Preferences Editor:

fluid.prefs.create(container, {
	build: {
		gradeNames: ["my.auxSchema"]
	}
};

Grades

The base grades used by the the First Discovery Editor:

Model

Path

Description

Values

Default

currentPanelNum

The panel currently displayed.

Panel ID (Number)

1

Supported Events

Event

Type

Description

Parameters

Parameter Description

onPrefsEditorReady

default

Fired when the internal prefsEditor, containing all of panels, is ready.

Component

An instance of fluid.prefs.prefsEditor

onCreateNav

default

Fired after onPrefsEditorReady, which is when all of the necessary markup is in place.

Component 

An instance of fluid.prefs.prefsEditor

onPanelShown

default

Fired each time a panel becomes visible.

Number 

The panel ID of visible shown panel

Methods

Method

Description

Parameters

showPanel

Sets the visibility of the panels. The panel which is identified as the current panel in the model is made visible, the reset are hidden.

 

Subcomponents

Name

Description

Values

Default

selfVoicing

Specifies the Text-To-Speech engine to use for self voicing.

"gpii.firstDiscovery.selfVoicing"

selfVoicing: {
    container: "{that}.dom.selfVoicing",
    createOnEvent: "onPrefsEditorReady",
    type: "gpii.firstDiscovery.selfVoicing",
    options: {
        model: {
            enabled: "{prefsEditor}.model.gpii_firstDiscovery_speak",
            utteranceOpts: {
                lang: "{prefsEditor}.model.gpii_firstDiscovery_language",
                rate: "{prefsEditor}.model.gpii_firstDiscovery_speechRate"
            }
        },
        messageBase: "{messageLoader}.resources.prefsEditor.resourceText"
    }
}
helpButtonSpecifies the type of help button to use. The current help button is mostly a placeholder, as it only sets the text.
"gpii.firstDiscovery.helpButton"
helpButton: {
    type: "gpii.firstDiscovery.helpButton",
    container: "{that}.dom.helpButton",
    createOnEvent: "onPrefsEditorReady",
    options: {
        messageBase: "{messageLoader}.resources.prefsEditor.resourceText"
    }
}
prefsEditorSpecifies the underlying prefs editor used. This is the part that contains all of the adjuster panels."fluid.prefs.prefsEditor"
prefsEditor: {
    container: "{that}.dom.prefsEditor",
    options: {
        selectors: {
            panel: "{firstDiscoveryEditor}.options.selectors.panel"
        },
        events: {
            onPanelShown: "{firstDiscoveryEditor}.events.onPanelShown"
        },
        listeners: {
            onReady: {
                listener: "{firstDiscoveryEditor}.events.onPrefsEditorReady",
                args: "{firstDiscoveryEditor}"
            },
            onAutoSave: "{that}.saveAndApply",
            "onReset.reload": {
                "this": "location",
                method: "reload",
                args: true
            },
            "onCreate.bindResetShortcut": {
                listener: "gpii.firstDiscovery.keyboardShortcut.bindShortcut",
                args: [
                    "body",
                    gpii.firstDiscovery.keyboardShortcut.key.r,
                    ["ctrlKey", "altKey"],
                    "{that}.reset"
                ]
            }
        },
        autoSave: true,
        connectionGradeForLang: "gpii.firstDiscovery.panel.lang.prefEditorConnection",
        distributeOptions: {
            source: "{that}.options.connectionGradeForLang",
            target: "{that > gpii.firstDiscovery.panel.lang}.options.prefsEditorConnection"
        }
    }
}
navSpecifies the component to use to handle the navigation between panels, and the set of panel icons.
"gpii.firstDiscovery.nav"
nav: {
    type: "gpii.firstDiscovery.nav",
    container: "{that}.dom.nav",
    createOnEvent: "onCreateNav",
    options: {
        model: {
            currentPanelNum: "{firstDiscoveryEditor}.model.currentPanelNum"
        },
        messageBase: "{messageLoader}.resources.prefsEditor.resourceText",
        styles: "{firstDiscoveryEditor}.options.styles",
        panelTotalNum: "{firstDiscoveryEditor}.panels.length"
    }
}
messageLoaderSpecifies the component and means for loading in the JSON message bundle files.
"fluid.prefs.resourceLoader"
messageLoader: {
    options: {
        locale: "{prefsEditorLoader}.settings.gpii_firstDiscovery_language"
    }
}

Options

Name

Description

Values

Default

defaultLocale

The language code to use, for selecting the correct message bundle, when no language has been provided in the preferences.

A valid language code such as: "en-US", "fr-FR", "es-MX", "de-DE", "nl-NL", "sv-SE"

 

This resolves to "en-US".

defaultLocale: {
    expander: {
        funcName: "fluid.get",
        args: [{
            expander: {
                funcName: "fluid.defaults",
                args: ["gpii.firstDiscovery.schemas.language"]
            }
        }, ["schema", "properties", "gpii.firstDiscovery.language", "default"]]
    }
}

tooltipOptions

The options to be used by any descendant tooltip components.

 

 

tooltipOptions: {
    delay: 0,
    duration: 0,
    position: {
        my: "left bottom",
        at: "right+1 top"
    },
    styles: {
        tooltip: "gpii-fd-tooltip"
    },
    items: ".gpiic-fd-tooltip:not([disabled])"
}

selectors

Javascript object containing selectors for various fragments of the markup, including the containers for the subcomponents.

 

 

See Selectors

stylesSpecific class names used to achieve the look and feel. 
styles: {
    active: "gpii-fd-active",
    show: "gpii-fd-show",
    currentPanel: "gpii-fd-current",
    lastPanel: "gpii-fd-lastPanel"
}
modelListenersJavaScript object containing model paths and the listeners that are activated when changes happen to those paths.Keys in the object are event names, values are functions or arrays of functions.See Model

Selectors

One of the options that can be provided to the First Discovery Editor is a set of CSS-based selectors identifying where in the DOM different elements can be found. The value for the option is itself a Javascript object containing name/value pairs:

 

selectors: {
    selector1Name: "selector 1 string",
    selector2Name: "selector 2 string",
      ...
}

Selector Name

Description

Default

prefsEditor

The container to use for the internal prefsEditor; which contains all of the adjuster panels.

".gpiic-fd-prefsEditor"
panelPassed down to internal prefsEditor to use as its panel selector.".gpiic-fd-prefsEditor-panel"
selfVoicingThe container for the selfVoicing subcomponent.".gpiic-fd-selfVoicing"
helpButton

The container for the help button.

".gpiic-fd-help"
navThe container for the navigation subcomponent.".gpiic-fd-nav"

Dependencies

<link rel="stylesheet" href="src/lib/infusion/src/lib/normalize/css/normalize.css" />
<link rel="stylesheet" href="src/lib/foundation/css/foundation.min.css" />
<link rel="stylesheet" href="src/css/style.css" />
<link rel="stylesheet" type="text/css" href="src/lib/infusion/src/framework/preferences/css/Enactors.css" />
<link rel="stylesheet" type="text/css" href="src/lib/infusion/src/framework/preferences/css/PrefsEditor.css" />
 
<script type="text/javascript" src="src/lib/infusion/infusion-custom.js"></script>
<script type="text/javascript" src="src/schemas/schemas.js"></script>
<script type="text/javascript" src="src/js/keyboardShortcut.js"></script>
<script type="text/javascript" src="src/js/ttsHookup.js"></script>
<script type="text/javascript" src="src/js/tooltip.js"></script>
<script type="text/javascript" src="src/js/msgLookup.js"></script>
<script type="text/javascript" src="src/js/selfVoicing.js"></script>
<script type="text/javascript" src="src/js/stickyKeysAssessment.js"></script>
<script type="text/javascript" src="src/js/keyboardInput.js"></script>
<script type="text/javascript" src="src/js/stickyKeysAdjuster.js"></script>
<script type="text/javascript" src="src/js/panels.js"></script>
<script type="text/javascript" src="src/js/enactors.js"></script>
<script type="text/javascript" src="src/js/navButtons.js"></script>
<script type="text/javascript" src="src/js/navIcons.js"></script>
<script type="text/javascript" src="src/js/helpButton.js"></script>
<script type="text/javascript" src="src/js/stepCount.js"></script>
<script type="text/javascript" src="src/js/nav.js"></script>
<script type="text/javascript" src="src/js/firstDiscoveryEditor.js"></script>