Live Preview API

Overview

TODO

Server API

Brackets ships with 3 server implementations currently

• UserServer - Serves content from the user-specified base URL (File > Project Settings...).
• StaticServer - Serves content from the built-in HTTP server (via Node.js).
• FileServer - Serves file: URL sites locally

/**
 * @constructor
 * Base class for live preview servers
 *
 * @param {!{baseUrl: string, root: string, pathResolver: function(string): string}} config
 *    Configuration parameters for this server:
 *        baseUrl       - Optional base URL (ProjectManager.getProjectRoot().fullPath)
 *        pathResolver  - Function to covert absolute native paths to project relative paths (ProjectManager.makeProjectRelativeIfPossible(absoluteFilePath))
 *        root          - Native path to the project root (and base URL)
 */
function BaseServer(config) {}

/**
 * Returns a base url for current project. 
 *
 * @return {string}
 * Base url for current project.
 */
BaseServer.prototype.getBaseUrl = function () {};

/**
 * Returns a URL for a given path
 * @param {string} path Absolute path to covert to a URL
 * @return {?string} Converts a path within the project root to a URL.
 *  Returns null if the path is not a descendant of the project root.
 */
BaseServer.prototype.pathToUrl = function (path) {};

/**
 * Convert a URL to a local full file path
 * @param {string} url
 * @return {?string} The absolute path for given URL or null if the path is
 *  not a descendant of the project.
 */
BaseServer.prototype.urlToPath = function (url) {};

/**
 * Called by LiveDevelopment before to prepare the server before navigating
 * to the project's base URL. The provider returns a jQuery promise.
 * The Live Development launch process waits until the promise
 * is resolved or rejected. If the promise is rejected, an error window
 * is shown and Live Development does not start..
 *
 * @return {jQuery.Promise} Promise that may be asynchronously resolved
 *  when the server is ready to handle HTTP requests.
 */
BaseServer.prototype.readyToServe = function () {};

/**
 * Determines if this server can serve local file. LiveDevServerManager
 * calls this method when determining if a server can serve a file.
 * @param {string} localPath A local path to file being served.
 * @return {boolean} true When the file can be served, otherwise false.
 */
BaseServer.prototype.canServe = function (localPath) {};

/**
 * Adds a live document to server
 * @param {Object} liveDocument
 */
BaseServer.prototype.add = function (liveDocument) {};

/**
 * Removes a live document from the server
 * @param {Object} liveDocument
 */
BaseServer.prototype.remove = function (liveDocument) {};

/**
 * Clears all live documents currently attached to the server
 */
BaseServer.prototype.clear = function () {};

/**
 * Start the server
 */
BaseServer.prototype.start = function () {};

/**
 * Stop the server
 */
BaseServer.prototype.stop = function () {};

Example Server Implementation

The snippet below is simplified from the Theseus JavaScript Debugger Extension. It shows a minimal implementation for creating and registering a live preview server.

var LiveDevelopment = brackets.getModule("LiveDevelopment/LiveDevelopment"),
    BaseServer      = brackets.getModule("LiveDevelopment/Servers/BaseServer");

function ProxyServer(config) {
    BaseServer.call(this, config);
}

ProxyServer.prototype = Object.create(BaseServer.prototype);
ProxyServer.prototype.constructor = ProxyServer;

ProxyServer.prototype.canServe = function (localAbsoluteFilePath) {
    return myTestIfFileTypeCanBeServedAsAWebPage(localAbsoluteFilePath);
};

ProxyServer.prototype.readyToServe = function () {
    var deferred = new $.Deferred();
    // ... async initialization of server ...
    return deferred.promise();
};