=About Imagine CMS

Imagine CMS is a content management system developed by {Bigger Bird Creative, Inc.}[https://www.biggerbird.com] in 2006 for its clients. Other systems came with a learning curve: fine for daily users, but clients who only used it once a month or so would never remember how to use the system the next time they logged in. Simpler systems didn't allow us enough flexibility as designers and developers.

=Demo

Working on this... it needs to be fairly resilient to hacking attempts, not a trivial thing to set up.

=History and Roadmap

Thus, Imagine was created in the Rails 1.0 days, to run a large number of technically simple content-based sites (versus the one or two highly customized web applications most Rails developers were building at the time). We wanted to provide a way to create and manage static content while also allowing some automation (navigation, RSS feeds, etc.) while also allowing limitless custom development. However, because plugins/engines were quite limited in those days, Imagine was implemented by monkey-patching core parts of Rails and creating a new framework on top of Rails. Although this allowed us great insight into the inner workings of Rails (and led to a minor contribution to Rails core), this approach proved extremely difficult to port to Rails 2. Thus, sites using Imagine have been stuck on Rails 1.2 since time immemorial.

All that is now firmly in the past. By extracting Imagine functionality into a gem (a Rails Engine), we have achieved compatibility with Rails 3.2 and Ruby 1.9 and removed roadblocks to a future upgrade to Rails 4 and Ruby 2, all while remaining backwards compatible with the legacy Imagine CMS database structure.

Of the three original phases of this project, two remain:

* Imagine 3.0 (Rails 3.2, Ruby 1.9): [DONE] 90% restored functionality, no database changes.
* Imagine 3.1 (Rails 3.2, Ruby 1.9/2.0): 100% restored functionality, plus a few extras. May require a few simple migrations.
* Imagine 4.0 (Rails 4.0, Ruby 2.0): Upgrade to Rails 4; refactor & rewrite the worst parts (substitutions); drop ERB templating for something safer, like Liquid; switch to a cross-browser editor; drop Prototype for jQuery; modernize HTML, CSS, JS

(Imagine 1.x and 2.x version numbers have already been used internally, so we started at 3.0.)

=Current Status

Imagine 3.0 is finally ready for production use internally at Bigger Bird, but it's not quite ready for general use yet. Probably still buggy, not all functionality has been properly exercised, and there are no tests yet, I'll tackle this for 4.0 as we modernize the internals.

One major feature is still missing: browser-based editing of view layouts and stylesheets. While convenient, this was probably not ever a good idea, so I'm working on a better solution.

Unless you are interested in contributing to development, it might be best to wait until the second phase of this project (Imagine 4). Why? Well, the purpose of Imagine 3 is strictly to port legacy sites to Rails 3.2 as simply as possible. Imagine 3 will always be held back by its need to remain compatible with legacy installations dating back to 2006. The ERB templating language can be dangerous (it allows all Ruby, including shell escapes), and the editor (powered by an ancient version of Dojo) is Firefox-only. It also uses Prototype, which has become a bit unfashionable these days.

Imagine 4 will be a clean break from all of these "traditions," and thus will be a good time to get on board.

=Hosting

Imagine 3 can run on most "standard" Rails hosting platforms, anything that uses Passenger, Unicorn, etc. On hosts that don't allow/recommend writing to the local filesystem (e.g. Heroku) you won't be able to use photo galleries or page caching, but other features should work (this has not been tested).

=Getting Help

Get paid support and hosting for Imagine CMS straight from the people who made it: {Bigger Bird Creative, Inc.}[https://www.biggerbird.com] Neither is required, of course. :-) Free support is up top (Issues).

=Customizing & Contributing

Pull requests always appreciated (recommend getting in touch first). If companies or individuals are willing to sponsor major features on the roadmap (or features that meet their own needs) development can proceed more quickly.

=Migrating from Imagine 2.x

Putting this at the end because this information may not useful to the general public at the moment. It will evolve over time into a general getting started guide.

File/code changes:
* Rename all .rhtml files to .html.erb, .rxml to .xml.builder
* Find and replace: RAILS_ROOT => Rails.root
* Find and replace: SITE_ROOT => Rails.root
* Find and replace: RAILS_ENV => Rails.env (not all instances: constants only, leave environment variables)

Assets:
* Delete prototype.js, effect.js, controls.js, dragdrop.js, imagine.js, reset.css, manage.css; move everything else to assets
* Create symlinks to assets in public (images, javascripts, stylesheets, files)

Config changes:
* Move constants from config/environment.rb to config/initializers/imagine_cms.rb. Use Object.send(:remove_const, :ConstantName) as needed to override default values (bit of a stupid workaround but it works).
* [To enable S3 asset storage] Create config/imagine_cms.yml (see sample in test/dummy/config) and add AWS account credentials (preferably IAM, not master account). If using CloudFront, enable "Forward Query Strings" (Behaviors > Edit) to make sure visitors see the latest versions of uploaded assets.

Third party libraries no longer included:
* Install fop in vendor/ if needed.

Layout changes:
* Under app/views/application: Update three partial paths: 'shared/ccs_header' => 'imagine_cms/header', 'shared/ccs_toolbar' => 'imagine_cms/toolbar', '/management/dialogs' => 'imagine_cms/dialogs'
* Add: <%= csrf_meta_tags %>
* Change to standard Rails includes, plus print:
    <%= stylesheet_link_tag 'application', :media => 'all' %>
    <%= stylesheet_link_tag 'print', :media => 'print' %>
    <%= javascript_include_tag 'application' %>

View changes:
* Change <% form_tag do %> and similar to <%= form_tag %>

Major functions that were (re)moved, and how to get them back:
* script/clear_cache: Use rake imagine_cms:cache:clear
* Exception emails: Install exception_notifier gem and add to config/environments/production.rb:
  config.middleware.use ExceptionNotifier,
    :email_prefix => "[EXCEPTION] ",
    :sender_address => %{"Exception Notifier" <sender@example.com>},
    :exception_recipients => %w{recipient@example.com}

Recommended Rails config changes:
* config.assets.compile = true (optional, easy way out for sites with a lot of customizations)
* config.assets.precompile += %w( ... ) (if compile = false, this must be updated properly)