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

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

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)

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