Monty Lounge Blog feed

In Review of Sass

Thu, 04 Aug 2011 08:15:59 -0400

Four months ago I presented "Quickstart to Sass/Less.js CSS" at the Jersey Shore Tech meetup and it's about time to share my thoughts. Although my talk covered both Sass and Less.js today we will only cover Sass as it's the tool I use more often. If you're interested in Less.js I did recently post one thing about Less.js.

To learn more about the Sass project go check out the project site Sass-lang.com and make sure to follow TheSassWay and Compass on Twitter to keep up-to-date with Sass and Compass news. We'll dicsuss Compass in a bit.

Overview of Sass

Sass is an extension of CSS, and as its tagline says, it "... makes CSS fun again".

But what does that really mean? It means Sass and provides additional features on top of CSS helping organize your CSS into cleaner, more manageable code and promotes reuse through @mixins, @extends, @includes. Together these help reinforce the DRY principle. Sass executes these features by compiling your source .scss/.Sass files and producing valid .css files.

Compilation huh what?

The thought of compilation may be foreign to you, and if it is then here's a brief description as to why it needs to happen.

As we discussed, Sass adds extensions to CSS. Something as simple as a variable is not known to CSS. In Sass it's as simple as...

//source app.scss file
$button-buy-color: #ff0000;

Then for all the styles you want to reference `$button-buy-color`. Here's a very basic example:

// source app.scss file
#sale button
{
  background-color: $button-buy-color;
}

#special button
{
  background-color: $button-buy-color;
}

