Archive for the ‘Pancake’ Category

Inherited Templates in Pancake

November 28, 2009

Update: Fixed some of the code examples to remove a stray block

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:

# base.html.haml

!!!
%html
  %body
    %h1 Welcome to base
    - content_block :content do 
      %p Default Base Content

# foo.html.haml

- inherits_from :base
  
- content_block :content do 
  %p Foo Content

If we had a stack that looked like this:

class FooStack < Pancake::Stacks::Short
  add_root(__FILE__)
  
  get "/" do 
    render :base
  end

  get "/foo" do
    render :foo
  end
end

When we visit the “/” url we’d get output like this:


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
  <body>
    <h1>Welcome to base</h1>
    <p> Default Base Content </p>
  </body>
</html>

When we visit “/foo” we’d get something like this:


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
  <body>
    <h1>Welcome to base</h1>
    <p> Foo Content </p>
  </body>
</html>

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.

# foo.html.haml

- inherits_from :base
  
- content_block :content do 
  %p Foo Content
  = content_block.super

By calling super on the content block, you’re inserting the content of the parent block inside the child. The output of running that template would look like this:


<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
  <body>
    <h1>Welcome to base</h1>
    <p> Foo Content </p>
    <p> Default Base Content </p>
  </body>
</html>

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:


- inherits_from UiStack, :base

- content_block :content do 
  %p Some content

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:


- inherits_from :default!

- content_block :content do
  %p content for this view

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.

Pancake’s Console

November 19, 2009

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 $rack including goodness from Rack::Test so you get a whole bunch of methods for free 🙂 Lets try a few out.

∴ racksh
 ~ Loading Development Environment
Rack::Shell v0.9.4 started in development environment.
>> WagyuBlog::BlogEntry.all
=> [#]
>> VegetableBlog::BlogEntry.all
=> [#]
>> response = $rack.get("/wagyu")
# snip response
>> response.status 
=> 200
>>

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 🙂

Getting Started with Pancake

November 15, 2009

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.


$ pancake-gen micro app_container
$ cd app_container
$ mkdir mounts
$ cd mounts
$ pancake-gen short mounted


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.

$ shotgun -s thin -p 5000

Now you can visit http://localhost:5000/ and http://localhost:5000/mount to see your nice shiny new mounted application 🙂
When you're ready to give it a non-reloaded squirt, I use unicorn to start.

$ unicorn -p 5000

it's much faster.

Although we haven't gone into the ins and outs of how to write pancake apps. At least we can now generate them and get started.

Pancake Stacks… A great tasting blog

November 9, 2009

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.

Pancake