Links to this:

[Note that before writing this I did seek out existing implementations, and found js-preprocess to be the most interesting; However, I needed something that would work as part of an existing build chain, so authoring the tool in Python instead of JavaScript made more sense.]

Currently, jsmacro is poorly named, as I didn’t write the macro system that was in my head. Instead, it’s currently a basic preprocessor supporting only DEFINE and IF statements, which happened to be all I needed at the time. Usage works like this:

Input JavaScript

  //@define DEBUG 0

  var foo = function() {
    //@if DEBUG
    alert('This.');
    alert('That.');
    //@end

    print "Hi";
  };

Pass the above JavaScript through jsmacro from the command line like this: ./jsmacro.py -f infile.js > outfile.js (assuming the files are all in the same directory), and you get the following:

Output JavaScript

  var foo = function() {

    print "Hi";
  };

The tool has registered the variable ‘DEBUG’ as 0 (i.e., false), so the conditional include statements omit the alert() calls. If DEBUG had been set to 1 (i.e., true), the alert() statements would remain (though all jsmacro instructions would be removed either way.)

One of the tricky things about doing macros or preprocessing in JavaScript is that I wanted the code to be valid JavaScript before the tool is run (which is why C-preprocessors won’t work.) The idea is that you develop as you normally would, but wrap your debug and testing code in conditional jsmacro statements so that they are automatically removed as part of your build process.

There’s nothing fancy about the current implementation (it’s a crude state machine that scans line-by-line, top-to-bottom looking for regex patterns and deciding whether to output the line of not.) Crude as it may be though, it completely solved a problem for me, and hopefully it will help you out as well.

CmdUtils.CreateCommand({
  name: "expandlinks",
  homepage: "http://eriksmartt.com/blog/",
  author: { name: "Erik Smartt"},
  license: "MPL",
  preview: "Expands all hyperlinks, showing link locations.",
  execute: function() {
    var doc =  Application.activeWindow.activeTab.document;
    jQuery(doc.body).find("a").each(function(i) {
        jQuery(this).after(" &lt;<a href='" + this.href + "'>" + this.href + "</a>&gt;");
    });
  }
})

And yes, it will be much easier to subscribe to these commands once I gather them into a JS file for Ubiquity. For now, you can copy/paste into the command editor if you’re interested in trying it out.

CmdUtils.CreateCommand({
  name: "charcount",
  takes: {"text to count chars in": noun_arb_text},
  preview: function( pblock, argText ) {
    pblock.innerHTML = argText.text.length;
  }
})

Update: See comments below for Ubiquity 0.5 compatibility updates

Extending Ubiquity’s vocabulary is done via JavaScript, and the developer docs are pretty straight forward.

The docs cover Hello World, so I figured that the next best intro test would be a way to lookup stock charts and quotes. Here’s the result of a few minutes hacking on it:

CmdUtils.CreateCommand({
  name: "tik",
  takes: {"stock ticker symbol": noun_arb_text},
  preview: function( pblock, argText ) {
    var charturl = "http://chart.finance.yahoo.com/c/1y/a/" + argText.text;
    pblock.innerHTML = "";
  },
  execute: function( argText ) {
    var windowManager = Components.classes["@mozilla.org/appshell/window-mediator;1"]
                      .getService(Components.interfaces.nsIWindowMediator);
    var browserWindow = windowManager.getMostRecentWindow("navigator:browser");
    var browser = browserWindow.getBrowser();
    var url = "http://finance.google.com/finance?q=" + argText.text;
    browser.loadOneTab(url, null, null, null, false, false);
  }
})

This command introduces a ‘tik’ keyword, which loads 1-year stock symbol charts (from Yahoo) into the preview pane, and allows click-through to open a new tab for the Google Finance page of said symbol. Note that the preview-pane doesn’t always resize correctly for the chart to fit (though you can generally make it happen by typing a space after the stock symbol.) I guess there’s still some work to do there.

• Targeted at developers wanting to learn Django by building example applications rather then (or in addition to) reading the docs and man pages
• The reader builds three working applications by following along
• The examples are based on up-to-date Django features (ie., a 2008 build)
• Lesson’s focused on using Django (not on Django’s inner workings)
• Doesn’t waste time explaining Python and HTML (nor does it dive deep explaining the how/why of what you’re doing in the examples)
• Introduces the reader to powerful Django features — covering a wide range of capability
• Examples focus on designing for code reuse (and leading by example, by integrating with existing reusable apps and Python libraries)
• Offers an alternative approach to learning, focused on relevant, practical examples

Background:

Practical Django Projects (Apress book description) was written by James Bennett, release manager and contributor to the Django Web Framework. It was published by Apress in 2008. This was Bennett’s first book.

