Another long time in the making, Sammy 0.7 is here and its sexy. Check out the HISTORY and the full Changes to get the full details. The Boy of “Boy meets Girl” is Sammy, and the Girl is HTML5.

Download it!

It’s probably seemed like Sammy development had stopped a while ago. With all the other similar frameworks bouncing around these days, I’ll admit there were some dark days of doubt leading up to this release. In fact, most of the code that comprises Sammy 0.7 has been in the master branch for over 4 months. However, development and my belief in this project hasn’t wained, its more just that I’ve been completely consumed by my work at Paperless Post (and in a very good way). One of the benefits of leading the team there has been the ability to push the boundaries of what we can do with our code and our libraries. We use Sammy extensively at PP and I was super excited to have a use case and a way to develop and test this latest version and all its power. The big addition of HTML5 History support has made the big new app we’ve been working on for the past 6 months seamlessly deep-link between full urls and hash urls between multiple browsers. We’re pretty psyched about it.

History is History

Despite which side you fell in on in the Great hashchange debacle of '11 you can’t argue with the pure fact that regular URI paths are just better than hash (#) paths. The makers of the great browsers of the world and the HTML5 History spec have a solution that attempts to appeal to everyone. The premise is simple – create a JS API for manipulating the full path of the current browsers location without forcing a page reload. Meaning, you can tell the url to change from http://www.example.org/one to http://www.example.org/two without having to reload the window, and allowing you to then manipulate the state of the page. Seems sort of like a dream, doesn’t it? Not only that but it really is a perfect fit for the way Sammy manages state and how Sammy applications are already built around routes and paths. I knew this was the case the first time I saw it, but I was unsure how to mix it with the existing hash based routing that works (and would have to persist) across every browser, not just the latest and greatest.

I believe Sammy 0.7 presents a pretty solid solution. Now, instead of routing on paths that look like #/mypath you just route on paths that look like a server side path /mypath

var Sammy('#container', function() {

  this.use('Mustache');



  this.get('/', function() {

    this.partial('templates/index.mustache'); 

  });



  this.get('/:user', function() {

    this.load('users/'  this.params.user  '.json')

        .partial('user.mustache');

  });



});

The beauty and magic of above is a those routes will match both quirkey.com/#!/aq and quirkey.com/aq and execute the user route as expected. I’ve created a simple working example for you to play with at http://pushstate.quirkey.com/ (source here). We’ve been using and testing this for the past months and I can say its pretty solid (and pretty awesome).

There are some known caveats:

