Modules (180)

PreferencesManager

Description

PreferencesManager

Dependencies

Variables

CLIENT_ID_PREFIX Constant

The prefix used in the generated client ID

Type
string
    var CLIENT_ID_PREFIX = "com.adobe.brackets.";

    // Private Properties
    var preferencesKey,
        prefStorage,
        persistentStorage,
        extensionPaths,
        doLoadPreferences   = false;
Public API

CURRENT_FILE

Context to look up preferences for the currently edited file. This is undefined because this is the default behavior of PreferencesSystem.get.

Type
Object
    var CURRENT_FILE;
Public API

CURRENT_PROJECT

Context to look up preferences in the current project.

Type
Object
    var CURRENT_PROJECT = {};

PREFERENCES_CLIENT_ID Constant

The local storage ID

Type
string
    var PREFERENCES_CLIENT_ID = "com.adobe.brackets.preferences";

scopeOrderWithProject

Cached copy of the scopeOrder with the project Scope

    var scopeOrderWithProject = null;

scopeOrderWithoutProject

Cached copy of the scopeOrder without the project Scope

    var scopeOrderWithoutProject = null;

Functions

Private

_adjustScopeOrderForProject

scopeOrder Array.<string>
initial scopeOrder
includeProject boolean
Whether the project Scope should be included
Returns: Array.<string>
array with or without project Scope as needed.
    function _adjustScopeOrderForProject(scopeOrder, includeProject) {
        var hasProject = scopeOrder.indexOf("project") > -1;

        if (hasProject === includeProject) {
            return scopeOrder;
        }

        var newScopeOrder;

        if (includeProject) {
            var before = scopeOrder.indexOf("user");
            if (before === -1) {
                before = scopeOrder.length - 2;
            }
            newScopeOrder = _.take(scopeOrder, before);
            newScopeOrder.push("project");
            newScopeOrder.push.apply(newScopeOrder, _.drop(scopeOrder, before));
        } else {
            newScopeOrder = _.without(scopeOrder, "project");
        }
        return newScopeOrder;
    }
Private Public API

_buildContext

filename optional string
Filename to create the context with.
languageId optional string
Language ID to create the context with.
    function _buildContext(filename, languageId) {
        var ctx = {};
        if (filename) {
            ctx.path = filename;
        } else {
            ctx.path = currentFilename;
        }
        if (languageId) {
            ctx.language = languageId;
        } else {
            ctx.language = currentLanguageId;
        }
        ctx.scopeOrder = _includeProjectScope(ctx.path) ?
                        scopeOrderWithProject :
                        scopeOrderWithoutProject;
        return ctx;
    }

    function _getContext(context) {
        context = context || {};
        return _buildContext(context.path, context.language);
    }
Private Public API

_getExtensionPaths

Returns: Array.<string>
    function _getExtensionPaths() {
        if (!extensionPaths) {
            var dirPath = FileUtils.getNativeBracketsDirectoryPath();

            extensionPaths = [
                dirPath + "/extensions/default/",
                dirPath + "/extensions/dev/",
                ExtensionLoader.getUserExtensionPath() + "/"
            ];
        }
        return extensionPaths;
    }
Private

_handleOpenPreferences

    function _handleOpenPreferences() {
        var fullPath = getUserPrefFile(),
            file = FileSystem.getFileForPath(fullPath);
        file.exists(function (err, doesExist) {
            if (doesExist) {
                CommandManager.execute(Commands.FILE_OPEN, { fullPath: fullPath });
            } else {
                FileUtils.writeText(file, "", true)
                    .done(function () {
                        CommandManager.execute(Commands.FILE_OPEN, { fullPath: fullPath });
                    });
            }
        });

    }

    CommandManager.register(Strings.CMD_OPEN_PREFERENCES, Commands.FILE_OPEN_PREFERENCES, _handleOpenPreferences);
Private

_includeProjectScope

filename optional string
Full path to edited file
Returns: boolean
true if the project Scope should be included.
    function _includeProjectScope(filename) {
        filename = filename || currentFilename;
        if (!filename || !projectDirectory) {
            return false;
        }
        return FileUtils.getRelativeFilename(projectDirectory, filename) !== undefined;
    }
Private

