Skip to content

Instantly share code, notes, and snippets.

@domenic

domenic/README.md

Last active June 24, 2021 16:37
Download ZIP

Revisions

  1. domenic revised this gist Aug 28, 2013. 1 changed file with 3 additions and 3 deletions.
    6 changes: 3 additions & 3 deletions printingUI.js
    View file
    Original file line number Diff line number Diff line change
    @@ -26,7 +26,7 @@ function ensureEnhancedAsync(book) {
    // Now act on that knowledge: either give up if we can't, or upgrade if we can.

    if (!couldUpgrade) {
    // This will bubble up, resulting in the promise returned from ensurePrintableAsync
    // This will bubble up, resulting in the promise returned from ensureEnhancedAsync
    // being rejected.
    throw new Error("You cannot print from the basic version, and have already downloaded "
    + "the enhanced version on another computer. Use that computer instead.");
    @@ -49,7 +49,7 @@ function ensureEnhancedAsync(book) {
    // But, when the promise is fulfilled, you can be sure that the entire printing process is done, one way
    // or another.
    exports.printAsync = function (book) {
    return ensurePrintableAsync(book)
    return ensureEnhancedAsync(book)
    .then(function () {
    return dialogs.promptAsync("What page would you like to print?").then(function (pageNumber) {
    // If they gave us a page number, print it!
    @@ -63,7 +63,7 @@ exports.printAsync = function (book) {
    });
    })
    .catch(function (error) {
    // If we got an error, either in the ensurePrintableAsync processing or bubbled up from
    // If we got an error, either in the ensureEnhancedAsync processing or bubbled up from
    // printImplAsync, alert the user.
    return dialogs.alertAsync(error.message);
    })
  2. domenic revised this gist Aug 28, 2013. 1 changed file with 2 additions and 0 deletions.
    2 changes: 2 additions & 0 deletions dialogs.js
    View file
    Original file line number Diff line number Diff line change
    @@ -1,3 +1,5 @@
    "use strict";

    var Q = require("q");
    var $ = require("jquery");

  3. domenic revised this gist Aug 28, 2013. 2 changed files with 15 additions and 12 deletions.
    25 changes: 13 additions & 12 deletions drm.js
    View file
    Original file line number Diff line number Diff line change
    @@ -1,3 +1,5 @@
    "use strict";

    var Q = require("q");
    var $ = require("jquery");
    var system = require("./system"); // Implementation not shown. It has a computerId export.
    @@ -7,24 +9,23 @@ exports.getCouldUpgradeAsync = function (book) {
    var jQueryPromise = $.get("/book/" + book.id + "/drm/status?computerId=" + system.computerId, "json");
    var qPromise = Q(jQueryPromise);

    // pluck the isEnhancedAvailable property off of the JSON result.
    // Pluck the isEnhancedAvailable property off of the JSON result. This `get` is
    // a nice Q feature that is essentially sugar for
    // `qPromise.then(function (o) { return o.isEnhancedAvailable; })`.
    return qPromise.get("isEnhancedAvailable");
    };

    // Returns a promise with no fulfillment value (equivalent to a synchronous function that doesn't return anything).
    // The returned promise will be fulfilled if the HTTP POST succeeds, meaning the enhanced license has been acquired
    // for this computer.
    // It will be broken if the HTTP POST fails (e.g. server sends back 500 error), which we interpret as meaning that
    // for some reason we couldn't assign an enhanced license to this computer.
    // Returns a promise with no fulfillment value (equivalent to a synchronous function that doesn't
    // return anything). The returned promise will be fulfilled if the HTTP POST succeeds, meaning the
    // enhanced license has been acquired for this computer. It will be rejected if the HTTP POST fails
    // (e.g. server sends back 500 error), which we interpret as meaning that for some reason we
    // couldn't assign an enhanced license to this computer.
    exports.upgradeAsync = function (book) {
    var jQueryPromise = $.post("/book/" + book.id + "/drm/acquire-enhanced-license?computerId=" + system.computerId);
    var qPromise = Q(jQueryPromise);

    // Convert a HTTP error into a meaningful error object.
    return qPromise.then(
    null, // pass through success
    function () {
    throw new Error("Could not acquire enhanced license for this computer.");
    }
    );
    return qPromise.catch(function () {
    throw new Error("Could not acquire enhanced license for this computer.");
    });
    };
    2 changes: 2 additions & 0 deletions printingUI.js
    View file
    Original file line number Diff line number Diff line change
    @@ -1,3 +1,5 @@
    "use strict";

    var Q = require("q");
    var dialogs = require("./dialogs");
    var drm = require("./drm");
  4. domenic revised this gist Aug 28, 2013. 1 changed file with 15 additions and 9 deletions.
    24 changes: 15 additions & 9 deletions printingUI.js
    View file
    Original file line number Diff line number Diff line change
    @@ -8,10 +8,12 @@ var spinner = require("./spinner"); // Implementation not shown; has start() and
    // (For simplicity let's say the user can only print one page through our interface.)
    var printImpl = window.cPlusPlusApis.print;

    // Promisify the C++ method, which happily follows the Node-style callback-with-error-as-first-argument convention.
    // Promisify the C++ method, which happily follows the Node-style callback-with-error-as-first-argument
    // convention.
    var printImplAsync = Q.denodeify(printImpl);

    // Returns a promise that will be fulfilled if and only if the book becomes (or already is) an enhanced copy.
    // Returns a promise that will be fulfilled if and only if the book becomes (or already is) an
    // enhanced copy.
    function ensureEnhancedAsync(book) {
    if (book.isEnhanced) {
    // Return an already-fulfilled promise (with no fulfillment value): we're good to go.
    @@ -22,7 +24,8 @@ function ensureEnhancedAsync(book) {
    // Now act on that knowledge: either give up if we can't, or upgrade if we can.

    if (!couldUpgrade) {
    // This will bubble up, resulting in the promise returned from ensurePrintableAsync being broken.
    // This will bubble up, resulting in the promise returned from ensurePrintableAsync
    // being rejected.
    throw new Error("You cannot print from the basic version, and have already downloaded "
    + "the enhanced version on another computer. Use that computer instead.");
    } else {
    @@ -41,24 +44,27 @@ function ensureEnhancedAsync(book) {
    }

    // The promise returned here will always be fulfilled, since we transform errors into user notifications.
    // But, when the promise is fulfilled, you can be sure that the entire printing process is done, one way or another.
    // But, when the promise is fulfilled, you can be sure that the entire printing process is done, one way
    // or another.
    exports.printAsync = function (book) {
    return ensurePrintableAsync(book)
    .then(function () {
    return dialogs.promptAsync("What page number would you like to print?").then(function (pageNumber) {
    return dialogs.promptAsync("What page would you like to print?").then(function (pageNumber) {
    // If they gave us a page number, print it!
    if (pageNumber) {
    // Start up the spinner so as to block the UI and avoid deadlocks!
    spinner.start();
    return printImplAsync(book.id, pageNumber);
    }
    // If they cancelled out of this prompt, then this method has done its job, and we can just let it return a fulfilled promise.
    // If they cancelled out of this prompt, then this method has done its job, and we can
    // just let it return a fulfilled promise.
    });
    })
    .catch(function (error) {
    // If we got an error, either in the ensurePrintableAsync processing or bubbled up from printImplAsync,
    // alert the user.
    // If we got an error, either in the ensurePrintableAsync processing or bubbled up from
    // printImplAsync, alert the user.
    return dialogs.alertAsync(error.message);
    })
    .finally(spinner.stop); // Make sure to stop the spinner on either success or failure to unblock the UI.
    .finally(spinner.stop); // Make sure to stop the spinner on either success or failure
    // in order to unblock the UI.
    };
  5. domenic revised this gist Aug 28, 2013. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion printingUI.js
    View file
    Original file line number Diff line number Diff line change
    @@ -15,7 +15,7 @@ var printImplAsync = Q.denodeify(printImpl);
    function ensureEnhancedAsync(book) {
    if (book.isEnhanced) {
    // Return an already-fulfilled promise (with no fulfillment value): we're good to go.
    return Q.resolve();
    return Q();
    } else {
    // First see if we could possibly upgrade.
    return drm.getCouldUpgradeAsync().then(function (couldUpgrade) {
  6. domenic revised this gist Aug 28, 2013. 2 changed files with 6 additions and 9 deletions.
    2 changes: 1 addition & 1 deletion drm.js
    View file
    Original file line number Diff line number Diff line change
    @@ -5,7 +5,7 @@ var system = require("./system"); // Implementation not shown. It has a computer
    // Returns a promise for a boolean.
    exports.getCouldUpgradeAsync = function (book) {
    var jQueryPromise = $.get("/book/" + book.id + "/drm/status?computerId=" + system.computerId, "json");
    var qPromise = Q.when(jQueryPromise);
    var qPromise = Q(jQueryPromise);

    // pluck the isEnhancedAvailable property off of the JSON result.
    return qPromise.get("isEnhancedAvailable");
    13 changes: 5 additions & 8 deletions printingUI.js
    View file
    Original file line number Diff line number Diff line change
    @@ -55,13 +55,10 @@ exports.printAsync = function (book) {
    // If they cancelled out of this prompt, then this method has done its job, and we can just let it return a fulfilled promise.
    });
    })
    .then(
    null, // Pass through success
    function (error) {
    // If we got an error, either in the ensurePrintableAsync processing or bubbled up from printImplAsync,
    // alert the user.
    return dialogs.alertAsync(error.message);
    }
    )
    .catch(function (error) {
    // If we got an error, either in the ensurePrintableAsync processing or bubbled up from printImplAsync,
    // alert the user.
    return dialogs.alertAsync(error.message);
    })
    .finally(spinner.stop); // Make sure to stop the spinner on either success or failure to unblock the UI.
    };
  7. domenic revised this gist Aug 28, 2013. 3 changed files with 137 additions and 143 deletions.
    96 changes: 47 additions & 49 deletions dialogs.js
    View file
    Original file line number Diff line number Diff line change
    @@ -1,58 +1,56 @@
    define(function (require, exports, module) {
    var Q = require("q");
    var $ = require("jquery");
    var Q = require("q");
    var $ = require("jquery");

    exports.alertAsync = function (text) {
    var deferred = Q.defer();

    exports.alertAsync = function (text) {
    var deferred = Q.defer();

    $("<div />").text(text).dialog({
    buttons: {
    OK: deferred.resolve
    }
    });
    return deferred.promise;
    };
    $("<div />").text(text).dialog({
    buttons: {
    OK: deferred.resolve
    }
    });

    return deferred.promise;
    };

    exports.confirmAsync = function (text) {
    var deferred = Q.defer();

    exports.confirmAsync = function (text) {
    var deferred = Q.defer();

    $("<div />").text(text).dialog({
    buttons: {
    OK: function () {
    deferred.resolve(true);
    },
    Cancel: function () {
    deferred.resolve(false);
    }
    $("<div />").text(text).dialog({
    buttons: {
    OK: function () {
    deferred.resolve(true);
    },
    close: function () {
    Cancel: function () {
    deferred.resolve(false);
    }
    });

    return deferred.promise;
    };
    },
    close: function () {
    deferred.resolve(false);
    }
    });

    return deferred.promise;
    };

    exports.promptAsync = function (text) {
    var deferred = Q.defer();

    exports.promptAsync = function (text) {
    var deferred = Q.defer();

    var $input = $("<input type='text' />");

    $("<div />").text(text).append($input).dialog({
    buttons: {
    OK: function () {
    deferred.resolve($input.val());
    },
    Cancel: function () {
    deferred.resolve(null);
    }
    var $input = $("<input type='text' />");

    $("<div />").text(text).append($input).dialog({
    buttons: {
    OK: function () {
    deferred.resolve($input.val());
    },
    close: function () {
    Cancel: function () {
    deferred.resolve(null);
    }
    });

    return deferred.promise;
    };
    });
    },
    close: function () {
    deferred.resolve(null);
    }
    });

    return deferred.promise;
    };
    58 changes: 28 additions & 30 deletions drm.js
    View file
    Original file line number Diff line number Diff line change
    @@ -1,32 +1,30 @@
    define(function (require, exports, module) {
    var Q = require("q");
    var $ = require("jquery");
    var system = require("./system"); // Implementation not shown. It has a computerId export.
    var Q = require("q");
    var $ = require("jquery");
    var system = require("./system"); // Implementation not shown. It has a computerId export.

    // Returns a promise for a boolean.
    exports.getCouldUpgradeAsync = function (book) {
    var jQueryPromise = $.get("/book/" + book.id + "/drm/status?computerId=" + system.computerId, "json");
    var qPromise = Q.when(jQueryPromise);

    // Returns a promise for a boolean.
    exports.getCouldUpgradeAsync = function (book) {
    var jQueryPromise = $.get("/book/" + book.id + "/drm/status?computerId=" + system.computerId, "json");
    var qPromise = Q.when(jQueryPromise);

    // pluck the isEnhancedAvailable property off of the JSON result.
    return qPromise.get("isEnhancedAvailable");
    };
    // pluck the isEnhancedAvailable property off of the JSON result.
    return qPromise.get("isEnhancedAvailable");
    };

    // Returns a promise with no fulfillment value (equivalent to a synchronous function that doesn't return anything).
    // The returned promise will be fulfilled if the HTTP POST succeeds, meaning the enhanced license has been acquired
    // for this computer.
    // It will be broken if the HTTP POST fails (e.g. server sends back 500 error), which we interpret as meaning that
    // for some reason we couldn't assign an enhanced license to this computer.
    exports.upgradeAsync = function (book) {
    var jQueryPromise = $.post("/book/" + book.id + "/drm/acquire-enhanced-license?computerId=" + system.computerId);
    var qPromise = Q(jQueryPromise);

    // Returns a promise with no fulfillment value (equivalent to a synchronous function that doesn't return anything).
    // The returned promise will be fulfilled if the HTTP POST succeeds, meaning the enhanced license has been acquired
    // for this computer.
    // It will be broken if the HTTP POST fails (e.g. server sends back 500 error), which we interpret as meaning that
    // for some reason we couldn't assign an enhanced license to this computer.
    exports.upgradeAsync = function (book) {
    var jQueryPromise = $.post("/book/" + book.id + "/drm/acquire-enhanced-license?computerId=" + system.computerId);
    var qPromise = Q.when(jQueryPromise);

    // Convert a HTTP error into a meaningful error object.
    return qPromise.then(
    null, // pass through success
    function () {
    throw new Error("Could not acquire enhanced license for this computer.");
    }
    );
    };
    });
    // Convert a HTTP error into a meaningful error object.
    return qPromise.then(
    null, // pass through success
    function () {
    throw new Error("Could not acquire enhanced license for this computer.");
    }
    );
    };
    126 changes: 62 additions & 64 deletions printingUI.js
    View file
    Original file line number Diff line number Diff line change
    @@ -1,69 +1,67 @@
    define(function (require, exports, module) {
    var Q = require("q");
    var dialogs = require("./dialogs");
    var drm = require("./drm");
    var spinner = require("./spinner"); // Implementation not shown; has start() and stop() methods.

    // C++ has nicely tacked this method onto the window object for us.
    // Signature: printImpl(bookId, pageNumber, onPrintDone(err))
    // (For simplicity let's say the user can only print one page through our interface.)
    var printImpl = window.cPlusPlusApis.print;

    // Promisify the C++ method, which happily follows the Node-style callback-with-error-as-first-argument convention.
    var printImplAsync = Q.denodeify(printImpl);
    var Q = require("q");
    var dialogs = require("./dialogs");
    var drm = require("./drm");
    var spinner = require("./spinner"); // Implementation not shown; has start() and stop() methods.

    // Returns a promise that will be fulfilled if and only if the book becomes (or already is) an enhanced copy.
    function ensureEnhancedAsync(book) {
    if (book.isEnhanced) {
    // Return an already-fulfilled promise (with no fulfillment value): we're good to go.
    return Q.resolve();
    } else {
    // First see if we could possibly upgrade.
    return drm.getCouldUpgradeAsync().then(function (couldUpgrade) {
    // Now act on that knowledge: either give up if we can't, or upgrade if we can.

    if (!couldUpgrade) {
    // This will bubble up, resulting in the promise returned from ensurePrintableAsync being broken.
    throw new Error("You cannot print from the basic version, and have already downloaded "
    + "the enhanced version on another computer. Use that computer instead.");
    } else {
    // Ask the user if they want to upgrade.
    return dialogs.confirmAsync("Do you want to upgrade to enhanced?").then(function (result) {
    // If they do, perform the upgrade.
    if (result) {
    return drm.upgradeAsync(book);
    } else {
    throw new Error("Since you have not chosen to upgrade, printing is not available.");
    }
    });
    }
    });
    }
    }
    // C++ has nicely tacked this method onto the window object for us.
    // Signature: printImpl(bookId, pageNumber, onPrintDone(err))
    // (For simplicity let's say the user can only print one page through our interface.)
    var printImpl = window.cPlusPlusApis.print;

    // Promisify the C++ method, which happily follows the Node-style callback-with-error-as-first-argument convention.
    var printImplAsync = Q.denodeify(printImpl);

    // The promise returned here will always be fulfilled, since we transform errors into user notifications.
    // But, when the promise is fulfilled, you can be sure that the entire printing process is done, one way or another.
    exports.printAsync = function (book) {
    return ensurePrintableAsync(book)
    .then(function () {
    return dialogs.promptAsync("What page number would you like to print?").then(function (pageNumber) {
    // If they gave us a page number, print it!
    if (pageNumber) {
    // Start up the spinner so as to block the UI and avoid deadlocks!
    spinner.start();
    return printImplAsync(book.id, pageNumber);
    // Returns a promise that will be fulfilled if and only if the book becomes (or already is) an enhanced copy.
    function ensureEnhancedAsync(book) {
    if (book.isEnhanced) {
    // Return an already-fulfilled promise (with no fulfillment value): we're good to go.
    return Q.resolve();
    } else {
    // First see if we could possibly upgrade.
    return drm.getCouldUpgradeAsync().then(function (couldUpgrade) {
    // Now act on that knowledge: either give up if we can't, or upgrade if we can.

    if (!couldUpgrade) {
    // This will bubble up, resulting in the promise returned from ensurePrintableAsync being broken.
    throw new Error("You cannot print from the basic version, and have already downloaded "
    + "the enhanced version on another computer. Use that computer instead.");
    } else {
    // Ask the user if they want to upgrade.
    return dialogs.confirmAsync("Do you want to upgrade to enhanced?").then(function (result) {
    // If they do, perform the upgrade.
    if (result) {
    return drm.upgradeAsync(book);
    } else {
    throw new Error("Since you have not chosen to upgrade, printing is not available.");
    }
    // If they cancelled out of this prompt, then this method has done its job, and we can just let it return a fulfilled promise.
    });
    })
    .then(
    null, // Pass through success
    function (error) {
    // If we got an error, either in the ensurePrintableAsync processing or bubbled up from printImplAsync,
    // alert the user.
    return dialogs.alertAsync(error.message);
    }
    });
    }
    }

    // The promise returned here will always be fulfilled, since we transform errors into user notifications.
    // But, when the promise is fulfilled, you can be sure that the entire printing process is done, one way or another.
    exports.printAsync = function (book) {
    return ensurePrintableAsync(book)
    .then(function () {
    return dialogs.promptAsync("What page number would you like to print?").then(function (pageNumber) {
    // If they gave us a page number, print it!
    if (pageNumber) {
    // Start up the spinner so as to block the UI and avoid deadlocks!
    spinner.start();
    return printImplAsync(book.id, pageNumber);
    }
    )
    .finally(spinner.stop); // Make sure to stop the spinner on either success or failure to unblock the UI.
    };
    });
    // If they cancelled out of this prompt, then this method has done its job, and we can just let it return a fulfilled promise.
    });
    })
    .then(
    null, // Pass through success
    function (error) {
    // If we got an error, either in the ensurePrintableAsync processing or bubbled up from printImplAsync,
    // alert the user.
    return dialogs.alertAsync(error.message);
    }
    )
    .finally(spinner.stop); // Make sure to stop the spinner on either success or failure to unblock the UI.
    };
  8. domenic revised this gist Aug 28, 2013. 1 changed file with 3 additions and 3 deletions.
    6 changes: 3 additions & 3 deletions printingUI.js
    View file
    Original file line number Diff line number Diff line change
    @@ -9,8 +9,8 @@ define(function (require, exports, module) {
    // (For simplicity let's say the user can only print one page through our interface.)
    var printImpl = window.cPlusPlusApis.print;

    // Promisify the C++ method, which happily follows the Node-style callback-with-error-as-last-argument convention.
    var printImplAsync = Q.node(printImpl);
    // Promisify the C++ method, which happily follows the Node-style callback-with-error-as-first-argument convention.
    var printImplAsync = Q.denodeify(printImpl);

    // Returns a promise that will be fulfilled if and only if the book becomes (or already is) an enhanced copy.
    function ensureEnhancedAsync(book) {
    @@ -64,6 +64,6 @@ define(function (require, exports, module) {
    return dialogs.alertAsync(error.message);
    }
    )
    .fin(spinner.stop); // Make sure to stop the spinner on either success or failure to unblock the UI.
    .finally(spinner.stop); // Make sure to stop the spinner on either success or failure to unblock the UI.
    };
    });
  9. domenic revised this gist May 11, 2012. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion printingUI.js
    View file
    Original file line number Diff line number Diff line change
    @@ -16,7 +16,7 @@ define(function (require, exports, module) {
    function ensureEnhancedAsync(book) {
    if (book.isEnhanced) {
    // Return an already-fulfilled promise (with no fulfillment value): we're good to go.
    return Q.ref();
    return Q.resolve();
    } else {
    // First see if we could possibly upgrade.
    return drm.getCouldUpgradeAsync().then(function (couldUpgrade) {
  10. domenic revised this gist Jan 13, 2012. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion README.md
    View file
    Original file line number Diff line number Diff line change
    @@ -8,7 +8,7 @@ The scenario:
    The problem statement:
    ----------------------

    * We want a simple `printAsync()` method that we can attach to our click handler.
    * We want a simple `printAsync()` method that we can attach to our click handler for a print button somewhere in the UI.

    The complications:
    ------------------
  11. domenic revised this gist Jan 13, 2012. 3 changed files with 4 additions and 3 deletions.
    2 changes: 1 addition & 1 deletion dialogs.js
    View file
    Original file line number Diff line number Diff line change
    @@ -1,5 +1,5 @@
    define(function (require, exports, module) {
    var Q = require("Q");
    var Q = require("q");
    var $ = require("jquery");

    exports.alertAsync = function (text) {
    3 changes: 2 additions & 1 deletion drm.js
    View file
    Original file line number Diff line number Diff line change
    @@ -1,5 +1,6 @@
    define(function (require, exports, module) {
    var Q = require("Q");
    var Q = require("q");
    var $ = require("jquery");
    var system = require("./system"); // Implementation not shown. It has a computerId export.

    // Returns a promise for a boolean.
    2 changes: 1 addition & 1 deletion printingUI.js
    View file
    Original file line number Diff line number Diff line change
    @@ -1,5 +1,5 @@
    define(function (require, exports, module) {
    var Q = require("Q");
    var Q = require("q");
    var dialogs = require("./dialogs");
    var drm = require("./drm");
    var spinner = require("./spinner"); // Implementation not shown; has start() and stop() methods.
  12. domenic revised this gist Jan 13, 2012. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion dialogs.js
    View file
    Original file line number Diff line number Diff line change
    @@ -1,4 +1,4 @@
    define(function (require, exports, modules) {
    define(function (require, exports, module) {
    var Q = require("Q");
    var $ = require("jquery");

  13. domenic revised this gist Jan 13, 2012. 3 changed files with 17 additions and 6 deletions.
    19 changes: 14 additions & 5 deletions README.md
    View file
    Original file line number Diff line number Diff line change
    @@ -2,8 +2,8 @@ The scenario:
    -------------

    * We are writing a digital textbook-reading app.
    * You get two copies of each digital textbooks: "basic" or "enhanced." Only one computer can have the enhanced copy.
    * You can only print from the enhanced copy.
    * Most of the time you have a "basic" license for your textbook, but one (and only one) of your computers can request an "enhanced" license.
    * You can only print from the computer with the enhanced license.

    The problem statement:
    ----------------------
    @@ -13,8 +13,17 @@ The problem statement:
    The complications:
    ------------------

    * If the user has the basic version, we need to check if it's possible for them to upgrade to enhanced:
    * If so, ask the user if they want to upgrade, and then continue the print operation.
    * If the user has the basic license, we need to check if it's possible for them to acquire the enhanced license:
    * If so, ask the user if they want to upgrade, and then continue the print operation if they agree.
    * If not, error out: printing is impossible.
    * Printing is an asynchronous operation, provided to us via `window.cPlusPlusApis.print`, that could fail (e.g. if the printer is out of paper).
    * Due to some horrible threaded C++ code, we get deadlocks if the user navigates through the book at the same time as the book is printing, so we need to block the UI while it prints.
    * Due to some horrible threaded C++ code, we get deadlocks if the user navigates through the book at the same time as the book is printing, so we need to block the UI while it prints.

    The plan:
    ---------

    * Use a bunch of promise methods that work together to encapsulate all this complexity into different layers.
    * The simplest of the bunch is the `dialogs` module: it just gives you some nice promise-returning, jQuery-UI-dialog-using versions of `alert`, `confirm`, and `prompt`. It exemplifies the use of deferreds to create promise-returning methods, even in situations where the asynchronous nature of the task is indeterminate (i.e. depends on the user clicking a button).
    * The `drm` module talks to the server (via Ajax) to figure out if a user's computer can upgrade to the enhanced license, or to perform the upgrade process itself. It exemplifies a few more advanced promise-consumption techniques.
    * The `printingUI` module uses the former two to create a (private) function, `ensureEnhancedAsync`, that carries out all the UI and business logic around upgrading to enhanced if at all possible. It exports a `printAsync` function, which makes use of `ensureEnhancedAsync` to do its very best to print, or error out to the user if it's not. Here we see the true power of error bubbling and promise piping.
    * Finally, some other part of the app will wire up `printingUI`'s `printAsync` export to a button somewhere. That's the easy part ;).
    2 changes: 1 addition & 1 deletion drm.js
    View file
    Original file line number Diff line number Diff line change
    @@ -4,7 +4,7 @@ define(function (require, exports, module) {

    // Returns a promise for a boolean.
    exports.getCouldUpgradeAsync = function (book) {
    var jQueryPromise = $.get("/book/" + book.id + "/drm/status", "json");
    var jQueryPromise = $.get("/book/" + book.id + "/drm/status?computerId=" + system.computerId, "json");
    var qPromise = Q.when(jQueryPromise);

    // pluck the isEnhancedAvailable property off of the JSON result.
    2 changes: 2 additions & 0 deletions printingUI.js
    View file
    Original file line number Diff line number Diff line change
    @@ -41,6 +41,8 @@ define(function (require, exports, module) {
    }
    }

    // The promise returned here will always be fulfilled, since we transform errors into user notifications.
    // But, when the promise is fulfilled, you can be sure that the entire printing process is done, one way or another.
    exports.printAsync = function (book) {
    return ensurePrintableAsync(book)
    .then(function () {
  14. domenic revised this gist Jan 13, 2012. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion README.md
    View file
    Original file line number Diff line number Diff line change
    @@ -16,5 +16,5 @@ The complications:
    * If the user has the basic version, we need to check if it's possible for them to upgrade to enhanced:
    * If so, ask the user if they want to upgrade, and then continue the print operation.
    * If not, error out: printing is impossible.
    * Printing is an asynchronous operation, that could fail (e.g. if the printer is out of paper).
    * Printing is an asynchronous operation, provided to us via `window.cPlusPlusApis.print`, that could fail (e.g. if the printer is out of paper).
    * Due to some horrible threaded C++ code, we get deadlocks if the user navigates through the book at the same time as the book is printing, so we need to block the UI while it prints.
  15. domenic renamed this gist Jan 13, 2012. 1 changed file with 0 additions and 0 deletions.
    0 printingUI → printingUI.js
    View file
    File renamed without changes.
  16. domenic revised this gist Jan 13, 2012. 1 changed file with 67 additions and 0 deletions.
    67 changes: 67 additions & 0 deletions printingUI
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,67 @@
    define(function (require, exports, module) {
    var Q = require("Q");
    var dialogs = require("./dialogs");
    var drm = require("./drm");
    var spinner = require("./spinner"); // Implementation not shown; has start() and stop() methods.

    // C++ has nicely tacked this method onto the window object for us.
    // Signature: printImpl(bookId, pageNumber, onPrintDone(err))
    // (For simplicity let's say the user can only print one page through our interface.)
    var printImpl = window.cPlusPlusApis.print;

    // Promisify the C++ method, which happily follows the Node-style callback-with-error-as-last-argument convention.
    var printImplAsync = Q.node(printImpl);

    // Returns a promise that will be fulfilled if and only if the book becomes (or already is) an enhanced copy.
    function ensureEnhancedAsync(book) {
    if (book.isEnhanced) {
    // Return an already-fulfilled promise (with no fulfillment value): we're good to go.
    return Q.ref();
    } else {
    // First see if we could possibly upgrade.
    return drm.getCouldUpgradeAsync().then(function (couldUpgrade) {
    // Now act on that knowledge: either give up if we can't, or upgrade if we can.

    if (!couldUpgrade) {
    // This will bubble up, resulting in the promise returned from ensurePrintableAsync being broken.
    throw new Error("You cannot print from the basic version, and have already downloaded "
    + "the enhanced version on another computer. Use that computer instead.");
    } else {
    // Ask the user if they want to upgrade.
    return dialogs.confirmAsync("Do you want to upgrade to enhanced?").then(function (result) {
    // If they do, perform the upgrade.
    if (result) {
    return drm.upgradeAsync(book);
    } else {
    throw new Error("Since you have not chosen to upgrade, printing is not available.");
    }
    });
    }
    });
    }
    }

    exports.printAsync = function (book) {
    return ensurePrintableAsync(book)
    .then(function () {
    return dialogs.promptAsync("What page number would you like to print?").then(function (pageNumber) {
    // If they gave us a page number, print it!
    if (pageNumber) {
    // Start up the spinner so as to block the UI and avoid deadlocks!
    spinner.start();
    return printImplAsync(book.id, pageNumber);
    }
    // If they cancelled out of this prompt, then this method has done its job, and we can just let it return a fulfilled promise.
    });
    })
    .then(
    null, // Pass through success
    function (error) {
    // If we got an error, either in the ensurePrintableAsync processing or bubbled up from printImplAsync,
    // alert the user.
    return dialogs.alertAsync(error.message);
    }
    )
    .fin(spinner.stop); // Make sure to stop the spinner on either success or failure to unblock the UI.
    };
    });
  17. domenic revised this gist Jan 13, 2012. 1 changed file with 58 additions and 0 deletions.
    58 changes: 58 additions & 0 deletions dialogs.js
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,58 @@
    define(function (require, exports, modules) {
    var Q = require("Q");
    var $ = require("jquery");

    exports.alertAsync = function (text) {
    var deferred = Q.defer();

    $("<div />").text(text).dialog({
    buttons: {
    OK: deferred.resolve
    }
    });

    return deferred.promise;
    };

    exports.confirmAsync = function (text) {
    var deferred = Q.defer();

    $("<div />").text(text).dialog({
    buttons: {
    OK: function () {
    deferred.resolve(true);
    },
    Cancel: function () {
    deferred.resolve(false);
    }
    },
    close: function () {
    deferred.resolve(false);
    }
    });

    return deferred.promise;
    };

    exports.promptAsync = function (text) {
    var deferred = Q.defer();

    var $input = $("<input type='text' />");

    $("<div />").text(text).append($input).dialog({
    buttons: {
    OK: function () {
    deferred.resolve($input.val());
    },
    Cancel: function () {
    deferred.resolve(null);
    }
    },
    close: function () {
    deferred.resolve(null);
    }
    });

    return deferred.promise;
    };
    });
  18. domenic revised this gist Jan 13, 2012. 1 changed file with 31 additions and 0 deletions.
    31 changes: 31 additions & 0 deletions drm.js
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,31 @@
    define(function (require, exports, module) {
    var Q = require("Q");
    var system = require("./system"); // Implementation not shown. It has a computerId export.

    // Returns a promise for a boolean.
    exports.getCouldUpgradeAsync = function (book) {
    var jQueryPromise = $.get("/book/" + book.id + "/drm/status", "json");
    var qPromise = Q.when(jQueryPromise);

    // pluck the isEnhancedAvailable property off of the JSON result.
    return qPromise.get("isEnhancedAvailable");
    };

    // Returns a promise with no fulfillment value (equivalent to a synchronous function that doesn't return anything).
    // The returned promise will be fulfilled if the HTTP POST succeeds, meaning the enhanced license has been acquired
    // for this computer.
    // It will be broken if the HTTP POST fails (e.g. server sends back 500 error), which we interpret as meaning that
    // for some reason we couldn't assign an enhanced license to this computer.
    exports.upgradeAsync = function (book) {
    var jQueryPromise = $.post("/book/" + book.id + "/drm/acquire-enhanced-license?computerId=" + system.computerId);
    var qPromise = Q.when(jQueryPromise);

    // Convert a HTTP error into a meaningful error object.
    return qPromise.then(
    null, // pass through success
    function () {
    throw new Error("Could not acquire enhanced license for this computer.");
    }
    );
    };
    });
  19. domenic revised this gist Jan 13, 2012. 1 changed file with 3 additions and 0 deletions.
    3 changes: 3 additions & 0 deletions README.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,14 +1,17 @@
    The scenario:
    -------------

    * We are writing a digital textbook-reading app.
    * You get two copies of each digital textbooks: "basic" or "enhanced." Only one computer can have the enhanced copy.
    * You can only print from the enhanced copy.

    The problem statement:
    ----------------------

    * We want a simple `printAsync()` method that we can attach to our click handler.

    The complications:
    ------------------

    * If the user has the basic version, we need to check if it's possible for them to upgrade to enhanced:
    * If so, ask the user if they want to upgrade, and then continue the print operation.
  20. domenic revised this gist Jan 13, 2012. 1 changed file with 3 additions and 0 deletions.
    3 changes: 3 additions & 0 deletions README.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,12 +1,15 @@
    The scenario:

    * We are writing a digital textbook-reading app.
    * You get two copies of each digital textbooks: "basic" or "enhanced." Only one computer can have the enhanced copy.
    * You can only print from the enhanced copy.

    The problem statement:

    * We want a simple `printAsync()` method that we can attach to our click handler.

    The complications:

    * If the user has the basic version, we need to check if it's possible for them to upgrade to enhanced:
    * If so, ask the user if they want to upgrade, and then continue the print operation.
    * If not, error out: printing is impossible.
  21. domenic created this gist Jan 13, 2012.
    14 changes: 14 additions & 0 deletions README.md
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,14 @@
    The scenario:
    * We are writing a digital textbook-reading app.
    * You get two copies of each digital textbooks: "basic" or "enhanced." Only one computer can have the enhanced copy.
    * You can only print from the enhanced copy.

    The problem statement:
    * We want a simple `printAsync()` method that we can attach to our click handler.

    The complications:
    * If the user has the basic version, we need to check if it's possible for them to upgrade to enhanced:
    * If so, ask the user if they want to upgrade, and then continue the print operation.
    * If not, error out: printing is impossible.
    * Printing is an asynchronous operation, that could fail (e.g. if the printer is out of paper).
    * Due to some horrible threaded C++ code, we get deadlocks if the user navigates through the book at the same time as the book is printing, so we need to block the UI while it prints.