Now that you have the Comatose plugin installed and ready for action, it needs to know which 'root' path, or base URI, to serve content from. That mapping is done in your routes.rb file. It's as simple as adding the following as the last entry (even after the map.connect ':controller/:action/:id' route):

map.comatose_admin
map.comatose_root ''

With this in place, Comatose will start serving pages directly from the root of the application. Since it's the last route, if there aren't any previous matches (to the other routes you've defined for your application), it will pass the URI info on to the ComatoseController.

Note: Don't forget to remove the default Rails index.html from app/public/, if it's there it will be used by the server instead of the comatose root page!

This is the bare minimum for integration. At this point, you should be able to visit http://127.0.0.1:3000/comatose_admin and start adding pages.

Multiple Mount Points

You can map multiple roots to your application by simply calling the map.comatose_root once for each location.

map.comatose_root 'pages'
map.comatose_root 'content'

That's nifty, but it doesn't seem to be all that useful like that. Now, if you can map a URI root path to a sub-page of your page tree, then it becomes handy. Here's how you'd do that:

map.comatose_root 'help', :index=>'help'
map.comatose_root 'content', :index=>'other-content'

Mount Point Configuration

You can configure how Comatose works per root path. Here are the options you can specify when calling map.comatose_root:

• :index -- The full_path of the page to mount to this path
• :layout -- The Rails layout to use when rendering this page
• :use_cache -- Setting to false disables caching for this mount point

So, perhaps we have a page in our tree that is the parent node for all of our application help. And perhaps we want it styled differently than the other comatose pages. To do that, we'd just create a new Rails layout and tell Comatose to use that layout when rendering all help pages:

map.comatose_root 'help', :index=>'application-help', :layout=>'help_layout'
map.comatose_root ''

When you don't send in the :index, it will default to the root node. Also, Comatose will use a generic layout that's been included in the plugin if you don't specify a :layout.

Named Comatose Routes

You can add named routes for Comatose mount points. You use map.comatose_* where "*" is anything other than "root".

map.comatose_help 'help', :index=>'application-help', :layout=>'help_layout'

This will create a comatose_help named routed that you can use elsewhere in your application. You can specify a child page of a named route like this:

<%= link_to "Account Help", comatose_help_url(:page=>'account') %>

Page Content

The page body gets processed, then filtered. Processing generates content based on dynamic tags (in Liquid, or ERB). Filtering takes the content and converts it into HTML.

Text Filters

Text filters convert the text into HTML. Comatose comes pre-configured with support for using Textile, Markdown, Markdown+SmartyPants, or RDoc.

If there is another text filter type you'd prefer beyond the default filters, you can write your own text filter as simply as putting this in your environment.rb file:

# SMARTYPANTS
TextFilters.define "SmartyPants" do |text|
  require 'rubypants'

  def render_text(text)
    RubyPants.new(text).to_html
  end
end

If you try to require a library that isn't installed, the TextFilter will not enable the filter. Therefore the filter drop-down on the edit page form will never show a filter that throws an exception when being loaded. For this to work properly, you have to require the library within the TextFilters.define block.

Text Processing

The page body is also is run through Liquid or ERb, so you can get kinda fancy. Here are all the items you have access to in the processing context:

• page.title
• page.slug
• page.keywords
• page.has_keyword.key -- where key is the keyword you're testing for
• page.uri
• page.link -- returns a link to current page
• page.content -- processed and filtered page.body
• page.author
• page.updated_on
• page.created_on
• page.parent -- the parent page
• page.children -- array of child pages
• page.rchildren -- array of child pages in reverse order
• params.* -- request info and any passed params from the mounting point
• * (Any params sent via :locals when inline)

Inline Rendering

Comatose allows rendering of pages inline from your application view, it's used just like rendering a partial:

<%= render :comatose=>'about' %>

Where 'about' is the page path. By default it will return a failure message if you send it a path it can't find. You can tell it not to by sending it the :silent flag, like this:

<%= render :comatose=>'site/navigation', :silent=>true %>

Sending Parameters

Just like partial, inline rendering supports sending a :locals hash, allowing you to send parameters to the comatose page being rendered:

<%= render :comatose=>'welcome', :locals=>{ :username=>'USERNAME' } %>

The parameters are accessible from the page processor just like a page attribute. For example:

h1. Welcome

Hello, {{ username }}

Using ComatoseDrops to Access Application Data

Comatose is designed to be as safe as possible. By default it removes access of destructive ActiveRecord methods, and it doesn't allow access into your application either. What does that mean? It means, by default, you can't access Rails' helpers, or your application helpers from within the page's content.

However, there are times when it's useful to provide a page access to application data. To do that you create a ComatoseDrop. If you're familiar with Liquid's Drop, then you'll feel right at home. Here's an example of simple ComatoseDrop:

Comatose.define_drop 'news' do

  def latest_headlines
    News.find(:all, :conditions=>['created_on > ?', 2.weeks.ago]).collect {|n| n.title }
  end

end

Now, within a comatose page it can be referenced like this:

h2. Latest Headlines

{% for headline in news.latest_headlines %}
* {{ headline }}
{% endfor %}

Viola! That's it.

« The Basics | Comatose Administration »