Archive for November, 2009

Pancake uses template inheritance to embed content in a root template. This is similar to Rails layouts, but with inherited templates, you can have different content blocks, each having their own default content. Inspiration for this feature has come from Django and Rango which also use an inheritance concept. There’s really not an easy way to explain in words so lets see what it looks like:

See how the content block for :content in foo was used when we inherited from :base? It’s got “Foo Content” in the inherited one. Templates in a Pancake Short stack can all use inherited templates. By suppling inherited_from with a template name, the current template will inherit from it. You can supply a different template name on each request, and then inherit from a different template each time if you need to.

That’s cool and all. We can inherit from a different template each time. Pancake will take care of finding the right template when you inherit a stack also, so that if a child stack hasn’t defined it, it will look in the parent stack.

Wouldn’t it be cool to be able to append to the parent content rather than just overwrite it though? Well a Pancake Short stack lets us do that too.

One of the troubles with an inherited approach though, is that if I have 2 stacks, Foo and, Bar inside a master container stack MyMasterStack, all three of these will inherit from different places. I’ve just added in Pancake version 0.1.26 the ability to specify a stack name and template name in inherits from. So you could have something like this:

So we’re inheriting this template from the :base template of the UiStack. Kinda cool, but there’s still a problem. I need prior knowledge that it’s the UiStack that I want to inherit from. That’s ok when it’s your app, but if you write a stack for general consumption you may not be able to make that assumption. Pancake sorts this for you. You can tell Pancake, at a global level, which Stack you’d like to set as the master template stack. By default this is the container stack when using pancake stand alone. If you’re just adding it somewhere else though, you’d start the container stack like this:

MyStack.stackup(:master => true)

This sets the stack as the master which adds the “master” directory as another root for the stack, but also sets the stack to be master of templates. To manually set the stack as master of templates you do this:

MyStack.before_build_stack do
Pancake.master_templates = UiStack
end

This sets the UiStack as the master for the whole pancake graph, which lets us do this:

Using the :default! template name, will tell pancake to inherit from the master template stack, in this case UiStack, with the :base template. You can tell it to use a different one but by default, :base is the one that gets used.

By using this mechanism, a collection of different shared stacks can share the same look and feel by inheriting from the global Pancake master templates stack. When writing plugins and shared stacks, you can just set the stack templates to inherit from :default! and everything should just work.

This weekend I got to go to Railscamp 6. Railscamp is so much fun. There’s heaps of really cool ruby peeps there. I’d start to name them but there were over 120 people at this one so it may not make for the most interesting read to those who weren’t there.

The reason I’m writing this post though is not about Railscamp itself, but rather the project that I helped hack on. Lincoln Stoll flew all the way from Germany to be at Railscamp. I love catching up with him and as usual, he had plenty of interesting stuff happening. One that really caught my attention was his idea of having a proxy through to CouchDB. We’d love to be able to use CouchDB in applications with some authentication and whilst the Couch team are working on this, we’d still like the auth to come from within the ruby application via Warden or something so we’re not doubling up on auth logic. It’d also be awesome if we can mount couchdb in my applications url space so that we can use couch directly from the browser via ajax in my main application. Something that I’ve actually wanted to do for a while.

So I started hacking on implementing this in Pancake while Lincoln got over his jet lag. When he got up he showed me what he’d done on the plane as a lambda based rack application which sorted the issues I was having, and between the two of use we had a Pancake stack that was proxying to couchdb in pretty short order.

You’ll see that when you mount it away from root, the /_utils resource doesn’t really work. That’s because couch doesn’t know it’s mounted and generates the urls without the mount path appended. That doesn’t matter for what I want though, which is accessing the database itself via json calls.

Now, say we want to augement that so that we have an “/admin/users” resource on our stack. Maybe we want to provide a signup form or something similar, or maybe a login form. You can just add actions to the stack like you normally would. For example, lets inherit the ProxyStack into our own stack, and make some tweaks:

You’ll notice that I’m prefixing the class definitions with “::”. This is to put them into the global space. When loading a rackup, they’re loaded into an anonymous class/module. You can get around that by not declaring classes directly in your config.ru file.

The other thing we wanted to be able to do is authenticate / authorize calls to couchapp from within our proxy. Lets say we’re using Warden for the authentication. We can use a before_proxy hook to add an authenticate! call, allowing a host application to specify what that means, and just using it in our proxy stack.

class ::MyProxy :admin_users do
"You're in #{stack_class} at #{url(:admin_users)}"
end
end