• History only works in latest and greatest browsers (Chrome, FF5, Safari 4) but support for it is growing. Ben Cherry and the team at twitter also found some issues with certain versions of webkit and URLs getting out of sync (though its been resolved
• Your server side needs to be able to handle whatever urls you’re changing to. This means that if you route/redirect to something like /path/one/two in Sammy, the server better be able to handle that url as well and point you in the right direction. Otherwise, refreshing the browser will lead users to a 404 or worse. The sammy-pushstate example has a pretty clever way of dealing with this in couchapps. It uses CouchDB rewrite rules to route any url request (minus the key files) to the index.html page (and hence allows sammy to handle the routing).
• Currently, mobile webkit (aka Mobile Safari and the Android browser) report support for pushState/History when in fact they don’t have it. Since I’ve tried to keep browser sniffing out of the core Sammy repo, it currently doesn’t detect for this. You can manually disable push state per application, though, and do the browser sniff yourself if you plan to use your app on mobile.
• This causes some possible breaking changes for upgrading Sammy apps. If you previously did any routing (or path checking) the path reported in a route (EventContext.prototype.path) is now the full path starting at / not just the path beyond the hash. Also HashLocationProxy was renamed to DefaultLocationProxy.

That being said, its a pretty awesome feature and it makes writing Sammy apps really powerful when exposed to the full path. Theres more information in the API docs here.

Templating engines are so 2010

One thing thats frustrated a number of Sammy users is that previously all the template plugins (aka Sammy.Mustache, Sammy.Handlebars, etc) included the source for the engine in the plugin. In the beginning, I thought this was a great idea because it reduced the number of potential headaches and complaints of ‘Mustache isn’t working (because I didn’t include the source)’. However, what turned out to be a bigger issue was keeping up with all the plugins and their individual rapid development cycles. Because of this, all templating plugins (with the exception of Sammy.Template and Sammy.Meld) are now just simple wrappers and expect you to include the respective templating library in your own source. This also makes the case of using Mustache outside of Sammy in the same source/app as a Sammy.Mustache application a lot easier. For the sake of making the transition easier, the latest version of all of the engines is included in the repo (in vendor/templating).

More!

Those are certainly the biggest things with this release but its also not the whole deal. There were 12 other changes, bug fixes, and new plugins written by 10 different contributors! I can’t thank the people who use and contribute patches and ideas back to Sammy, enough. You guys rock.

Sammy.js is finally official because now we have a real dedicated website: http://sammyjs.org. It only took two years.

Along with the website the logo I designed before JSConf.eu last year now has an official place to proudly be displayed. Since we’re a REAL project now, we’re also starting up the SWAG train, so logo stickers are on their way.

The biggest change with the new site is the API documentation has been significantly cleaned up. The text is still being generated from the code itself, but now we have easier navigation, the ability to keep multiple versions of the docs (generated per release) and probably the most fun – method level comments powered by Sammy users and contributors, DISQUS. I’ve made good use of the method level comments featured in sites like apidock so I’m very excited to see if the community participates here.

Sammy.js is growing up and its been so much fun to see how and where people use it. I don’t see that many big changes in the future for it before we push a real 1.0 (See a brief roadmap on the mailing list) and a big goal is to get push the big one oh before this year’s JSConf in Portland.

A question came up on the mailing list recently about overriding previously defined routes after struggling thinking of how to do this with the current codebase, the answer was simple: Use helpers!

Coming from Sinatra or Rails the idea of helpers might be associated with just “view helpers” – methods added to the controller which are passed down to the view to help refactor/encapsulate common view logic. In Sammy.js helpers are really a way of refactoring common logic out of routes and into a reusable named method.

Refactorin’

In any app you’ll have startup code or code that needs to be run for every or multiple pages (routes). In Sammy this might looks like:

$.sammy(function() {

  

  this.get('#/', function() {

    if (this.params.grid) {

      this.$element().addClass('grid');

    } else {

      this.$element().removeClass('grid');

    }

    this.partial('index.html');

  });

  

  this.get('#/user', function() {

    if (this.params.grid) {

      this.$element().addClass('grid');

    } else {

      this.$element().removeClass('grid');

    }

    this.partial('user.html');

  });

  

})

A contrived example, but you can tell we’re doing almost the exactly same thing in each of the routes. A common JS convention and something you could do pretty easily here, would just be to extract the functionality out into a closure/function and call it for each route.

$.sammy(function() {

  

  var displayGrid = function($element, display) {

    if (display) {

      $element.addClass('grid');

    } else {

      $element.removeClass('grid');

    }

  };

  

  this.get('#/', function() {

    displayGrid(this.$element(), this.params.grid);

    this.partial('index.html');

  });

  

  this.get('#/user', function() {

    displayGrid(this.$element(), this.params.grid);

    this.partial('user.html');

  });

  

})

This works, it prevents global leakage by declaring it inside the app, and it gets rid of a number of lines of repetitive code. However, we’re still passing a bunch of route attributes into the closure. This is where helpers can shine.

$.sammy(function() {

  

  this.helpers({

    displayGrid: function() {

      if (this.params.grid) {

        this.$element().addClass('grid');

      } else {

        this.$element().removeClass('grid');

      }

  });

  

  this.get('#/', function() {

    this.displayGrid();

    this.partial('index.html');

  });

  

  this.get('#/user', function() {

    this.displayGrid();

    this.partial('user.html');

  });

  

});

This looks a lot cleaner to me. You might not love this but it makes some things really magical. By making displayGrid a helper it automagically has access to the context of the current route. That means that just like the route’s callback, it has access to everything in the EventContext including params, redirect, render and other helpers. This is important, because it basically allows you to extract common code from routes into helpers and then refactor those helpers even further into other helpers.

stOOPid inheritance and mixins

Helpers are actually just methods on the app’s EventContext prototype, and event though there’s no classical inheritance with super’s and all that jazz we can do some fun OOP-like magic.

In the example from the mailing list, we wanted to override an application’s existing route with a new route. Though the way routes are stored and handled makes it difficult on the app level, doing it on the helper level is EZ:

// initializing a new app

var app = $.sammy(function() {

  

  this.helpers({

    // define a helper to load the index as the default behavior

    loadIndex: function() {

      this.partial('index.html');

    }

  });

  

  this.get('#/', function() {

    this.loadIndex();

  });

});



// override the specific helper, and hence the index route

// we can also do this by calling `helpers()`

app.helper('loadIndex', function() {

  this.partial('specialindex.html');

});

use() is how Sammy includes a plugin in an app. A plugin is really just another app function, though, that get’s evaluated at the time you use() it. In fact, when you call $.sammy() you’re just creating a new instance of Sammy.Application and then calling use() on it with the app function. This is a simple way of doing “mixin” style inheritance. A plugin can do anything an app can, including and especially helpers. So with multiple apps we be all like tag team: OOP there it is

$.sammy('#hiphop', function() {

  this.helpers({

    playCatchPhrase: $.noop

    // noop there it is 

    // this is sort of like an abstract method

  });

  

  this.get('#/catchphrase', function() {

    this.playCatchPhrase();

  })

});



var atlanta = function() {

  this.helper('playCatchPhrase', function() {

    alert('whoomp there it is!');

  });

};



var la = function() {

  this.helper('playCatchPhrase', function() {

    alert('do the hump!');

  });

};



$.sammy('#hiphop').use(la);

// get '#/catchphrase' //=> 'do the hump!'

Thats still pretty simple, though combining these ideas is actually pretty powerful. Almost all of Sammy’s existing plugins are based on this simple approach. I’m hoping soon, it can get even more abstract and complex. Why not a Sammy.Auth that handles displaying/posting/and doing all the basic authentication? You could use helpers for most of the dirty work and then one could just override the defaults in their specific apps. You could even create another set of plugins that were different displays or authentication systems that override the simple base methods. Do it! ( so I dont have to )

I’ve been thinking about part III and beyond as well, but thats for another day. I hope at least this fixes a lot of the confusion for people delving into Sammy for the first time.

Check out the new tutorials here.

It’s a couple months in the making, but I’m happy to say that Sammy.js 0.6 is finally here. Check out the HISTORY and the Changes. I’m calling this release the California Suite in honor of my move to the West Coast and the fact that I did most of this coding on the plane back and forth. There are some awesome big new features that I’ve been using for a little while now and I can say are a big improvement over previous releases.

Download it!

Before I get to that, I want to mention that work is in full swing on a new Sammy.js website with more documentation and other great stuff. I even have a real logo which I hope to share soon (stickers, anyone?). Before the site launches, though, I set up a new GitHub wiki so that sammy.js users and developers can share projects and code that they’ve been working on.

On to the features!

Context! Context! Context!

The biggest complaint and frustration that I heard from people working with Sammy was about dealing with rendering complex views on the client. If you’re doing full client side applications or any amount of client side templating you’ve felt the pain of deeply nested callbacks and complex workarounds for interpolating data in an asynchronous environment. It’s all like, render this template, wait, first I need the data, hold up, I cant even render that yet I need to get this other template first. Here’s a common example of what I’m talking about:

this.get('#/', function() {

  this.partial('index.mustache', function(html) {

    $('#main').html(html);

    $.getJSON('items.json', function(items) {

      this.partial('item.mustache', items, function(item, i) {

        $('#main ul').append(item);

      });

    });

  ));

});

It’s not just nested callback’s that are the pain – its the knowing (or not knowing) when a template will be there or not. It’s also trying to deal with fetching data and fetching templates within the same context without a unified API. After kind of examining how other people are doing this, I took some queues from jQuery’s API as well as ‘promise’ style programming and Sexy.js. The result is Sammy.RenderContext. You create a RenderContext by calling one of three methods within a route/EventContext – load() render() or partial(). Once you have a every method you chain to it is guaranteed to execute in the order that you chain it regardless of it synchronicity. This means that you can put an appendTo() after a load() and the content won’t be appended until its fetched asynchronously from a remote location. The content from the previous method in the chain is also passed along so you don’t have to constantly pull out references. The code above, translated to the new way looks like:

this.get('#/', function() {

  this.render('index.mustache')

      .replace('#main')

      .render('items.json')

      .renderEach('item.mustache')

      .appendTo('#main ul');

});

A wee bit nicer. Not only does it improve readability but it makes it much easier to do longer more involved client side templating without getting lost in a mire of order and context passing. RenderContext’s can also be invoked side by side in a single route for parallel execution of chains. Each chain is its own object and keeps its own state. I tried to keep the API concise but with just a few methods, I think most situations are covered:

then(function(content, previous) {})

next(content);

wait();

// Loading local or remote content

load('item.template')

load($('.item'))

// rendering templates

interpolate('item.template', {})

interpolate($('.item'), {})

render('item.template', {})

partial('item.template', {})

collect(items, function(item, i) {})

renderEach('item.template', items)

// DOM Manipulation

swap()

appendTo($(element))

prependTo($(element))

replace($(element))

// Events

trigger('name', {})

Along with the readability improvements, the RenderContext (specifically load()) allows for DOM style or pre-embedded templating. Meaning, templates don’t have to come from files, they can be DOM elements and embedded into <script> or hidden tags. This goes along with the two new templating engines added as well . . .

Alchemy

I thought I had this really novel idea. Why not use classes or other attributes of DOM elements to define how they’re tied to a JSON object? I worked on some prototypes and finally found a name and wrote some real code. It turns out, it was a pretty good idea, but also one that had been done before. 0.6 includes plugins for my own Sammy.Meld and the existing and by default more popular pure.js.

The basic idea of both of these engines is that you take some data like this:

{

  "post": {

    "title": "My Post",

    "body": "Lorem ipsum dolor sit amet.",

    "tags": ["one", "two", "three"],

    "meta": {

      "comments": 5,

      "time": "Yesterday"

    }

  }

}

And some HTML like this:

<div class="post">

  <h2 class="title"></h2>

  <div class="body"></div>

  <span class="tags"></span>

  <ul class="meta">

    <li>Comments Count: <span class="comments"></span></li>

    <li>Posted: <span class="time"></span></li>

  </ul>

</div>

Meld them together and you should get something like:

<div class="post">

  <h2 class="title">My Post</h2>

  <div class="body">Lorem ipsum dolor sit amet.</div>

  <span class="tags">one</span>

  <span class="tags">two</span>

  <span class="tags">three</span>

  <ul class="meta">

    <li>Comments Count: <span class="comments">5</span></li>

    <li>Posted: <span class="time">Yesterday</span></li>

  </ul>

</div>

There are some clear benefits to this over traditional tag style (mustache, ejs) style templating. Namely, its just HTML. This means that you can include it in the DOM on the initial render and not have to go fetch it from the server. It also means that a designer can just design it and even use lorem ipsum if you want, and you don’t have to go through and add the templating language. There are some downsides, too. DOM manipulation even with jQuery’s speed is pretty much always going to be slower then just text interpolation. I’m working on improving the speed of Meld though caching and faster manipulations, but it ain’t easy. The other big downside is that complicated iteration or template logic is pretty hard to do in this style. Pure tries to get around this by using a third element called directives which are further instructions on how to meld the data and the markup. I forgo this extra ability to configure in Meld in favor of very simple transformations (ul,ol = lists) and a much smaller file size (uncompressed meld is only 4K). I’ve been using Meld on some personal projects and hope to test its worth in a real production environment very soon. You can see more examples of it’s power in the tests

What’s next?

I’m still pushing to get Sammy.js to 1.0 in the very near future. I really don’t think theres that much between here and there. I’ll mention that I’ve finally been seriously coding with node and server side js and I’m not that happy with the current state of routing libs there. Server side sammy? Maybe.

More

There were a lot of smaller bug fixes and improvements beyond Meld and the RenderContext so I definitely encourage checking out the full list and making the upgrade soon. Big thanks as always to everyone who helped with the release. Go out and make some apps!

More interesting, I was interviewed by The Changelog Show. Wynn and Adam are awesome hosts, and we talked about a lot of fun things including a good deal about Sammy and JSConf. Since I didnt really get to talk too much about Sammy at JSConf, it was a great way to share my current thoughts and some stories of the origins of Sammy.js. This also lead into a nice mention on The Dev Show yesterday.

I haven’t mentioned it here either, but I’ve also been making some major upgrades to my Sammy presentation app, Swinger. I added slide sorting, incremental lists, and a ton more. This also includes having a fully useable hosted version for people to play with at http://swinger.quirkey.com/

I’m very excited about where Sammy is going and even more excited as I’m using it almost every day and getting to contribute back to the project and think about the stumbling blocks as I use it.

I already have a basic plan laid out for the next release which is mainly focused on re-writing the partial() and template handling to make chaining multiple templates much much easier. You can follow the work I’m doing on it on github. The current status is that it works and passes the basic tests, but theres still a bit to go in terms of API and usability. I’m going to write a more detailed post about it very soon.

I’m pleased to announce the next major release of Sammy.js, 0.5.0. I’ll go over what I think are the most import changes, but you can check out the HISTORY or just cut to the chase and download it.

jQuery 1.4.1

One of the big events I was waiting for in order to release this new version was the release of jQuery 1.4.1. Besides being a good leap and jump faster then previous versions, the latest jQuery added support for cross-browser bubbling of the submit event. This might not sound like a big deal, but Sammy handles post/put/delete routes by binding to forms and their submit events. In previous versions of Sammy, if a form was dynamically added to the page (i.e. by a partial or get route), you (or the app) would fire a changed event, which would tell the app to search for all newly added forms and bind to their submit events. Using the power of jQuery 1.4.1, Sammy can now just listen for submit events that will bubble up to the applications element and from their dispatch the route. In general this is a lot cleaner and will make it easier for beginners as it just works.

Chain of fools

From user requests, and to fulfill my own desires, I’ve tried make Sammy more adaptable to different styles of coding/app creation. The first thing I realized why not make Sammy app definitions chain-able? It’s a style of development that jQuery developers are already used to, and it looks pretty swanky, too. With 0.5, all the app modifying methods are now chain-able:

  



// classic style:

$.sammy(function() {

  this.use(Sammy.Mustache);

  this.use(Sammy.Session);

  

  this.before(function() {

    // …

  });

  

  this.get('#/', function() {

    // …

  });

  

  this.bind('run', function() {

    // …

  });

  

})



// New chain style:

$.sammy()

  .use(Sammy.Mustache)

  .use(Sammy.Session)

  .before(function() { 

    // .

  })

  .get('#/', function() {

    // …

  })

  .bind('run', function() {

    // …

  });

    

Sammy()

Once just a namespace, Sammy() is now a function (and its aliased to $.sammy). The Sammy() method provides access to the new Sammy.apps object and hence allows you to access the different Sammy applications you’ve added to the page without having to define additional global vars. Finding and extending is all based on @element_selector@s so those should be unique per-application. It also provides a quicker syntax for defining an app bound to an element_selector.

// Old way

// we're forced to make app a global so we can access it 

// outside of this closure

app = $.sammy(function() {

  this.element_selector = '#myapp';

  //…

})

// equivalent to

app = new Sammy.Application(function() {

  this.element_selector = '#myapp';

  //…

});



// NEW WAY

$.sammy('#myapp', function() {

  //…

});

// equivalent to Sammy('#myapp', function() {})



// No need to assign it, the app can be looked up by element selector

$.sammy('#myapp') //=> Sammy.Application

There are some cool use-cases for this, including being able to iterate over all the Sammy apps in play and extend them.

any way you want it

Sammy 0.5 adds the new any pseudo-verb which allows you to easily add a route that will match against any verb:

  

$.sammy(function() {

  

  this.any('#/', function() {

    this.log("I'm up for anything");

  });

  

  // also equivalent

  this.route('#/', function() {});

  

});

This was actually the first step of another way to define Sammy applications. The new mapRoutes() method allows you to define any number of routes as 2D Array.

$.sammy(function() {

  

  this.runIndex = function() {

    this.partial('index.template');

  };

  

  this.mapRoutes([

    // each element in the array represents the arguments sent to route()

    ['get', '#/user', function() {

      this.partial('user.template');

    }],

    // leaving out the verb assumes the verb is 'any'

    [/\/alert$/, function() {

      alert(this.params['alert']);

    }],

    // passing a string instead of a callback assigns the method with that

    // name from the application.

    ['get', '#/', 'runIndex']

  ]);

  

});

I personally like the method syntax better, but there are some cool uses for this – You could even load your routes from multiple files and add them to the application using JSON.

Filters

before filters are very useful for extracting common functionality out of your routes. However, I’ve found myself writing this pretty often:

$.sammy(function() {

  

  this.before(function() {

    // only run if the path is not the index

    if (this.path != '#/') {

      //… do something

    }

  })

  

});

Taking some hints from Rails, I’ve added options to before filters. The above example could be rewritten:

$.sammy(function() {

  

  this.before({except: '#/'}, function() {

    //… do something

  })

  

});

The filters can match against path (as a string or RegExp) and verb and you can define them in the positive (only) or negative (except). The method that does the matching is exposed as contextMatchesOptions so you can use it outside of before()

I’ve also found myself doing a lot of wrapping entire route callbacks in an asynchronous check for something (usually a login). The new around filters make this easy. around takes a single argument which is a neatly packed function that contains the full execution path of the route being accessed. This includes additional filters and the route callback itself. This also means you can entirely halt the execution by never running the passed callback.

$.sammy(function() {

  

  this.around(function(callback) {

    // `this` here is the Sammy.EventContext

    // just like before, etc

    $.get('/session', function() {

      callback();

    });

  });



})

Lots more

Theres actually a fair amount more to cover in Sammy 0.5, but I think I’ll be doing more short ‘Whats new’ posts soon. Check the HISTORY for a full rundown of changes.

Thanks

Special thanks goes out to everyone who helped with ideas, commits and testing for this release including Lena Herrmann, Jinzhu, dpree, Jeff O’Connell, Todd Willey, Tim Caswell, and Frank Prößdorf (endor).

I’m very happy to announce the next major release of Sammy.js. I’ve been working on this for over a month and the result has been a lot more changes then I expected but over all a smaller, cleaner core code base. Here’s a quick run through of the biggest changes. See HISTORY or the Commits for a full list and more detail.

Plugins

The biggest change, that resulted in a lot of little changes is Sammy.Application#use() which allows you to package and resuse application level code into ‘Plugins’. See the documentation on plugins for more detail. This also marks the start of an official selection of plugins, with two as part of this release and more on the way.

The default template system that used $.srender internally has been extracted out into a plugin. To enable almost the exact same functionality:

// somewhere in your HTML (after sammy.js): 
// <script src="plugins/sammy.template.js" type="text/javascript"></script>
$.sammy(function() {
  // include the Sammy.Template plugin
  this.use(Sammy.Template);
  
});

Events

Sammy.Application’s bind() and trigger() methods now use jQuery’s namespacing to bind to Events. This means that Sammy.Application can now easily catch events that bubble to it like ‘click’ or ‘focus’. The big awesomeness is that the callbacks for these bind() methods are always evaluated within a Sammy.EventContext so that even events triggered from outside the app can be handled in the same way as internal events.

var app = $.sammy(function() {

    this.bind('custom-event', function() {
      // this == Sammy.EventContext
      alert('Custom Event' + this.params['wha']);
    });

  });

  // the app is by default bound to 'body'
  $('body').trigger('custom-event', {wha: 'ZUH?!'});
  //=> system alert ZUH?!
  

Cleanup

With the advent of plugins, Sammy Core is now even smaller (8.9k minified). This is also possible because I’ve removed the former ‘classical’ inheritence code in favor of prototypal inheritence, which is a big win in terms of cleanlieness and global scope leakage.

See Also

I mentioned this on twitter, but I’m working on some new tutorials and screencasts about Sammy. If you have ideas/suggestions, dont hesitate to let me know. The first one should be up next week. I’m going to try to do them bi-weekly, we’ll see how that goes

Again, I’ve tried to be as thorough with inline API docs as I could so any changes should be in the clear. Thanks again to everyone who helped with this release and has supported Sammy recently!

Get Started

• Watch a Screencast (iPhone)
• Read the Introduction
• Read the Docs
• Follow @sammy_js
• Join the mailing list

The Story

About three months ago, when I was knee deep in hacking and playing with Sinatra I had this weird moment as I woke up one morning: “What if I could build Sinatra in JavaScript?” At that point it was just a challenge – I had just started doing almost full-time JS for a client and it seemed like a fun project.

As I started to actually implement it (slowly in short spurts on the weekends), I realized that using the power of JavaScript’s closures and jQuery’s powerful event system, this could be something more then just a ‘clone’. It could actually be . . . useful!

With that in mind, I set out to actually make is usable. I cleaned up the code, I wrote some example implementations, and most importantly – I documented the shit out of it.

I’m pretty excited about it (can’t you tell?) especially about its possible uses for structuring applications on the front-end for RESTful Databases and services. Embed it in a CouchApp to build an entire application in JavaScript while having access to a full range of documents/querying abilities.

The Future

I’m going to continue refining and adding examples. Please feel free to email me or contact me through github with questions/feedback.

Happy Friday!

I decided not to just preach and tried to take my own advice. What came out of my first attempt is gembox. Gembox is a very light interface built on top of Ruby Gems. Download it, start it with:

$ gembox

That’s it. Ruby Gems is great starting point because it has a well defined API and a huge user-base (rubygems users === ruby users). What it doens’t have is a great web interface. Just booting up this little app gives you a pretty (albiet currently shallow) interface to your gems. This app is tiny. I chose to split it out over multiple files, but with your app could have put this all in a single file and included it in your library’s name-space. It’s that easy.

So here’s my pitch: Give your gems/libraries/code bundles beautiful web interfaces with minimal effort using Sinatra.

I think gembox was a successful little experiment and over the next weeks I’ll be updating my gems with simple interfaces.

Currently, I’m in the running for a spot to speak at GoGaRuCo. I like the idea of the attendee’s being able to vote for what presentations to have at the conference, but I think having a truncated synopsis listed might not give me the best chance. So I’d like to try to explain what I plan to talk about a little further. If you like what you hear please vote!

Photo Credit: http://flickr.com/photos/rnyk/2493099076/

It’s finally going to be released as Part of Rails 2.3 (exciting!).

Ryan Bates released a great Railscast with a detailed overview of templates. Ryan does a great job as usual getting to the meat of the feature.

If you’re interested, I have my own Rails template as part of my ‘halpers’. It installs jQuery and a couple of plugins and gems – including a forked version of restful-authentication that has a shoulda test suite and email of login based authentication. I hope you enjoy this feature as much as I do.

Somehow, I missed until now that it had been featured on the github blog. This is an overwhelming honor. Github is one of my favorite tools ever, and using their awesome API was stupid simple and just another example of how awesome github is.

Anyway, getting featured is a serious kick in the butt to get documentation together for all my different projects.

Thanks, guys!

Check it out: http://github.com/quirkey/basecamphp/tree/master

Here’s the big reveal of the biggest thing I’ve been working on over the past forever: The Scout.

There’s a lot to say about this, but my partner in the project, Tom Ran, already said it much more eloquently in an interview with psfk.

I can, however, speak to the technical aspects of the project. It is (of course??) running on Ruby on Rails. I can pat myself on the back about it’s very powerful but easy to use CMS. Were working on adding a lot more articles right now and the whole set up seems to be chugging along without a hitch.

The whole project was a beautiful idea about a year ago but after a lot of lunch and dinner conversations I can finally say that it’s a reality.

I learned a lot on the project and used it as an excuse to grok some new technologies (or at lest new to me) like the Google Maps API.

Were hoping to continue to push our features and content in the coming weeks and months. To keep up:

1. Join the mailing list
2. “follow the site’s RSS Feeds: Blog, Retail, Dining/Bars, Features, and Tours
3. follow thescout on twitter

If you’re interested in contributing email info at the scout mag dot com.

Were just so excited it’s real.

The scenario: Its 3AM. You've been coding all day and youre just about ready to launch this sweet social networking app for steel workers who love to dance. One last thing - you need to replace all the crappy copy you stuck in to your 'flash' messages with real informative text. "sucesfil post" might make sense to you, but wont make sense to the blue collar guy doing the electric slide all over your server. You go to replace these warnings and feedback messages but theyre all over your code. You think: If Rails is so DRY and the business and display logic are all supposed to be separate, then why am I putting messages that will end up in my views all through my controllers?!

Introducing Flashdance

The get-the-view-out-of-the-controller-so-you-can-rest plugin.

Instead of all-up-in your controller files, messages are stored in a single YAML file:

# in app/views/shared/flash.yml

all_is_good: This is great
this_failed: This failed
using_erb: you are an idiot, <%= @email %>
section:
  subsection: I'm nested
my_controller:
  my_action:
    message: I'm soaking wet

Examples

At its most unobtrusive:

# in your controller
  def update
    # . . . booring part where record gets updated
    flash[:warning] = flashdance(:this_failed) #=> This failed
  end

A little nicer:

def update
    # . . .
    flash(:message => 'all_is_good') # YAML entries can be referred to by strings or symbols
    # equivalent to flash[:message] = "This is great"
  end

ERB is evaluated in the context of the controller so you can do fun things like:

  def tell_off_the_spammer
    # . . .
    @email = 'jon@example.com'
    flash(:warning => :using_erb)
    # equivalent to flash[:warning] = "you are an idiot, jon@example.com"
  end

So what if your app is huge and you use these flash thingies all over the place? Your YAML file might get big and unreadable. Well, thats why you can nest! Nested sections are refered to by arrays.

  def make_a_nest
    #  . . .
    flash(:nest => [:section,:subsection])
    # equivalent to flash[:nest] = "I'm nested"
  end

Flashdance automatically checks for entries nested in the controller/action path where you call it from. And heres where you get splashed with that big bucket of water:

class MyController < ApplicationController
  # . . . 
  
  def my_action
   # . . . where you dance your heart out
   flash(:message)
   # equivalent to flash[:message] = "I'm soaking wet"
  end
end

Install it

From subversion:

./script/plugin install -x svn://svn.quirkey.com/quirkey_tools/trunk/flashdance

or Download: flashdance.tar.gz

You can email me at aaron at this domain for bug reports/comments/suggestions - and I'm looking to set up Trac or something else soon.

Photo credit: http://www.flickr.com/photos/tzofia/185003069/]]> http://www.quirkey.com/blog/2008/02/29/drying-up-rails-flash-with-flashdance/feed/ 0