Ansuz:  Up & Running with a CMS that Works

Josh Adams [Isotope11] and Lex Sheehan [IBM] | December 12, 2008 | For the Ruby Advent Calendar, 2008

Ansuz is an open source (BSD licensed) web content management system (CMS) written in Ruby on Rails.  It has a plugin system based on Rails Engines, and it's themable.  It aims to provide more features out of the box than any comparable Rails-based CMS.

This article is an introduction to Ansuz, as well as a getting started guide for both users and developers.  If you're still a bit unsure what Ansuz is all about, think of it as a Rails-based competitor for Joomla, WordPress, etc.  It provides you with a lot of functionality out of the box, but it won't make you shoot yourself later on.  Ansuz is currently undergoing very active development and is constantly improving.  This will continue to be the case, as Ansuz is the product in which all of Isotope11's CMS-driven websites will be built for the foreseeable future.

Let's get started by looking at the Edit Page in the Ansuz admin interface...

You might say, "Wow, that looks swell! ... But how do I get it on my personal computer post-haste?"  The following instructions should get you up and running with Ansuz quickly.  Note that mysql is a prerequisite (for the demo database, not for Ansuz).

Installation

1. Clone from github: git clone git://github.com/knewter/ansuz.git
2. Create database config in: config/database.yml (see config/database.yml.example if you need help). Create the development database now too:   mysqladmin -u <mysqluser> -p create ansuz_development
3. Load the demo site database dump: mysql -u <mysqluser> -p ansuz_development < RAILS_ROOT/db/demo_site.sql
4. Install necessary gems: rake gems:install
5. Run tests: rake spec
6. Create the folder at: mkdir RAILS_ROOT/public/uploads (This is for fckeditor's resource browser / uploader)
7. Start server: script/server -p 3000
8. Go to: http://localhost:3000/admin
9. Login with: admin/admin

Getting Started

The initial data load populates the Ansuz database with a basic company site with:

•   Structured Content Sections
  
•   Blogs
•   Forums
•   Photo Albums
  

Here are a few things to start with:

Manage Pages

This is where you create the structure of your site and can quickly see the status of each page.  You can also easily see some of the plugins that come enabled out of the box in the Manage menu.

Figure 2.  Manage pages - an overview of your site's tree structure.

Ansuz Themes

Use Ansuz Themes to manage the look and feel of your web site.

Figure 3.  Choose a Theme - Choose from your installed themes.

Choose the default pink theme and your live site will look like this:

Figure 4.  The home page with 'default pink' applied.

Ansuz's theme support is provided by the aptly-named theme_support plugin.  You can see the repository layout for the default theme here.  Basically, a theme can be as simple as a folder with a 'layouts' directory and a 'stylesheets' directory, as well as an application layout calling your stylesheet.  Themes can also override any views Rails is aware of, so if you want to show a photo album differently in your theme you're welcome to.

You can discover and install new themes (or distribute your themes to existing users) from the Anzus Theme Syndication Server.  If you're writing a theme and would like it to be included in the main Ansuz theme repository, all you'll need to do is set up a public git repository for your theme and send me an email.

Figure 5.  Install new themes from the main Ansuz theme repository.

Ansuz Features

Almost all of the features of Ansuz are provided by plugins, rather than by Ansuz core.  Ansuz core consists of the following: the login and roles system, pages, and the API for plugins.  All of the other features are provided as plugins that come with the project.

Writing a plugin is just as simple as writing a theme, as evidenced by the extremely straightforward menu system plugin.  Let me introduce you to the API available for Ansuz plugins to tie into the admin interface.  From that plugin's init.rb:

Ansuz::PluginManagerInstance.register_admin_menu_entry('Manage', 'Menu', '/admin/menu_entries')

That line allows the menu system plugin to introduce an entry point into its interface in the admin menu.  The Ansuz::PluginManagerInstance is actually loaded into the Rails app in Ansuz's config/environment.rb before the Rails::Initializer block (so stuff in vendor/plugins can use the interface):

# Initialize the Ansuz Plugin Manager instance
Ansuz::PluginManagerInstance = Ansuz::PluginManager.new

Note: It's important, if you're working on a plugin for Ansuz, to mark any controllers as 'unloadable' or bad things will happen on your second request in development mode.  For an example, voila.  The controller that link points to also makes it clear that writing a plugin for Ansuz is just bog-standard Rails application development.

There's another thing that Ansuz plugins can provide: a Page Plugin.  These are plugins that can be placed on a given page one after another.  The main PagePlugin is a Rich Content Editor provided by FCKEditor; its code can be found here.  At present, there are four such plugins: Content Section, Photo Album, Scrollable Content, and Form Builder.

The following tables will give you a feel for Ansuz's current feature set:

ADMIN FEATURES	COMMENTS
Admin interface	An administrative interface that plugins may hook into.
Approval Workflow	Require a content reviewer to approve content before it is published.
Menu Editor	Create a menu system for your web site that links to urls that you specify.
Access Control	Role-based access control using the authorization plugin.
RIA Editor	FCKEditor
File/Asset Mgt	Create a file storage structure, upload and manage files for your web site.
Content Preview	"Edit" links display for content editors -- takes user directly to corresponding content in admin interface
Navigation	"Manage Pages" shows site structure, workflow status, and is good way to quickly find your editable content
Editable Views/Templates	Ansuz provides a free form way to enter content for your site.  FCKEditor templates can be added for consistency and speed.
Default Templates/Examples	FCKEditor default templates.
Theme Management	Create, install, and choose your site theme from the admin GUI
Default Themes	Choose a theme from the Theme Repository.
Content MetaData	Store metadata with content to enhance search results.
Direct Link into Ansuz Community	Ties into http://www.crowdsound.com for feature suggestions, and links directly into the bug tracker to create a ticket.  The community is a priority.

COLLABORATION FEATURES	COMMENTS
Blog	Personal blogging with comments (NOTE: comments not yet implemented)
Forums	Share ideas and solutions.  Host a discussion.

PAGE PLUGINS (may be placed on a given page)	COMMENTS
Content Section w/ WYSIWYG Editor	Edit content on a page in a WYSIWYG Editor (FCKEditor)
Photo Albums	Display a collection of photos, with headings and captions, in a lightbox interface on a page.
Scrollable Content	Panes of content that can be scrolled between.  See this plugin in action on the home page of http://www.isotope11.com
Form Builder	Add custom forms to a page (build a contact form; have a survey; get some leads) [This plugin is in extreme alpha at present, but should shape up shortly as it is just a port of a plugin from our previous, proprietary CMS that has been field-tested fairly robustly.]

FEATURES IN ROADMAP	COMMENTS
Theme Syndication	Upload your theme to the main Ansuz theme repository for easy distribution to all of the installed Ansuz instances.
Content Section Arrangement GUI	Layout your page using an admin-interface-managed GUI component.
Content Markup	Rich text editing and direct HTML editing currently supported, RedCloth, BlueCoth, etc. to be added.

Summary

Your CMS will likely need customization.  So, choose your CMS solution carefully, based not only on current features, but also based on the language and framework upon which it runs.  Ansuz runs on Ruby on Rails with a flexible plugin-architecture, which means better code, lower risk and a lower total cost of ownership.

I hope this article has served to pique curiosity and to get others interested in developing Ansuz alongside us.  If you have any questions about Ansuz or would like to have a detailed discussion about any portion of it, feel free to contact me at josh at isotope11.com.

---

About the Authors

Josh Adams is a Partner and Lead Developer at Isotope11.  He got his joint degree in Mathematics and Philosophy from the University of Alabama at Birmingham, and has been developing in Rails since before Rails 1.0.  He also co-founded, with Kevin Russell and Greg Houston, the Birmingham Ruby User's Group, RubyHam.  Isotope11 is currently taking on new projects.  Check out our portfolio.

Lex Sheehan is a Senior Software Engineer at IBM and active member of the Atlanta Ruby Users Group (ATLRUG).  He has provided valuable use cases over the course of evaluating, integrating and deploying Ansuz with an integrated JRuby on Rails RIA web application with advanced search capabilities whose target environment is the following:

Links

http://www.ansuzcms.com - The main site for the Ansuz project.
http://github.com/knewter/ansuz/tree/master - Ansuz's master repository.
http://crowdsound.com/hosted_site/popular?aid=718 - Ansuz's CrowdSound page, to make feature suggestions and allow the community to vote up/down the features they would like to see.
http://ansuz.lighthouseapp.com/projects/15780-ansuz - The Bug Tracker, provided by Lighthouse.
http://www.isotope11.com - Isotope11 provides custom software for businesses, as well as Rails consulting and fancy new Rails-based Content Management Systems :)
http://www.isshen.com - Adam Dill and Hosh at Isshen Solutions work on Ansuz as well.
#ansuz on FreeNode - Come join us on IRC, someone's always on.  We can help you with any problems you run into as well.