_initStorage

    function _initStorage(storage) {
        persistentStorage = storage;

        if (doLoadPreferences) {
            prefStorage = JSON.parse(persistentStorage.getItem(preferencesKey));
        }

        // initialize empty preferences if none were found in storage
        if (!prefStorage) {
            _reset();
        }
    }

    // Check localStorage for a preferencesKey. Production and unit test keys
    // are used to keep preferences separate within the same storage implementation.
    preferencesKey = window.localStorage.getItem("preferencesKey");

    if (!preferencesKey) {
        // use default key if none is found
        preferencesKey = PREFERENCES_CLIENT_ID;
        doLoadPreferences = true;
    } else {
        // using a non-default key, check for additional settings
        doLoadPreferences = !!(window.localStorage.getItem("doLoadPreferences"));
    }

    // Use localStorage by default
    _initStorage(window.localStorage);


    // Public API
    exports.getPreferenceStorage    = getPreferenceStorage;
    exports.savePreferences         = savePreferences;
    exports.getClientID             = getClientID;


    // Unit test use only
    exports._reset                  = _reset;
    exports._getExtensionPaths      = _getExtensionPaths;

    // New code follows. The code above (with the exception of the imports) is
    // deprecated.

    var currentFilename         = null, // the filename currently being edited
        currentLanguageId       = null, // the language id of the file currently being edited
        projectDirectory        = null,
        projectScopeIsIncluded  = true;
Private Public API

_reset

    function _reset() {
        prefStorage = {};

        // Note that storage.clear() is not used. Production and unit test code
        // both rely on the same backing storage but unique item keys.
        persistentStorage.setItem(preferencesKey, JSON.stringify(prefStorage));
    }
Private Public API

_setCurrentFile

newFilename string
Full path to currently edited file
    function _setCurrentFile(newFilename) {
        var oldFilename = currentFilename;
        if (oldFilename === newFilename) {
            return;
        }
        currentFilename = newFilename;
        _toggleProjectScope();
        PreferencesImpl.manager.signalContextChanged(_buildContext(oldFilename, currentLanguageId),
                                                     _buildContext(newFilename, currentLanguageId));
    }
Private Public API

_setCurrentLanguage

newLanguageId string
The id of the language of the current editor.
    function _setCurrentLanguage(newLanguageId) {
        var oldLanguageId = currentLanguageId;
        if (oldLanguageId === newLanguageId) {
            return;
        }
        currentLanguageId = newLanguageId;
        PreferencesImpl.manager.signalContextChanged(_buildContext(currentFilename, oldLanguageId),
                                                     _buildContext(currentFilename, newLanguageId));
    }


    PreferencesImpl.manager.contextBuilder = _getContext;
Private Public API

_setProjectSettingsFile

settingsFile string
Full path to the project's settings file
    function _setProjectSettingsFile(settingsFile) {
        projectDirectory = FileUtils.getDirectoryPath(settingsFile);
        _toggleProjectScope();
        PreferencesImpl.projectPathLayer.setPrefFilePath(settingsFile);
        PreferencesImpl.projectStorage.setPath(settingsFile);
    }
Private

_toggleProjectScope

    function _toggleProjectScope() {
        if (_includeProjectScope() === projectScopeIsIncluded) {
            return;
        }
        if (projectScopeIsIncluded) {
            PreferencesImpl.manager.removeFromScopeOrder("project");
        } else {
            PreferencesImpl.manager.addToScopeOrder("project", "user");
        }
        projectScopeIsIncluded = !projectScopeIsIncluded;
    }
Private

_updateCurrentProjectContext

    function _updateCurrentProjectContext() {
        var defaultScopeOrder = PreferencesImpl.manager._getScopeOrder({});
        scopeOrderWithProject = _adjustScopeOrderForProject(defaultScopeOrder, true);
        scopeOrderWithoutProject = _adjustScopeOrderForProject(defaultScopeOrder, false);
        CURRENT_PROJECT.scopeOrder = scopeOrderWithProject;
    }

    _updateCurrentProjectContext();

    PreferencesImpl.manager.on("scopeOrderChange", _updateCurrentProjectContext);
Public API

deprecated convertPreferences

Converts from the old localStorage-based preferences to the new-style preferences according to the "rules" given.

rules is an object, the keys of which refer to the preference names. The value tells the converter what to do. The following values are available:

  • user: convert to a user-level preference
  • user newkey: convert to a user-level preference, changing the key to newkey

Once a key has been converted, it will not be converted again.