Here, we’ve added a before hook to show authentication via warden, and also to print out a little message to the log. The hook is run in the action context so it’s like we’re right inside the action. We’re not going to setup warden inside this article so we’ll leave it commented out. You can add as many before_proxy hooks, and after_proxy hooks as you like.

So now we’ve seen it as a raw rack app, inherited into a container app, augmented and authenticated. But what about actually using it in X% of ruby apps… Rails. Well, because it’s rack, you can use it in rails as a metal. Go on over to your application and generate a metal:

script/generate metal proxy_metal

Make sure to require proxy_stack in your environment in config.gem and setup your metal to look like this:

Fire it up and head over to http://localhost:3000/couchdb/ and you’ve got your proxy from within rails. It’s important that you don’t mount it at “/” in rails, otherwise every request will first check couchdb before being passed onto your rails app!

But, why did I put so much cruft into the Rails Metal one? You could have setup the rails metal to be this

but I wanted to demonstrate something else. Proxy stack it turns out, can proxy whatever http request you like. This is for demonstration purposes only however. Before you do this, get permission or own the other site. I take no responsibility for your actions if you decide to try and hijack content, which incidentally, would make you a complete douche bag.

One of the really great things that Rails has done is provided us with script/console. This is such a handy utility and it works really well.

It’s no secret what I think of rack, but still, I’ll say it again. I think Rack is awesome, and although the spec is simple, when we conform to the spec we get new things from out of left field 😀 Enter (from field left) racksh This is pure gold IMHO. Install in the usual way:

$ gem install racksh

If we go back to the app we built up in my last post lets see how we can get a console for it.

∴ racksh
~ Loading Development Environment
Rack::Shell v0.9.4 started in development environment.
>>

See the awesomeness of rack there? Racksh does a very nice job at providing a console to all rack applications who follow the spec and also provide a config.ru file. Also, since it’s an awesome tool, it makes your fully stacked up application available at $rackincluding goodness from Rack::Test so you get a whole bunch of methods for free 🙂 Lets try a few out.

I’d suggest everyone checkout the docs and readme for both Racksh and Rack::Test to see what you can do with these great tools, and try them out. Use them with such frameworks as Sinatra, Rango, Pancake and many others 🙂

One of the useful things about Pancake is that you can inherit your full application. This includes routes, bootloaders, configuration, paths and a few other things I won’t expound heavily on here.

What I want to go through is how to use it. Before we get started, make sure you have at least pancake 0.1.20

Since my initial post, Jack Dempsey has written a small test blog for Pancake. It’s not going to upset wordpress at this point (maybe one day), but it will serve to demonstrate inheriting and mounting gem’d stacks. The test blog stack is at http://github.com/jackdempsey/pancake-blog

We’ll also need to add this to the bottom of the config/config.rb file.

Blog.initialize_stack

This makes sure all the models in Blog are loaded before we inherit.

Ok, so lets start up the app again (with unicorn) and head over to http://localhost:5000/wagyu Aaaannnddd… The posts from before have disappeared… That’s actually intentional. It’s done that way in pancake-blog so you can mount multiple blogs in the one process without clashing the posts.
The model Blog::BlogEntry (the post) is inherited along with Blog so we end up with WagyuBlog::BlogEntry and VegetableBlog::BlogEntry. By doing this we’re segregating the data via STI.

That’s kinda cool, but we can do better. It’s not much good to have them all behaving the same all the time, and having all the stuff in the blog_container.rb file isn’t the most awesome. Lets mount them through the mounts directory. Create a “mounts” directory and a sub-directory for each blog:

$ mkdir -p mounts/wagyu-blog
$ mkdir -p mounts/vegetable-blog

Now, lets make the blog_container.rb file look like this by removing the inherit calls:

Start the applciation again. You’ll see that the behavior is the same as doing it the other way. So, what exactly did that buy us? We’ve added a root to each of the blogs. That means we can start tweaking the views and add models / other files etc. We’ll just do one, but it will work for either, or both.

If you look at the pancake-blog source. You’ll see that the view inherits_from :base. Lets replace the base of the wagyu blog. Make a views directory in mounts/wagyu-blog/views and create a base.html.haml file. erb and erubis works just as well. Create your template, remember that you need to create a content block for at least :content (because of the child template in pancake-blog) That means you’ll need something like:

Not a very dramatic template I know, but you can see that it’s different when you render it. The VegetablesBlog at http://localhost:5000/veggies and see that it’s still the same as it was before we modified the templates for the WagyuBlog.