To get the above to render the correct CSS you need to let Sass compile it using the `sass app.scss app.css'. command. The compilation would generate:

// resulting app.css file
#sale button
{
  background-color: #ff0000;
}

#special button
{
  background-color: #ff0000;
}

The end result of Sass compiling your .scss file is a .css file. In the above example if we wanted to change the color for all "buy buttons" we would just have to change the value in one location.

Actually, another way to think about compilation — you could create a valid CSS file, using no Sass features, but save your file with the .scss extension and it would still be a valid Sass file when compiled. You don't need to use features of Sass in your .scss files for them to compile correctly, but if you're doing that then just create `.css` files.

So, Sass files must be compiled prior to deployment. You can compile them on your local machine, as part of your build/deploy process, etc. Referencing a .scss file in the of you HTML templates will do you no good. This is incorrect...

<link rel="stylesheet" href="/css/whatever.scss" media="screen" />

The end the goal we're all aiming for is to produce quality CSS and Sass helps you get there and beyond. It just may take one additional step to get you there... compilation.

Sass Features

What are these killer features? The ones I use most often are mixins, functions(), variables, nested rules various @-rules and directives, parent selectors and sometimes operations. We'll discuss some of these in a bit along with some code examples, but before we go any further serving up pints of the Sass Cool Aid let's discuss why you may not want to use Sass, and some of the reasons I initially didn't buy into it.

Why not Sass?

For noobs being introduced to Sass I can easily see why you might think this is an over-engineering for something as simple as CSS. Why add a compilation step to render CSS? This isn't server side code! The argument has some weight, but I'd argue you can't really begin to grasp the utility of these tools until you get your hands dirty.

My initial introduction to these CSS extensions was actually CleverCSS. This and my curiosity in similar solutions eventually led me over to Sass, which at the time only offered the indented syntax. As a reminder the indented syntax looks like this...

@mixin table-base
  th
  text-align: center
  font-weight: bold
  td, th
  padding: 2px

No semicolons? White-space sensitivity in CSS!? What is this "@mixin" directive? I was immediately turned off. Here's why...

First, Sass's original, unindented syntax was a bit too foreign to me. It's just CSS, why are we breaking convention? If I'm going to use this or my team is going to use this, or a new hire is going to use this, then it should be familiar. The updated "Sassy" syntax resolves this concern.

Next, the idea of a pseudo programming language intertwined with CSS seemed over-engineered. Mixins, variable, control directives, oh my! Such things aren't meant for CSS! CSS is about style, not programing. Right? Boy was I wrong. These "complexities", as I initially viewed them, are powerful features for making CSS organized, reusable, concise, and in the end... simple.

Then there's the introduction to yet another dependency... Ruby. There's no way around this one. You will need to add it to your stack to compile your Sass source files.

Next, there's the new step/disruption to your existing workflow - compilation. This one is hard to avoid as well. You can't just edit your css file and view the resulting CSS changes locally without compilation. You have to edit the .scss and then compile it. It's not as difficult as it sounds though, and Sass comes with a handy `--watch` option which makes this esentially painless. Again, this is a trade-off I'm willing to make.

Finally, probably the largest obstacle with these CSS extentions is debugging. Sass itself provides a terrific debugger — if there are syntax errors with your .sass/.scss files then Sass will display what file and line raised the exception. This is great. But if your trying to figure out why something isn't displaying in the browser correctly then the features offered by Sass (i.e. mixins, includes, extends, etc) come at the expense of the pre-processing compilation of your Sass source files, and result in a less forgiving debugging process. For example, a style defined on line #32 of one of your .scss files may render on line #153 of a resulting .css file. This one hurts the most.

All of the above and you still think we need Sass? We've gone so long without these features why do we need them now? Let's be honest we all know you don't *need* them.

Nathan Borror, creator of Readernaut, shares some of my same concerns discussed above. His post from 2009, "Sass isn't for me" is a great critique especially for the comments discussion. Some of his issues have been resolved since the post (sassy syntax and whitespace sensitivity, for example). Nathan later posted "Less.js is more", a follow up where he details his Less.js impressions. Sadly both of these posts no longer exist. I followed up with Nathan recently and he no longer uses either much these days. He added, "I really do respect and admire what people are trying to do in this space and it's up to the developer to decide what's right for their situation. I kind of regret the two blog posts because, while I tried to be constructive and spark an intelligent discussion, it ultimately comes down to deciding which tool helps make your product great."

I couldn't agree more with Nathan.

So Why Sass then?

For me, Sass's features provide a more reusable and more easily maintainable code base and therefore the benefits outweight any of the above changes to my process.

My favorites features of Sass is the @mixin, arguably the most powerful feature. It allows the developer to encapsulate display code into reusable components, keeping your code concise, reusable, and easily maintained. Here's a basic example. The below mixin provides base functionality for a standard message UI element on a website.

@mixin user_message($bgcolor: #CCC, $color: #FFF, $border: left){
padding: 20px;
background-color: $bgcolor;
border-#{$border}: solid 2px darken($bgcolor, 40%); 
color: $color;
margin-bottom: 10px
}

The above is a Sass mixin with a bunch of Sass features employed. It uses arguments `($bgcolor: #CCC, $color: #FFF, $border: left)` with default values to allow the developer to specify various properties. If you notice `border-#{$border}:` I'm using interpolation to inject the variable value into the style definition. I'm also using darken() which is an HSL function to dynamically set the color of the border I specify.

I can then implement the below for 3 various message elements (server error is a bit contrived). Here's my app.scss snippet:

@import "message";


// this uses the default arg values

.message{
  @include user_message();
}

//this overrides all the args

.error{
  @include user_message(#F5F5F5, #FF0000, right);
}

// this extends the above error style with some additions
.server-error
{
  @extend .error;
  font-size: 220%;
  border: solid 5px red;
}

In the above I've used the @import directive, the @include directive, referenced the `user_message` mixin, and the @extend directive. These are the core methods used in reusing code throughot your project. Read the docs to get more familiar with them, or better yet try them out yourself and break things to learn.

Back to the code. The above results in this after the app.scss is compiled:

.message {
  padding: 20px;
  background-color: #cccccc;
  border-left: solid 2px #666666;
  color: white;
  margin-bottom: 10px;
}

.error, .server-error {
  padding: 20px;
  background-color: #cccccc;
  border-left: solid 2px #666666;
  color: red;
  margin-bottom: 10px;
}

.server-error {
  font-size: 220%;
  border: solid 5px red;
}

As you can see my source .scss file is more concise. I've created a reusable message mixin. From there I've reused this mixin on the `.message` and `.error` classes and then again on `.server-error` where I've gone and extended the `.error` class which is reusing the message mixin above. And if I ever want to change the structure or style of all my user message UI elements on my site I just update the user_message @mixin in one place.

Let's take it a bit further and review the popular rounded corners example by making it reusable and easily maintainable.

Here's what it would take to style a rounded corners class in CSS today:

.multi-rounded-corners{
  -webkit-border-top-left-radius: 5px;
  -webkit-border-top-right-radius: 5px;
  -webkit-border-bottom-right-radius: 5px;
  -webkit-border-bottom-left-radius: 5px;
  -moz-border-radius-topleft: 5px;
  -moz-border-radius-topright: 5px;
  -moz-border-radius-bottomright: 5px;
  -moz-border-radius-bottomleft: 5px;
  border-top-left-radius: 5px;
  border-top-right-radius: 5px;
  border-bottom-right-radius: 5px;
  border-bottom-left-radius: 5px;
}

Writing this often becomes redundant and time consuming. Dan Cederholm, author of CSS3 for Web Designers recently tweeted, "Crafting Sass mixins for oft-used CSS3 stacks. The time-saver of all time-savers. Native variable/mixin suport for CSS4 please thanks.""

I agree! Using Sass we can create one mixin and then reuse this as often as we like. Then, if we need to add a change to support another browser, for example, we just edit this one mixin and the rest of our code is updated as well. Here's the mixin and Sass implementation that also provides arguments for specifying the corner radius values:

@mixin multi-rounded-corners($topLeft: 5px, $topRight: 5px, $bottomRight: 5px, $bottomLeft: 5px) {
  -webkit-border-top-left-radius: $topLeft;
  -webkit-border-top-right-radius: $topRight;
  -webkit-border-bottom-right-radius: $bottomRight;
  -webkit-border-bottom-left-radius: $bottomLeft;
  -moz-border-radius-topleft: $topLeft;
  -moz-border-radius-topright: $topRight;
  -moz-border-radius-bottomright: $bottomRight;
  -moz-border-radius-bottomleft: $bottomLeft;
  border-top-left-radius: $topLeft;
  border-top-right-radius: $topRight;
  border-bottom-right-radius: $bottomRight;
  border-bottom-left-radius: $bottomLeft;
}

Hey, why don't we make our message element have rounded corners as well! To reuse the @multi-rounded-corners in our application's .scss file we just add one line to reference the `multi-rounded-corners()` mixin.

@import "message";

.success{
  @include user_message();
  @include multi-rounded-corners();
}

And whala! We now have a "success" style that reuses both our @user_message and @multi-rounded-corners mixins. Code is now organized. Simpler to read. Simpler to update. Go take that long lunch break.

Learning Sass

The first thing you want to know is how to use this thing. The official Sass tutorial is a great place to start.

If you like screencasts the people over at ThinkVitamin are producing an entire series on the subject. You can watch the first episode Sass Introduction for free.

I highly recommend watching the below, terrific screencast as well, titled Kicking Ass and Taking names with Sass and Compass. Seriously, make sure you watch this as Nathan created a very well produced screencast with a handful of great examples and code review. We haven't discussed Compass yet, we do briefly below, but I suggest familiarizing yourself with in your next step along the SassWay.

Kicking Ass + Taking Names with Sass & Compass from Nathan Henderson on Vimeo.

So there's plenty information out there already if you're looking to learn, and more and more being published each day. Check out Forrst and Github for more Sass examples.

Is Sass a Framework?

I often hear this question asked. Sass is not a framework. It's an extension of CSS. Sass offers the interface to execute these extensions. Compass is a framework. From their docs...

"Compass, at its heart, is a framework upon which Sass-based stylesheet frameworks are built. It provides the tools for building, installing and using reusable stylesheets that provide anything from full-fledged layout frameworks to designs for widgets or even full page designs. All using the power of Sass to keep the semantic meaning of the html pages clear and free of design details."

For those familiar with Django or Rails, here's a good analogy (via Idan Gazit) between Sass and Compass — "Compass is the Django, Sass is the Python or Compass is the Rails, Sass is the Ruby."

Just like the above, Python and Ruby are the core languages that make Django and Rails frameworks possible. You can write Sass without Compass, but you can't build a Compass extension without Sass. And just like these web frameworks Compass also provides additional utility, conventions, best practices, documentation, community contributed libraries, and is continuously developed and tested (Go fork it on Github now!). For example, take a look at Compass core for various helpers/utilities. Checkout Compass blueprint for your layout needs. Want some fancy buttons? You can install the fancy buttons Compass plugin the community created, or if you want to get on the responsive design train hook the Less Framework (not Less.js) check out compass-less-plugin. There's also Idan Gazit's Sinter for a minimal approach to responsive design for Compass. So you get the idea - the open source community is contributing and building a community of this plugins.

Diving full into Compass and all its features requires an additional, lengthier discussion (for example a Compass extension can include JS files and Images). Make sure to check it out though because it's extremely powerful.

Conclusion

The above code snippets are very basic examples but I hope communicate the concepts of how and why you would want to include Sass in your projects. One large project that employs Sass and makes its code freely available is Sencha Touch. If you want to take a look at how a large, publicy available project integrates Sass then Sencha Touch is a good place to start. In fact, they recently published an advanced Sass implementation Touch Charts Styling which makes for a good read just to see how far you can push Sass with a little creativity. If you know of others please drop them in the comments below.

As I mentioned, you don't begin to appreciated the utility of Sass until you use Sass in your projects. The project site and documentation for both Sass and Compass are terrific which lessens the barrier to entry. And although there are some learning curves along the way, once you get passed those little bumps, just like many others have already, you'll find yourself not wanting to look back.

Before we leave, Sass 3.0 introduced a new command line utility `sass-convert` which makes converting existing CSS to Sass a breeze, even converting some of your existing styles into Sass compliant nested rules where appropriate. Someone also created a web UI to do this over at CSS 2 Sass. So what are you waiting for?

One thing about Less.js

Sun, 31 Jul 2011 21:34:47 -0400

I don't use Less.js on any projects, but I have used it to create prototypes just to familiarize myself with Less.js while I was researching both Sass and Less.js.

Node.js isn't in my current development stack, so server side pre-processing of my .less files isn't an option (Node.js is required to pre-process your .less files before deployment). Therefore, I leveraged my favorite feature of Less.js, client side processing, which is actually pretty awesome for one main reason — you don't have to interrupt your current development workflow with any pre-deploy processing steps.

This addition of a pre-processing step in your workflow isn't a huge deal to many but for those not looking to add additional requirements to their stack (i.e. Node.js for Less.js or Ruby if you're using Sass) then this is any easy way to start playing around with this popular CSS extension.

So, Less.js processes your `.less` files client side, supporting IE 6+, Webkit, and Firefox, leaving it to the browser to handle the processing. You may love that idea, or you may not. To see what I'm talking about visit the Less.js project site lesscss.org and make sure to view source.

<link rel="stylesheet/less" type="text/css" href="less/main.less">
<script src="less.js" type="text/javascript"></script>

You'll notice a reference to `main.less` using a link tag with a `rel` attribute with the value 'stylesheet/less'. This is then processed by `less.js` on the client side generating valid CSS. That's it. That's the implementation. Pretty darn cool, no?

So if you're not comfortable with any of the server side pre-processing requirements, try using Less.js client-side to familiarize yourself with the features of these CSS pre-processors (mixing, variables, functions, etc).

My Django Advent Article

Sat, 13 Feb 2010 11:11:05 -0400

I was honored to be invited to post an article for a special series Django Advent created by Rob Hudson and Idan Gazit. The title of my article is "Everything I hate about Mingus" and in it I discuss:

"... obstacles faced and lessons learned managing an application that relies on so many reusable apps, and experiences in managing a small, open source project."

The Django Advent project is only a week old and already has a handful of terrific articles, from various authors, covering the new features in Django 1.2 which is the next stable release expected to ship in early March.

Django Advent also features one non-1.2 related article every Friday (which is how I snuck in). There are more than 10 articles left in the queue, with more being added I believe. Make sure to check it out and subscribe to the - Django Advent RSS feed.

Thanks Rob and Idan for inviting me. It was a pleasure.

Integrating mongoDB and Django

Thu, 11 Feb 2010 12:21:26 -0400

After listening to Mike Dirolf talk about mongoDB at a recent Django-NYC meetup I was left wanting to learn more about mongoDB and how I could integrate it into my Django projects.

Overview

This screencast will quickly review places to learn more about mongoDB, and a few available Python APIs for working with mongoDB, particularly mongoengine. It also discuss a project that shows us how to leverage all the great things about Django and also integrate a NOSQL database into the mix.

I stumbled onto the mongoEngine project about a month ago and have been meaning to post this screencast since then. What I like most about mongoEngine is that the classes structure looks and feels a lot like Django's models. I also really like its query API which also looks and feels a lot like Django's QuerySet API.

Finally, I take a look at a Django powered tumblog project that uses mongoDB in the backend. This particular project leverages a custom authentication backend for handling application authentication, Django forms, Django views, templates, urls, etc. Essentially it uses everything but the ORM.

This is not an extremely detailed tutorial -- my goal is to open up the discussion around a topic I'm not very unfamiliar with myself (NOSQL databases). What you see in the screencast is the result of about one hour of playing around with the various projects I discuss.

What brought it all together for me was finding a project that integrates both mongoDB and Django. I found that in Django-Mumblr, which I discuss in the screencast.

One thing I didn't mention in the screencast is the Django authentication support built into mongoEngine. I had planned to review it, but because of the length of the video I decided to leave it out. So, make sure to check that out if you're interested in integrating Django and mongoDB.

I've included the video below, but it's much better viewed full-screen or over at the blip.tv -- check it out. And special thanks to Harry Marr for both the mongoEngine and Django-Mumblr projects.

Links referenced in the screencast:

Eleven Django blog engines you should know

Wed, 10 Feb 2010 12:15:17 -0400

About two years ago Michael Trier blogged "Where's the Django Blog?". James Bennett later followed up with Where is the Django Blog Application in which he discusess why there is no "definitive" Django blog engine. More recently Daniel Greenfeld asked Show me your open source Django blog in which he defines various requirements needed for a project. Ever since reading that post I've been meaning to write this post.

Below are a few blog engines I selected that I believe you should be aware of, sorted by most recently updated. If the author provided a description I used that. If not, I summarized what I know about the project. If you have your own blog engine we should be aware of, please post the name and url in the comments.

Byteflow is not included because the project site is down at the time of this post.

Biblion

Tagline: The eldarion.com blog app intended to be suitable for site-level company and project blogs.

Source: http://github.com/eldarion/biblion

Last updated: Feb 9, 2010

Live example:http://eldarion.com/blog/

Description: Biblion was the eldarion.com blog which we've extracted and open sourced. It is currently positioned as being used for site/project blogs such as eldarion.com and pinaxproject.com. We intend for this app to replace the internal Pinax blog app once we've made it feature complete.

Notable features:

support for multiple channels (e.g. technical vs business)
use of Creole as markup format
Atom feeds
previewing of blog posts before publishing
optional ability to announce new posts on twitter

Django-article

Tagline: Sophisticated blogging engine for Django-powered sites.

Source: http://bitbucket.org/codekoala/django-articles/

Last updated: February 08, 2010

Live example:codekoala.com

Description: Author Josh VanderLinden. Sophisticated blogging engine for Django-powered sites.

Notable features:

Tags for articles, with a tag cloud template tag
Auto-completion for tags in the Django admin
Ability to post in the future
Article expiration facilities
Allows articles to be written in plain text/HTML or using Markdown, ReStructured Text, or Textile markup
Related articles
Follow-up articles
Disqus comments
Article archive, with pagination
Internationalization-ready
Detects links in articles and creates a per-article index for you
Word count
RSS feeds for the latest articles
RSS feeds for the latest articles by tag

Flother

Tagline: The Python- and Django-based code for the website running flother.com

Source: http://github.com/flother/flother

Last updated: February 01, 2010

Live example:http://www.flother.com/blog/

Description: Flother is the personal web site for Matt Riggott. It's been through many iterations but now it runs on Python 2.5 and Django 1.1 and is in active development. This is the complete source code, released under the GPL v3.0.

Notable features:

six main apps within the project
Akismet-moderated comments
Entries are formatted using Markdown and can be public, private, or draft.
Draft entries can be previewed on the site by admin users.
photos and places apps ( currently in active development and will see a full geocoded photo library with an option to import from Flickr.)
Thumbnails of images are created and displayed in the admin. A Javascript-based interface for using files in blog entries is provided
Google's AJAX API is used (server-side) to perform a site-wide search and return results on the site itself.

Basic-Blog

Tagline: Simple prebuilt applications.

Source: http://github.com/nathanborror/django-basic-apps

Last updated: February 01, 2010

Live example: http://nathanborror.com/

Description: A terrific example of a basic blog engine. The basic-apps project is a great demonstration in creating reusable apps. When taking into consideration the larger "basic-apps" project there are even more features available that integrate with the basic-blog app. Django-Mingus uses the basic-blog, basic-media, and basic-inlines apps for its core blogging engine.

Notable features: This app provides posts, categories, tags, comments, markdown support, and a basic template system.

Hello-Newman

Tagline: na.

Source: http://github.com/gregnewman/hello-newman

Last updated: January 24, 2010

Live example: http://gregnewman.org/

Description: My segregated blog platform that replaced 20seven.org under the new domain gregnewman.org.

Notable features: Since there isn't a list to pull from, here's what I pulled from a quick review of Newman's site and the code - entries, categories, "distractions", hit tracking, and a concept of "journals".

Banjo

Tagline: Banjo is a blogging application with bells and whistles, written using the Django framework.

Source: http://getbanjo.com/

Last updated: January 2010

Live example: getbanjo.com/blog/ ... I assume.

Description: Banjo is suitable for any blog, but is most appropriate for people who wish to integrate a blog into an existing Django application, such as a Satchmo store or a forum.

We have released Banjo as an open-source application with extremely liberal "BSD" licensing. So you can use it for business or personal sites with no concerns.""

Notable features:

Multiblog capable from the start.
Skinning is built in.
Trackback and Pingback are supported.
Posting via XML-RPC.

djangotechblog

Tagline: A blogging engine for django, with techies in mind.

Source: http://code.google.com/p/djangotechblog/

Last updated: Dec 21, 2009

Live example: http://www.willmcgugan.com/

Description: A versatile blogging engine aimed at coders. Author Will McGugan.

Notable features: Read Lowdown on Django-Techblog.

Django-YABA

Tagline: Yet Another Blog Application.

Source: http://github.com/f4nt/django-yaba/

Last updated: November 03, 2009

Live example: http://www.f4ntasmic.com - this is now a blogspot blog. You should read the author's post More Changes which details some updates regarding the YABA project.

Description: From the author, " I wanted something a bit more flexible though, so I decided to build it with the idea of being able to plug it anywhere with minimal configuration. I'm going to leverage YAML ( http://www.yaml.de/en/ ) for the theme of the blog, so that you can have a fairly pretty blog out of the box within minutes. Anyways, let me know if you have any questions."

Notable features:

Dynamic Themes
WYSIWG Editor
Blog Posts
RSS Feed
BlogRoll
Articles
Comments
Social Media
Search
Galleries

Shifting Bits

Tagline: A Django Based Blog.

Source: http://github.com/paltman/shiftingbits/

Last updated:November 01, 2009

Live example: http://paltman.com/

Description: Read: Shifting Bits - Another Blog Engine and Sifting Bits Makes Progress.

Notable features:

Basic blog post mode driven using generic date based views with redirects so that the WordPress url date format (numbered month versus the prettier and django default of short month name) get mapped properly so that none of your links break.
WordPress to Django Migration Script
Tagging via django-tagging
Comments via the new django.contrib.comments and using the live markdown preview editor, wmd.
Full RSS feeds (both latest feeds and by tag)

Mighty Lemon

Tagline: A Django blog. Formerly Oebfare by brosner.

Source: http://github.com/mightylemon/mightylemon

Last updated: April 20,2009

Live example: http://www.willmcgugan.com/

Description: ~~oebfare~~Mighty Lemon is the source code that runs the blog at ~~http://oebfare.com~~justinlilly.com(?). The code is freely available for you to use however you want.

Notable features:

markdown support
pygments (code highlighting)
django-comment-utils (commenting)
django-tagging (tagging)
django-mailer (mailing)
django-gravatar (gravatars for comments)
django-elsewhere (social networks)

Coltrane

Tagline: Coltrane.

Source: http://code.google.com/p/coltrane-blog/

Last updated: Oct 12, 2008

Live example: b-list.org ... I may be wrong.

Description: This is the project referenced throughout the excellent Practical Django Projects. James Bennett is the author of both the book and the blog engine.

Notable features: Since there isn't a list to pull from, here's what I pulled from a quick review of the code - posts, tagging, categories, and comments.

Conclusion

So when asking "where is the Django blog engine" today, there are a few choices available to you. Will there ever be a "defacto" Django blog engine? I don't think so. Is there room for one? I do think so, but it would take an collective effort to create it, and support it. What the team is doing with Django-CMS is the level of effort that is needed. And that's a lot of work. As the author of Mingus (make sure to check out the contributors) I enjoy hacking on it. But Mingus is and always be a concept project; a hobby.

So take a look at the above. There's a ton of terrific stuff in there. If you were looking to start a Django powered blog, now you have at least the eleven Django powered blog engines mentioned above, and Mingus :). Thanks to the authors for their contributions to open source.

That apps that power Mingus 0.9

Mon, 08 Feb 2010 11:18:33 -0400

Extending my previous post The apps that power Django-Mingus, the best way to discuss what has changed in Mingus is to discuss the new apps.

Well, wait just one second

Ok, maybe the best way to begin is to quickly discuss a few higher level updates. The first, and one I'm very proud of, is that Mingus was recently added to Transifix and now has both Spanish and French translations included thus far. To be honest, Transifix wasn't the reason these two languages were added (two developers contributed them before Transifix came into the picture), but I can see it helping in getting the rest. Getting Mingus translated probably wouldn't have been possible if:

I didn't focus on providing at least the basic pipeline for internationalization (templates, admin/models where possible)
And if Pablo Marti and Florent Messa didn't come in and clean up where I left off. Thanks to those two Mingus now has Spanish and French translations.

The fact is that so many apps (and I'm to blame here for some of my apps in the past as well) just don't do the basic i18n legwork that gets your app 80-90% of the way there. It's so easy, so go read up on Django Internationalization now before you forget. I won't produce an open source Django app without doing so ever again.

The most evasive change, believe it or not, was adding WYSIWYG support to blog posts. It was only invasive in that I sat on the fence on whether or not I thought this feature should be added to Mingus or just handled by the employing developer. I gave into the demands (those one or two people) and added support now for TinyMCE, CKEditor, YUI, Markdown, Textile, restructuredText, and raw HTML. All of this can be set dynamically via the admin (no settings.py changes!). Django-Markup was the first app I integrated to help with this feature, and then added Django-WYSIWYG, and then Django-TinyMCE borrowing some ideas from skevy. The funnies part about it all, Github now graphs my project as 98% javascript because of simply adding WYSIWYG support. The rest is 1% Python and 1% PHP (wtf?). Anyway...

Probably the best thing to come out of Mingus 0.9 is the community that helped get it there. Developers (handles) like acdha, richleland, hotsyk, danfairs, mikl, scelis, pmarti and thoas, as well as skevy, and jefftriplett, and the others helped make Mingus a better product by forking it on their own, adding features, forking a reusable app it uses and updating those, etc. Speaking of those other reusable apps, of course we can't forget to thank all the authors of those reusable apps as well. And finally, github made following commits, forks, branches, and merging updates a cake.

Other than that there were a slew of changes, but nothing too horrible if you're looking to upgrade on your own. A few apps we'll discuss soon have been added, the location/handling of static media in the project has been updated -- I discuss that below when reviewing Django-StaticFile. I've begun maintaing a docs/CHANGELOG file for these types of details, something I should have done since day one -- lesson learned. You can always reference the project's git commit log for the finer details. For anyone looking to migrate from an already existing, older version of Mingus there are three key changes to note:

Two new columns have been added to basic.blog.models.Settings and Mingus provides postgres SQL migrations for these (no South yet, sorry)
Permalinks have been updated to be more international friendly (previously the month was a character sequence and now is a digit sequence). The detail view has logic to support legacy urls with raising a 404 but your Disqus comments won't be smart enough to know the difference between the new and the old URL (disqus uses the URL as a key look for your comments). So if your comments disappear on you then you know why. A solution to fix this is to write a Disqus migration, or fork the basic-apps code Mingus uses and revert back to the older pattern, or update the templates where they populate the url, or do like I did and add a "My url scheme changed, if you'd like to see older comments click here" type solution. Not pretty, but works for me. So you have a few options available to you.
Static media directory move mentioned above, but you may have customized that anyway.

For those coders out there looking to syntax highlight your code well Django-Markup pygmentizes your text by default (not knowing that though I had previously added a pygmentize filter to the templates but that has been removed to reduce redundancy). If you're using the Django-Markup editors (markdown or reStructuredTex) this should work for you.

I also added Google Code's prettify highlighter as an alternative. To enjoy the benefits of google-code highlighting your markup needs to specify a class="prettyprint" attribute. It uses the Google CDN to deliver the JS so if you don't have access to the internets you won't see any highlighting. The related CSS is included in Mingus if you'd like to customize it to you compliment your templates.

To help better understand Mingus, and the references above, I plan on screencasting/posting these tidbits asmy schedule provides. The rest of the updates were mostly harmless refactoring of code, template updates, some i18n love, regular maintenance, bug support, and what have you. So let's see what goodies we have now...

The new digs

Without further ado, here are Mingus 0.9 additions (and one removal):

Django-StaticFiles

Source: Django-StaticFiles

Description: A Django app that provides helpers for serving static files, used in Pinax.

Notes: How to handle serving static media in your project is always a good way to fire up a discussion. Managing them in a Django reusable app even more so. This project exists to resolve all those headaches. Jannis Leidel created this project in reflex to these static media management woes the Pinax team dealt with. It's one of those projects I believe should be considered for a contrib app as it resolves a common issue every Django project will most likely run into.

Django-DbTemplates

Source: Django-DbTemplates

Description: Django template loader for database stored templates with extensible cache backend.

Notes: Yet another project created by Jannis Leidel. The name is self-explanatory -- DbTemplates allows you to create templates in your database instead of the the file system, which allows editing via the Django admin. DbTemplates also allows you to override existing templates on the file-system by creating a new Template record. The benefit here is that you can allow edit access to those users who should not have access to the server. The negative is that source control is lost. Leveraging Django-Reversion is the suggestion solution to solve that versioning issue. I guess you'll see that in Mingus 1.0 :)

Currently Mingus does not have this enabled in the TEMPLATE_LOADERS settings, but the application is installed with Mingus by default. I'll most likely change this in HEAD so it's enabled by default. To enable this yourself all you need to do is specify the TEMPLATE_LOADER. Below is an example:

TEMPLATE_LOADERS = (
    'django.template.loaders.filesystem.load_template_source',
    'django.template.loaders.app_directories.load_template_source',
    'dbtemplates.loader.load_template_source',
)

Django-Slimmer

Source: Django-Slimmer

Description: Html compression as middleware and view decorators.

Notes: Middleware that slims down your HTTPResponse by removing extra white-space. This module is a django conversion of CheckoutableTemplates Zope package. Related, David Cramer published a post Spaceless HTML in Django which details his solution using Django Middleware for a similar perforance enhancement. You'll note that in the comments some readers noted alternative solutions as well. So far Django-Slimmer hasn't introduced anything but great results.

Django-Cropper

Source: Django-Cropper

Description: Integration of jCrop with the Django admin.

Notes: Simon Willison initially released this nice little reusable to make image cropping in the admin easy. It's a terrific tool that allows you to easily crop images in the admin using JQuery and JQuery-Crop. I tried to integrate it with the Mingus project, and it worked well, but there were two issue I ran into so I forked it. First, Willison raised the issue I mentioned above regarding what to do with your static files when releasing a reusable app, "... no idea what I should do with the static file dependencies though.". The second was the location of the ImageField "uploads" parameter which I like to set, if possible, in my project's media/uploads/[projectname] directory. I forked the repo to include these changes. Willison noted that this project was not a complete project and it's even highlighted here. Maybe Chris Adams post Django: reliably saving URLs to a file field provides the answer?

Django-Request

Project site: Django-Request

Description: A statistics module for django. It stores requests in a database for admins to see, it can also be used to get statistics on who is online etc.

Notes: Created by Kyle Fuller, Django-Request is the one app I'm most concerned about including is also one of the kewlest. Django-request provides analytics on (you guessed it) any http request your application handles. It provides a lot of customization (I setup a few ignore rules that live in local_settings.py), and integrates Flot graphical plots. The "overview" view looks really amazing and is a great example on how you can customize the Django admin to fit your needs. The reason I'm concerned about using Django-Request is that it's database write intense, plus the overview page executes analytics on all your request records which unless kept tidy could become very expensive. But for a blog like mine, I'm not concerned just yet. To remove it all you need to do is comment out the middleware reference. It also provides a few management commands to dump old records. So, it's nice like that.

Update: Mingus and Django-Request have had a love/hate relationship. I'm mostly kidding here, but there have a been a few bumps in the road, all of which I've submitted patches (via my own fork) for or logged issues. Kyle has been terrific about getting the fixes in. If you're detailed you'll note that as of 0.9.5 I removed django-request from Mingus altogether. Then when 0.9.6 was announced we found another bug. So you'll see the updated migration SQL in the 0.9.7 tag. Anyway, it's a really interesting app that shows off some of the many cool things you can do with Django itself (management commands, admin customization, etc). So it's back in Mingus for your enjoyment. This is what happens though when you're running beta software -- It's part of the game. Thanks Kyle for your work, and thanks for those users who helped track down the bugs.

Django-Memcache-Status

Source: Django-Memcache-Status

Description: Django admin extension that displays statistics about your memcached instances.

Notes: Martin Mahner is the author of this project. He provides a perfect, concise README file that details exactly what this project provides, so go check that out since it has nice screenshots and all that jazz.

Django-Bitly

Source:

Description: A Django app that manages bit.ly links to local objects.

Notes: This is the app used by django-twitter (below) to create bit.ly short urls when posting to twitter (Mingus allows you to fire off a twitter message when publishing a new blog post). The project provides additional features as well, so make sure to check it out. The Discovery Creative team is the author.

Django-WYSIWYG

Source: Django-WYSIWYG

Description: A Django application for making Django textareas rich text editors. Certainly as a template tag and possibly as a form widget.

Notes: Daniel Greenfield is the author of this project. Because I'm a masochist I wanted to not only support Textile, Markdown, reStructureText, raw HTML, and TinyMCE so I added Django-WYSIWYG. By default the app renders the YUI WYSIWYG editor editor via the yahoo CDN. I've added the configuration settings to settings.py so it defaults CKEditor. If you'd like for it to render the YUI WYSIWYG editor then just remove the DJANGO_WYSIWYG settings from settings.py.

Django-TinyMCE

Source: Django-TinyMCE

Notes: The first request I received for a WYSIWYG editor was for TinyMCE. It's a very successful project, and has numerous extensions and customization features. Some people just love their TinyMCE so it was hard to ignore it even knowing that it's younger, sexier competitor (CKEditor) was already included with Django-WYSIWYG. Mingus provides the basic implementation only, and that's all it will ever support. There appears to be multiple authors, so thanks to all of them.

Django-Twitter

Source: Django-Twitter

Description: Twitter Django Integration.

Notes: Adam Miskiewicz is the author of this little utility app. I'm pretty sure he created it for a Mingus blog that has not yet launched. I'm itchin to see it though when it does. The application itself provides a model for adding your twitter auth via the Django admin and a signal for creating the bit.ly url for your object, and then the posting to twitter as well. Django-Twitter is tightly coupled to django-bitly and if you haven't set the required bit.ly settings values in your settings.py file then publishing tweets post publishing won't work. Also, now that I think of it (and I just checked this out to confirm) it will post a tweet regardless of whether your post is set to Public or not. So yea, there's that as well :/

As I'm writing this I can't allow myself to complete this post without fixing the above issue so I've gone and created 0.9.2 tag for a fix, which includes a new signal in basic.blog to handle the posting, and it also decouples the need for bit.ly configuration. If you don't set your bit.ly credentials in settings.py it will then revert to using Site.domain + get_absolute_url() of the instance itself. At this point I'm considering refactoring django-twitter out of the mix in a later Mingus version as it now feels more like a basic-twitter app could handle this and is better suited as an addition to basic apps. That being said, Adam did a great job getting the initial legwork done. Thanks adam.

Python-Twitter

Source: Python-Twitter

Description: A python wrapper around the Twitter API.

Notes: Used by django-twitter to post the tweets, of course. There appears to be multiple authors, so thanks to all of them.

South

Source: South

Description: Intelligent schema migrations for Django apps.

Notes: I removed South as a requirement, not added it. None of the apps used in Mingus use South as their default migration tool, if they provide any migrations at all. It's sad actually. It should be the defacto Django migration solution. Does anyone disagree?

What's next?

Well, before we can talk about 1.0 we need to discuss the near future, which includes supporting bug fixes and producing screencast tutorials. For now, those are the things I'm going to focus on. I'm thinking a "5 Days of Mingus" series, or something like that. For the near future, that's my goal. What is not next is adding anymore text editors to the project :)

What's up for 1.0?

mobile theme
docs site (more docs) reST/sphinx
more test/test runner
theme support (switching via admin)
template update/clean up css
project site
pylint/code quality
fabric/deploy helper
1.2 support
A select few app additions that make sense (Django-Reversion, Django-DataTrans maybe, etc.)

How can you contribute?

Just keep forking baby... just keep forking. It's as simple as that. Fork, feature branch, test, merge, pull request. Repeat.

When will this all happen?

There will be no rush on pushing out a 1.0 release. Heck, if 1.0 were released by DjangoCon 2010 I'd be happy. I'm not ditching Mingus (it's the blog engine I use for my own personal site so I'm eating my own dog food), but as of recent my evenings and weekend schedule got plenty busy (new baby and home). It will be a "get to it when I can (or if others do)" type thing.

If you follow this project already you know I try very hard to resolve any issue that are filed as quickly as possible given my schedule. And I'll work with the rest of the contributors (who continue to develop on it) to progress the project as best as possible. Take a look at Mingus Network if you'd like to see who else is actively hacking on Mingus; there's some great stuff going on there.

With Mingus already being as feature rich as it probably will ever need to be, despite the few todo items listed above, the 1.0 release will be focused on stabilization, and proper project packaging.

Sites using Mingus today

One of the most motivating aspects of Mingus is seeing Mingus powered blogs go live in the wild. Below is a list of the blogs I'm aware of that are currently running Mingus (in no order). I'm sure I've missed a few. If so please comment with the URL of your Mingus powered blog:

Note: Additions to my original list:

Thanks to everyone who has launched a Mingus blog on their own. I hope it's been an enjoyable experience.

Thanks again

Finally, thanks to all those people who submitted issues, suggested ideas, committed code, evolved their own fork, etc. Your contributions in whatever form are greatly appreciated. I've added as many people as I could to the AUTHORS file that is packaged with Mingus. If you feel you were missed, just ping me and I'll make sure to add you. In the bigger picture of things I realize Mingus is an itsy, bitsy, tiny blip on the map but it's a fun project and I'm very happy to have passionate contributors and users of the project -- Django makes it easy doesn't it? Thanks again!

Mingus 0.9 Released

Sun, 07 Feb 2010 13:43:20 -0400

Update: Well, there's no QA like opening something up to the wild. Thanks to reader feedback we've tracked down a bug in one of the new reusable apps that Mingus employs. I've contacted the author and I assume a 0.9.7 release will be out shortly. For now, feel free to play around with 0.9.6(HEAD).

Update 2: I've bumped Mingus up to 0.9.7 tag which resolves the related issue. So both 0.9.7 and HEAD are "stable". Details to come in tomorrow's roundup post.

As I noted above, I'll have a more detailed post coming shortly, but the Django-Mingus 0.9 release is now available on Github. There have been some fixes since 0.9 was tagged, so ~~version 0.9.6~~ 0.9.7 is the current stable release. Please submit any issues you find to the Mingus issues section.

If you can't wait for the forthcoming blog post that will detail the updates, there's the new CHANGELOG and of course there's always the git log you can peruse for all the finer details. Enjoy!

Hello Claire

Sat, 09 Jan 2010 21:54:45 -0400

Note: I migrating to a new URL scheme, so legacy comments are available here.

Introducing Claire Paige Fricovsky, 11/30/09.

South and Reusable Apps

Wed, 21 Oct 2009 22:02:31 -0400

Note: I migrating to a new URL scheme, so legacy comments are available here.

I was honored to be invited to participate in a recent DjangoDose panel covering Reusable Apps in Django which featured Brian Rosner, Eric Florenzano, Alex Gaynor, James Bennett, James Tauber and Jannis Leidel. After listening to the episode I realized I offered up a "brain fart" when responding to @TheSeanOC's question "How should schema migrations be handled in reusable apps?".

Let's review the brain fart

I jumped in to answer the question quickly but my answer to this question was essentially "use South." Wow, great. Very enlightening. But I forgot to elaborate on the concept I've had in my head for a long time but have yet documented. As the callcast discussion related to this question continued the panel ended up agreeing that the best solution was making the use of South a convention. But in hindsight I wanted to offer something more. I had what I believe is an answer, or at least a suggestion for a solution. Remember in "A Christmas Story" when Ralphie went to the mall to ask Santa for his Christmas present wish? (No? Watch it.). He froze up when he was on Santa's lap and asked for a football. After he was removed from Santa's lap, and pushed down the slide, he quickly realized that's not what he wanted at all. He wanted an official Red Rider BB Gun. This is my Red Rider BB gun request.

South and reusable apps

First, South is an amazing migration solution for Django. I can't imagine developing without it. I include it in Django-Mingus only because I want to use South but Mingus itself, as a "project", defines no models and therefor South doesn't care about it :( Working on Mingus and the 28+ apps it includes I came to wanting this feature some time ago. So here's the gist of it all...

Mingus uses a collection of reusable Django apps to build a blog engine. I noted this in my DjangoCon 09 how-to, but this concept isn't new. In fact, in researching my DjangoCon presentation I came across a James Bennett post where he answers "Where is the Django blog application" and he suggested exactly what Mingus set out to do - leverage the awesome reusable apps feature to piece together a blog engine. That was psted 2 years ago! I thought only @gregnewman could see in into the future. Anyway, I'd love to offer migrations along with Mingus but sadly we're not there yet.

Today if you were to run a local version of Django-Mingus and test the app locally using runserver after you followed the quickstart documentation you would notice some of the Django reusable apps required in the pip requirements.txt file included with Mingus found a home in the [Root]/src directory, while others found their home in /lib/python2.5/site-packges (that's all related to how they were packaged and referenced in the requirements file). Anyway, here's a screenshot below.

Default Django-Mingus project directoy structure.

In the above screenshot the directory django-mingus is my git repository root, not the above. Now what I want is the ability to easily include migrations from my initial project start, and ongoing into the future (@gregnewman knows all about the future.) so I can evolve my project along with these reusable apps code base. So what I would like to do here is (you need to have some familiarity with South to recognize these commands) the below pseudo code:

 
./manage.py startmigration django-mingus

South would then create a migrations directory in my project's root (or wherever I specify it via a settings variable) and then iterate through all the apps in INSTALLED_APPS and create directories for each reusable app and initial migration scripts. Then moving forward any time I update the reusable apps, I could easily create migrations, evolve my project database, and have it safely encapsulated in my project's repository. Right now this is not possible. This is what would happen now if I tried to create an initial migration for django-flatblocks.

 
./manage.py startmigration flatblocks --initial

The below is the resulting directory structure.

Djang-flatblocks initial migration.

You'll see the migration directory was created in the root directory for the django-flatblocks project which in the Django-Mingus project is located here /testproj/src/django-flatblocks/flatblocks/migrations. My issue with this is it's not encapsulated in my project root, which means it's outside my repository (therefor no version control) and depending on how the developer is installing the project, the migration script could end up anywhere on the filesystem he/she feels best fit to install the related reusable apps for the Mingus project. The last point is a bit weak, because we're using virtualenv and pip which helps us out in that regard. But I do see the need for South migrations related to reusable apps being included in the projects root versus off the applications root, and I think this may be the solution.

Updated: I should have initially added a visual to detail what I'm suggesting. It's now below.

Alternative project view with South included reusable app migrations on the project level.

Conclusion

Whether this is the best idea or not I'm not 100% sure. But I've been meaning to throw it out there for quite some time. So it's my Redrider BB-Gun, or my South pony. Whatever you want to call it. I'd love to hear your thoughts or how you handle this in your own projects - leave a comment below. Thanks.

Screencast - Basic-Inlines and AdminImageWidget

Thu, 01 Oct 2009 22:21:40 -0400

Note: I migrating to a new URL scheme, so legacy comments are available here.

Below is quick screencast, thanks to screenr, I published in response to some questions I received about how/why Mingus uses Nathan Borror's excellent basic-inlines application which integrates nicely with basic-blog. I also took the opportunity to show off AdminImageWidget which was contributed by Peter Baumgartner over on djangosnippets.org.