clientID string,Object
ClientID used in the old preferences
rules Object
Rules for conversion (as defined above)
isViewState optional boolean
If it is undefined or false, then the preferences listed in 'rules' are those normal user-editable preferences. Otherwise, they are view state settings.
prefCheckCallback optional function(string)
Optional callback function that examines each preference key for migration.
    function convertPreferences(clientID, rules, isViewState, prefCheckCallback) {
        DeprecationWarning.deprecationWarning("PreferencesManager.convertPreferences() has been deprecated. " +
                                              "Please upgrade to the current Preferences system " +
                                              "(https://github.com/adobe/brackets/wiki/Preferences-System#conversion-from-the-pre-36-preferences-system).");
        PreferencesImpl.smUserScopeLoading.done(function () {
            PreferencesImpl.userScopeLoading.done(function () {
                if (!clientID || (typeof clientID === "object" && (!clientID.id || !clientID.uri))) {
                    console.error("Invalid clientID");
                    return;
                }
                var prefs = getPreferenceStorage(clientID, null, true);

                if (!prefs) {
                    return;
                }

                var prefsID = typeof clientID === "object" ? getClientID(clientID) : clientID;
                if (prefStorage.convertedKeysMap === undefined) {
                    prefStorage.convertedKeysMap = {};
                }
                var convertedKeysMap = prefStorage.convertedKeysMap;

                prefs.convert(rules, convertedKeysMap[prefsID], isViewState, prefCheckCallback)
                    .done(function (complete, convertedKeys) {
                        prefStorage.convertedKeysMap[prefsID] = convertedKeys;
                        savePreferences();
                    });
            }).fail(function (error) {
                console.error("Error while converting ", typeof clientID === "object" ? getClientID(clientID) : clientID);
                console.error(error);
            });
        });
    }


    // Constants for preference lookup contexts.
Public API

getClientID

This method returns a standardized ClientID for a given requireJS module object

module non-nullable {id: string, uri: string}
- A requireJS module object
Returns: string
The ClientID
    function getClientID(module) {
        var paths = exports._getExtensionPaths();
        var pathUrl, clientID;

        paths.some(function (path) {
            if (module.uri.toLocaleLowerCase().indexOf(path.toLocaleLowerCase()) === 0) {
                pathUrl = path;
                return true;
            }
        });

        if (pathUrl) {
            clientID = CLIENT_ID_PREFIX + module.uri.replace(pathUrl, "");
        } else {
            clientID = CLIENT_ID_PREFIX + module.id;
        }
        return clientID;
    }
Public API

getExtensionPrefs

Creates an extension-specific preferences manager using the prefix given. A . character will be appended to the prefix. So, a preference named foo with a prefix of myExtension will be stored as myExtension.foo in the preferences files.

prefix string
Prefix to be applied
    function getExtensionPrefs(prefix) {
        return PreferencesImpl.manager.getPrefixedSystem(prefix);
    }
Public API

deprecated getPreferenceStorage

Retreive the preferences data for the given clientID.

clientID string,{id: string,uri: string}
- A unique identifier or a requireJS module object
defaults optional string
- Default preferences stored as JSON
_doNotCreate optional boolean
Do not create the storage if it does not already exist. Used for conversion.
Returns: PreferenceStorage
    function getPreferenceStorage(clientID, defaults, _doNotCreate) {
        // No one should be calling this to access the old preference storage except for
        // migrating the old preferences to the new model. So if this is called without
        // having _doNotCreate set to true, then the caller is using the old preferences model.
        if (!_doNotCreate) {
            var clientString = typeof clientID === "object" ? clientID.uri : clientID;
            DeprecationWarning.deprecationWarning("PreferencesManager.getPreferenceStorage() called with client id '" +
                                                  clientString + "' has been deprecated. Use PreferencesManager.definePreference() instead.");
        }
        if (!clientID || (typeof clientID === "object" && (!clientID.id || !clientID.uri))) {
            console.error("Invalid clientID");
            return;
        }
        if (typeof clientID === "object") {
            clientID = getClientID(clientID);
        }

        var prefs = prefStorage[clientID];

        if (prefs === undefined) {
            if (_doNotCreate) {
                return;
            }
            // create a new empty preferences object
            prefs = (defaults && JSON.stringify(defaults)) ? defaults : {};
            prefStorage[clientID] = prefs;
        } else if (defaults) {
            // add new defaults
            _.forEach(defaults, function (value, key) {
                if (prefs[key] === undefined) {
                    prefs[key] = value;
                }
            });
        }

        return new OldPreferenceStorage(clientID, prefs);
    }