You can change any and all of the templates as you see fit for each inherited mount individually. You can even add a common root to both of them (or the parent class) and tweak there to have it affect both of them.

It’s been a really busy week at work this week 🙂 Now I’ve got a chance to write a quick “getting started” post I thought I’d show everyone how to get going with Pancake.

Pancake is designed to be flexible. You can have a single application contained in a config.ru, a two file config.ru + application file, or something with a bit more structure like a “micro” or “short” stacks.

I’ll just focus on the micro and short generated stacks today. They’re both Pancake “Short” stacks, but the generators are suited to different purposes. To get started you can use pancakes generator “pancake-gen”

Micro

$ pancake-gen micro my_stack

This generator will output enough code to generate your Short Stack app, make Passenger happy, and be able to mount it inside another stack.

The main application file here is “my_stack.rb” and there’s a Rakefile, config.ru, and public and temp directories for Passenger. You’ll also see a pancake_init.rb file. This file is not used unless you’re mounting this inside another stack (we’ll get to that later)

If you take a look in the my_stack.rb file, you’ll see that there’s a simple action in there. With any kind of Short Stack, just return your response at the end of the action and your gold. Pancake and Rack will look after the rest.

Views are stored in the “views” directory in the <template_name>.<format>.<render_engine> format.

Short

$ pancake-gen short my_stack

When you generate a stack with the “short” argument, you get a bit more structure. The biggest difference is that a “short” generated stack has everything you need to make the stack into an independent gem.

$ rake -T

Shows you all the Jeweler goodness for gemming up your stack.
The real working directory in this kind of stack is at lib/my_stack There’s a few more directories generated in there with this one. Mostly it’s just a bit more structure for a larger application.

Mounted Stacks

Ok so after that extraordinarily brief rundown of where each of the generated stack types fit, lets generate and mount these bad boys.

Great, now the "mounted" stack will get loaded when you start up the app_container stack. The AppContainer stack will load all the mounts by loading mounts/*/pancake_init.rb You can use that to load anything you want. Another Rack application like Sinatra, a custom bit of kit. Even ActiveRecord plugins if you wanted.
As it stands right now, there's no way to access the mounted app in the browser though so you need to mount it in url space.
Open up the app_container.rb file and get it looking like this:

class AppContainer < Pancake::Stacks::Short
add_root(__FILE__)
initialize_stack
router do |r|
r.mount(Mounted, "/mount")
end
get "/", :_name => :home do
"You're in the App!"
end
end

Here can see we're also initializing the stack. When we do that, all the mounted apps and models are loaded which we need to do prior to mounting the apps in the router.

You may want to edit the "mounted" app to show something interesting.

# mounts/mounted/lib/mounted/mounted.rb
class Mounted
get "(/)" do
"You're in Mounted!"
end
end

I tend to use shotgun when developing. This is a code reloading rack adapter and suits very well 🙂 I also tend to tell it to use thin and start on port 5000. Go back to the "app_container" directory, so you're in the directory with the config.ru file.

Welcome to my blog about pancake 🙂 Tasty Tasty Pancake. I’ll get into what Pancake is shortly, but I thought a little background might be in order.

Some of you may remember me from the Merb framework. I was privileged to work on the Merb framework for a significant amount of time. We had great growth and had some great ideas, implemented some really good stuff. ahh.. great times…

Well since the announcement of the merger with Rails, I started looking at developing Rails. Unfortunately the ideas and direction that Rails is going for Rails 3, whilst awesome, is not the direction that I wanted to go for my free time project. The idea of fully mountable applications was a very strong lure.

I really wanted a way to mount applications, to have small, focused pieces of code that are loosely coupled. I don’t just mean loosely coupled pieces of the framework, but also loosely coupled pieces of application code.

We really started to see this with Merb Slices and Rails engines. Unfortunately, these just don’t take it far enough. With these methods you cannot just pick up an application, and mount it inside another application. They’re not good rack applications, and not really able to stand on their own two feet as applications in their own right.

There is something that does allow us to do that though. Rack. Rack allows us to create extraordinarily modular code. The fact that Rails, Merb, Rameze, Sinatra, Rango and other frameworks are all built on Rack is telling. Rack built in such a way that code re-use and mountable applications and sub applications are natural within Rack.

So, since shortly after the merger, once I realised that Rails was not the project for my spare time, I started working on a project that implements the ideas I had for creating mountable applications. The applications should be self contained rack applications, able to function as gems, able to pick up an entire application and mount it inside another, able to inherit the whole application, take care of the low level plumbing, and lastly, let you create your own type of application when required.