Full disclosure: I was provided with a free, review-copy of the book by Apress.

The Book:

Practical Django Projects introduces the reader to the Django Web Framework by example. It takes the reader step-by-step through three example projects: a basic CMS, a blog application (called Coltrane, which powers the author’s personal blog), and a code-sharing/snippets site (called Cab, which powers http://www.djangosnippets.org/.) The examples cover real-world problems (and integration tasks) that developers are likely to be interested in, and leaves the reader with three working Django applications.

The lessons are spread across eleven chapters:

1. Welcome to Django — a wonderfully short introduction that wastes no space explaining prerequisites (it assumes the reader knows Python)
2. Your First Django Site: A Simple CMS — an introduction to the Django Admin and Flatpages
3. Customizing the Simple CMS — customizing the Admin interface (adding TinyMCE) and developing a simple, reusable search feature
4. A Django-Powered Weblog — defining the basic models, and using django-tagging and Generic Views
5. Expanding the Weblog — adding del.icio.us-synced links, and custom categories
6. Templates for the Weblog — more extensive use of Generic Views, template inheritance, and custom template tags
7. Finishing the Weblog — using django.contrib.comments and model signals to develop a moderation system with email notification and Akismet integration; Using django.contrib.syndication to add RSS/Atom feeds
8. A Social Code-Sharing Site — building the initial models, integrating with the pygments syntax highlighter, and writing custom model managers
9. Form Processing in the Code-Sharing Application — great examples of using newforms (much better then the The Definitive Guide to Django‘s chapter on form processing)
10. Finishing the Code-Sharing Application — more custom template tags, this time used with bookmarking and rating features
11. Writing Reusable Django Applications — a summary of Bennett’s philosophy on decoupling application features into reusable components (with references to the UNIX saying, “do one thing, and do it well”)

The examples focus on building applications the “Django way” — meaning that they heavily leverage Django features such as Generic Views, custom template tags, and the django.contrib package. Each section starts by outlining the features to be developed, then walking the reader through model definitions, URLs, template design, and the request-handler (view) code.

While working through the three example applications, Bennett teaches the reader how to decouple applications from projects, how to think about (and look for) opportunities for code reuse, and how to integrate with other reusable Django applications. The lessons aren’t so much “how does Django work”, but rather “how do you, as a developer, structure your projects to get the most out of the framework.” Depending on your level of comfort using Django and Python, the lessons will either be a breeze, or ridiculously confusing. (ie., there’s a lot of magic going on in the examples, and the book assumes that either you get it, you’re comfortable not knowing, or that you’ll figure out the finer bits when you need them.)

The Core Message

Ultimately, the book isn’t so much about learning Django, as it is about learning how to use Django properly (where properly is defined as the way in which the Django developers use Django.) From this perspective, it’s quite successful. The reader is shown a number of patterns and concepts that can be applied to any Django project.

Bennett wraps up the book with a chapter on design philosophy, but I think the overall lesson of the book is best summarized on page 124, with the following quote:

…this is the hallmark of a well-built Django application. Installing it shouldn’t involve any more work than the following:

1. Add it to INSTALLED_APPS and run syncdb.
2. Add a new URL pattern to route to its default URLConf.
3. Set up any needed templates.

This is the zen of pluggable Django applications. It’s the path Bennett wants to help you start down. The value of going down this path will depend on how often you’ll use Django in the future.

Conclusion:

Overall, I think the book will be more valuable for someone just getting started with Django, then someone who’s been hacking lower-level with the framework for awhile. It’s a developer-focused, quick-start, “get you on the right foot” kind of book that I certainly would have appreciated more a few years ago. The big question then, is whether this book is for you. The answer depends on a couple things, with the most important being how you like to learn. Do you prefer learning by example, or learning by reading the docs and building things on your own? If you prefer to have an expert guide you step-by-step, then this book is for you. You’ll still need to poke around in the Django documentation to really grok how it all works, but this book will get you up to speed quickly.

If you’ve read the docs, done the online tutorials, and are still interested in picking up some best-practices on decoupling your code from your specific application (ie., learning how Django supports code reuse), then this may still be a book for you. If you know you’ll be building a large application, the lessons in the book might help prevent you from writing a single, monolithic application, or at least give you some insight into how to organize and package your code. Down the road you’ll thank yourself.

For me personally, I was actually looking forward to this book before it came out. I think the Django docs online (as great as they are) can sometimes lack in providing best practices. However, I’ve also been using the framework professionally for a number of years (to deploy personal, start-up, and enterprise-class web applications), and I’ve previously built and deployed a pluggable, multi-site, Django-based blog engine (with del.icio.us and Akismet integration, flexible moderation rules, etc.), so the idea of using a blog engine as the core example in the book was a bit disappointing. That said, I did enjoy seeing another developer’s approach on solving the same problem, and I picked up a few nice tips around some of the more recent Django features.

If you’re looking to build a reusable code library (and you should be, if you’re going to build more then one Django project) and ensure that you’re using Django efficiently, this book will help point you down the right path and have you thinking about decoupling your architecture from the start.

Sadly, the news started showing up with quotes and claims that the statement may actually be true. “Netflix Eliminating Account Profiles” (on hackingnetflix.com) claims that “Netflix spokesperson Steve Swasey said that the decision to eliminate Profiles is a ‘final decision.’”

Here’s the kicker though; The now famous email ends with, “While it may be disappointing to see Profiles go away, this change will help us continue to improve the Netflix website for all our customers.” Really? How so?

For those not familiar with Netflix Profiles, the feature was somewhat unique. Instead of having a single persona per account, Netflix Profiles allowed a single account (ie., household) to setup multiple profiles (ie., husband, wife, kids, pets, etc.), so that each profile could manage their own rental queue. It also allowed the main account holder (ie. the parents) to review the other profile’s queue (ie., the kids) and set limitations, like whether the profiles were allowed to rent R-rated movies. The feature was amazingly helpful in eliminating arguments about who controlled the rental queue.

Removing features from a product can be a tough decision for any Product Manager. Features that are rarely used are easy to toss aside; But (market differentiating) features that customers love should never be thrown out without helping the customers replace or replicate the same benefit in another manner. In this case, Netflix dropped a much-loved feature, but left their customers without an alternative (other then opening more Netflix accounts, which isn’t a likely reaction for irritated customers.)

For more:

• Netflix Eliminating Profiles: Tells Us We Don’t Own Our Data

[Update: 2008-06-30] Complaining works! Netflix just announced that they are keeping Profiles:

You spoke, and we listened. We are keeping Profiles. Thank you for all the calls and emails telling us how important Profiles are.

We are sorry for any inconvenience we may have caused. We hope the next time you hear from us we will delight, and not disappoint, you.

Background

The book was written by Adrian Holovaty and Jacob Kaplan-Moss, the creators and “Benevolent Dictators” of the Django Web Framework. It was Holovaty and Kaplan-Moss’ first book, and, I believe, meant to be the first Django book to market. The book was drafted online; open to peer-review and community feedback; and ultimately published under the GNU Free Documentation License.

From the get-go, the print edition had a few inherent market challenges to face: First, the entire book is available online, for free, at: <http://www.djangobook.com/>. Second, in many ways the book is a re-hash of the docs available at <http://www.djangoproject.com/documentation/>, which are also free. Third, the book covers Django 0.96, not SVN. (0.96 is technically the latest-snapshot release, but a lot has changed since 0.96.) And finally, the $45 MSRP could be seen as a little steep for what is effectively a printed copy of a free, online book.

The print experience

Diving in, the book takes the reader through the basic installation process, provides a brief background on how the framework came to be (and why you want one), then steps through the major features (ie., the template system, ORM, URLconfs, generic views, etc.) It’s what you’d expect from a technical reference — no fluff, and straight to the details. There are plenty of code snippets to learn from, and the sidebar notes tend to be insightful.

Since it wasn’t new material for me, the book was a fairly quick read; but the experience of reading Django documentation in book-form was actually quite fascinating. There’s something about settling into a comfortable chair with a book, pen, and highlighter that you just can’t get with online documentation. Perhaps it was just a little more noticeable given the material. When I read the Django docs online, I tend to skim over them while trying to solve a problem. I use them as a reference more then a learning tool, and it’s usually while actively coding, thus my brain is partially distracted with whatever it is I’m building.

With a physical book, you can unplug, step away from the computer, and give the material your undivided attention. This isolation from distraction results in a much deeper understanding of the text. This is the real the value of the printed book — it’s an opportunity to digest online documentation in an environment more conducive to learning and retention.

My general take-aways and observations

• The book definitely has a beginner/intermediate feel to it, but only in the sense of a beginner Django user — not a beginner Web developer or Python programmer. I’m curious how well the book is received by folks who are beginners at Django and dynamic Web development since the text brings up a lot of complex topics in Web development that aren’t really explained. (Ex., database administration, server clustering, manipulating HTTP headers, etc.)
• The breadth of the book is impressive, but in some ways, the book really feeds you through a firehose, so to speak. It throws a lot of new concepts at the reader and doesn’t always explain why you’d need to know them, or how you might use them in the real world. For someone deploying a site with Django, it will be good to know that all these features are available, but it might take awhile before they need to use them (if ever.)
• The book does touch on some of the more advanced Django features (like extending the template system and writing custom middleware), which was nice, but some topics are reserved for the appendix and get limited coverage (ex., model managers and ‘Q’ queries.) Others, like the Sites Framework, are given good exposure, but not so much that the reader is left with a clear picture on when to use them and what their limitations are.
• The forms processing chapter was a bit lighter then what I was hoping for — especially given that the current newforms documentation still trends toward “read the source code.” It provides enough to start using newforms if your form needs are pretty basic, but doesn’t address creating your own widgets, or any of the fun stuff you can do once you start dynamically generating and manipulating newforms objects.
• It might have been nicer if the examples in the book were a little more tied together, perhaps all focused on building a single example project and showing how the various features are used in real-world applications. (The example of the book-publisher’s app was a reoccurring theme, but not so strongly that each chapter applied it’s new learnings to it.)
• The Deploying Django: “Going Big” sub-section provides a nice infrastructure graphics for how high-traffic systems might be setup, but once you get to the point of being “big”, you need to architect for it, and that’s really outside of the scope of this book. For this section, it might have been nice to reference other resources on scaling infrastructure, and perhaps pointing out some of the ways that Django can be optimized for performance and horizontal scaling. (For example, one of the Django projects we put into production at work will happily support 1,200 requests/second, but the database layer and session middleware have been reworked a bit, and the content caching approach is a little different then the standard Django offering.)
• On the more positive side, even as someone who’s been using Django for some time, I still learned a few new tricks, and I was reminded of a few features that I could be taking better advantage of. (And when you do this stuff professionally, every shortcut and productivity gain has monetary value — avoiding even a half-hour of debugging pays for the cost of this book.)
• This book would make a fantastic read for a back-end developer joining a project that is already using Django. I normally tell new developers to go through the Python Tutorial at <http://python.org/doc/tut/> if they’re new to Python, then to complete the Django Tutorials at <http://www.djangoproject.com/documentation/> before trying to grok any in-progress Django project. Now I have a third reference (though I might still suggest that they walk through the tutorials first, so that they have some context when reading the book. Otherwise, there are just too many new concepts to do a straight read-through and still grasp it all.)

Summary

The market needed a good Django book, and this one delivered a solid reference for the framework. Arguably, it’s not really a “Beginner’s Guide to Django”, but hopefully it covers enough of the basics that future books can focus on best practices and more advanced techniques. (On a related note, there’s apparently an upcoming “Practical Django Projects” book, also from Apress, that will focus more on building “reusable Django applications from start to finish”. This might actually make for a better beginner’s book, depending on how it turns out. [Via The B-List: Speaking and writing].)

The million-dollar question then, is “Should you buy this book?” My answer ended up being a bit more positive then I expected, but there are two parts: First, if you’re a front-end developer only, you don’t need this book. You can just read Chapter 4: The Django Template System online, and then use the “Django Templates: Guide for HTML authors” section of the online docs as a reference. For back-end developers, the story is different. If you’re going to just “read it while you hack”, then you might as well just read it online; but if you’re serious about building applications with Django (especially if you’re new to it), then you should consider the book and investing the time to step away from the computer and really let yourself get into it. Unless you are an active contributor to Django (which I’m not, just to be clear), the odds are pretty good that you’ll learn something new, even if you’re already using Django today.

It’s difficult to explain without visuals, so let’s start with a traditional looking URL:

The traditional-looking URL is a bunch of text. We recognize it as a URL, and typically market it as a full-text string. However, many sites use non-friendly URLs (think Vignette CURLs, for those who know what I’m talking about), in which case URLs are often massive strings full of seemingly random characters. When surfing sites with such URLs, the browser’s location bar becomes something you ignore until you’re ready to type in a new address.

Now let’s look at a Location’ized version of the same URL:

Quite different! The Location’ized URL is a distinct representation of a domain name (“eriksmartt.com”), and a service (“blog”). Information we don’t need, which normally just causes visual clutter (like the ‘/’ characters), has been greyed-out, and brand-recognition remains strong.

Here’s another example:

Just looking at that URL, it’s pretty clear what site I was on, and what I was asking for — which is exactly what a URL is. Writing out http://flickr.com/photos/tags/lolcat loses some of this meaning. It becomes a single address, rather then a service and a request.

Of course, clever domain-names can lose some of their brand recognition using this approach:

Still, I’ve already grown so accustom to seeing URLs as Locationbar² displays them, that it feels disappointing to use browsers lacking this capability. I’ve also found the tool to be extremely handy while developing websites, making it very clear which server I’m accessing, and what request I made.

YMMV, but I definitely recommend trying it out — and I’d love to hear about your experience using the add-on!