# Orthorings

Orthorings is a gem to interact with and display content from Orthor.com

The 2 main things you can do with Orthorings are:

* Define an entire site backed by Orthor with the included DSL (more on this below)
* Display content on any page in your app using the included helper methods

## Installation

As a gem

    gem install orthorings

## Configuration

Add a new file (e.g. orthor_config.rb) with the something like the below to your startup directory (e.g. in Rails config/initializers)

    Orthorings.setup do
      account_id "orthor"
      caching :memory, 300, {}
    end

You can specify any Moneta cache class as the first argument to config.caching, the second argument is expiry time in seconds. The third is any additional arguments you want passed to the cache class on initialize.

## DSL

To make creating a new site backed by Orthor super easy, we've included a DSL that lets you define your site. You don't need to supply any view files, you only need to create your own custom layout to override the included dull one. Currently the DSL plays with Sinatra and Rails - the Sinatra Extension is included in lib/sinatra/orthor.rb, Rails support is provided by engine functionality (seen in app/ and config/).

Here is some example usage (more docs to come, this is still a WIP and some aspects will change)

    Orthor::Site.define do
      layout :layout
      keywords "cms, content management, pluggable"
      description "pluggable content management service"

      with_template :basic_content do
        page "/",        :id => "what-is-orthor", :view => :home
        page "/about"
        page "/terms"
        page "/contact", :view => :contact
      end

      feed "/news_and_blog.rss", :id => "news-blog-entries"
      feed "/news.rss",          :id => "news"
      feed "/blog.rss",          :id => "blog"
      feed "/manual.rss",        :id => "manual"

      category "/manual", :page_path => "/manual/:id",
                          :template  => :user_manual
      category "/news", :template      => :news_item
      category "/blog", :template      => :blog_entry_brief,
                        :page_path     => "/blog/:id",
                        :page_template => :blog_entry
    end

### Options

    :id           - the orthor id of your element
    :view         - specify the path to a view file you'd like to render this content with
    :template     - the template to use when rendering your content
    :keywords     - what meta keywords you'd like to use on this page
    :description  - what meta description you'd like shown on this page

#### Category specific

    :page_path     - what path to use for your pages inside a category
    :page_template - what template to use to display a page inside a category

#### Feed specific

    :name         - The name of your feed, used in the feed_helpers

In the above example, every route defined will be handled by the Orthorings gem and rendered through your specified layout, easy! In rails, you will also get named routes based off of the orthor id, e.g.

    "our-blog" -> our_blog_path

## Templates

Your content from Orthor comes down in JSON, so for every piece of content you want to display, you need to provide a HTML template. Some example templates are shown below. Every piece of content you get back has the same attributes (e.g. "Published on", "Created by") plus every content widget on your template indexed by name.

When you define your pages etc, you can tell it which template to use with a :template argument. If you use the helper methods (explained below) you can pass in the template name.

    Orthor::Templates.define do
      template :basic_content, %(<div>{{Content}}</div>)

      template :blog_entry, %(
        <div class="blog-entry">
          <h2>{{Title}}</h2>
          <div class="blog-content">{{Wysiwyg}}</div>
        </div>)
      template :blog_entry_brief, %(
        <div class="blog-entry">
          <h2><a href="{{URL}}">{{Title}}</a></h2>
          <div class="blog-content">{{Wysiwyg.blurb}}</div>
        </div>)

      template :user_manual, %(
        <div class="user-manual-entry">
          <h2>{{Title}}</h2>
          <p class="last-updated">Last updated: {{Updated on}}</p>
          <div class="content">{{Wysiwyg}}</div>
        </div>)
    end


### Template tags

These tags are available to all content:

    {{Title}}        - your content title
    {{Created on}}   - the date your content was created
    {{Updated on}}   - the date your content was last updated
    {{Created by}}   - a hash of the creator details
    {{Updated by}}   - a hash of the updater details
    {{Published on}} - the date your content was published
    {{URL}}          - the URL for your content as defined in Orthor, or auto generated as /category-id/content-id

Other attributes that will be present on a per item specific basis are the names of your template elements, e.g.

    {{Content}}
    {{Featured News Item}}
    {{Supporting Image}}
    {{Markdown body}}


## Example Usage (as provided by the OrthorHelper module, defined as class methods of Orthorings)

In all the methods below, if you don't provide a template name, you will get the parsed JSON array/hash back.

### Content

    orthor_content("content-item-id", :template_name)
    Orthorings.content("id", :template_name)

### Queries

    orthor_query("query-id", :template_name)
    Orthorings.query("id", :template_name)

### Categories

    orthor_category("category-id", :template_name)
    Orthorings.category("id", :template_name)

### Feeds

    orthor_feed("feed-id") or Orthorings.feed("id")

### Meta data

    keywords         - render a <meta> keywords tag for the current piece of content (or the default site keywords)
    description      - render a <meta> description tag for the current piece of content (or the default site description)
    orthor_feed_tags - render a <link> tag for all of your defined feeds


Copyright (c) 2009 Robotic Foo, released under the MIT license