Public API

getUserPrefFile

Get the full path to the user-level preferences file.

Returns: string
Path to the preferences file
    function getUserPrefFile() {
        return PreferencesImpl.userPrefFile;
    }
Public API

getViewState

Convenience function that gets a view state

id string
preference to get
context nullable Object
Optional additional information about the request
    function getViewState(id, context) {
        return PreferencesImpl.stateManager.get(id, context);
    }
Public API

savePreferences

Save all preference clients.

    function savePreferences() {
        // save all preferences
        persistentStorage.setItem(preferencesKey, JSON.stringify(prefStorage));
    }
Public API

deprecated setValueAndSave

Convenience function that sets a preference and then saves the file, mimicking the old behavior a bit more closely.

id string
preference to set
value *
new value for the preference
options optional {location: ?Object, context: ?Object, string}
Specific location in which to set the value or the context to use when setting the value
Returns: boolean
true if a value was set
    function setValueAndSave(id, value, options) {
        DeprecationWarning.deprecationWarning("PreferencesManager.setValueAndSave() called for " + id + ". Use PreferencesManager.set() instead.", true);
        var changed = exports.set(id, value, options).stored;
        PreferencesImpl.manager.save();
        return changed;
    }
Public API

setViewState

Convenience function that sets a view state and then saves the file

id string
preference to set
value *
new value for the preference
context nullable Object
Optional additional information about the request
doNotSave optional boolean
If it is undefined or false, then save the view state immediately.
    function setViewState(id, value, context, doNotSave) {

        PreferencesImpl.stateManager.set(id, value, context);

        if (!doNotSave) {
            PreferencesImpl.stateManager.save();
        }
    }

    AppInit.appReady(function () {
        PreferencesImpl.manager.resumeChangeEvents();
    });

    // Private API for unit testing and use elsewhere in Brackets core
    exports._isUserScopeCorrupt     = PreferencesImpl.isUserScopeCorrupt;
    exports._setCurrentFile         = _setCurrentFile;
    exports._setCurrentLanguage     = _setCurrentLanguage;
    exports._setProjectSettingsFile = _setProjectSettingsFile;
    exports._smUserScopeLoading     = PreferencesImpl.smUserScopeLoading;
    exports._stateProjectLayer      = PreferencesImpl.stateProjectLayer;
    exports._reloadUserPrefs        = PreferencesImpl.reloadUserPrefs;
    exports._buildContext           = _buildContext;

    // Public API

    // Context names for preference lookups
    exports.CURRENT_FILE        = CURRENT_FILE;
    exports.CURRENT_PROJECT     = CURRENT_PROJECT;

    exports.ready               = PreferencesImpl.managerReady;
    exports.getUserPrefFile     = getUserPrefFile;
    exports.get                 = PreferencesImpl.manager.get.bind(PreferencesImpl.manager);
    exports.set                 = PreferencesImpl.manager.set.bind(PreferencesImpl.manager);
    exports.save                = PreferencesImpl.manager.save.bind(PreferencesImpl.manager);
    exports.on                  = PreferencesImpl.manager.on.bind(PreferencesImpl.manager);
    exports.off                 = PreferencesImpl.manager.off.bind(PreferencesImpl.manager);
    exports.getPreference       = PreferencesImpl.manager.getPreference.bind(PreferencesImpl.manager);
    exports.getAllPreferences   = PreferencesImpl.manager.getAllPreferences.bind(PreferencesImpl.manager);
    exports.getExtensionPrefs   = getExtensionPrefs;
    exports.setValueAndSave     = setValueAndSave;
    exports.getViewState        = getViewState;
    exports.setViewState        = setViewState;
    exports.addScope            = PreferencesImpl.manager.addScope.bind(PreferencesImpl.manager);
    exports.stateManager        = PreferencesImpl.stateManager;
    exports.FileStorage         = PreferencesBase.FileStorage;
    exports.SETTINGS_FILENAME   = PreferencesImpl.SETTINGS_FILENAME;
    exports.definePreference    = PreferencesImpl.manager.definePreference.bind(PreferencesImpl.manager);
    exports.fileChanged         = PreferencesImpl.manager.fileChanged.bind(PreferencesImpl.manager);
    exports.convertPreferences  = convertPreferences;
});