Bloggity
========

Bloggity is a plugin by Bill Harding (http://www.williambharding.com/blog/) that aims to make it brain-dead simple to integrate a fully-featured blog into your Rails site as a plugin.

Bloggity functionality
======================

Bloggity 1.0 sports the following featureset:

  * Create and maintain one or more blogs in a Rails app (e.g., a main blog, a CEO blog, and user blogs)
  * URLs formatted using blog titles for better SEO (e.g., http://mysite.com/blogs/founder/this_is_my_blog_title)
  * Wordpress-like WYSIWYG editor to write blogs in (requires FCKEditor, which is bundled with the plugin)
  * Separate configurable permissions for writing, commenting on, and moderating comments for blogs
  * Pre-built AJAX uploading for blog assets of whatever sort.  Insert assets into your blog in whatever manner you choose
  * Ability to use custom stylesheets on a per-blog basis (i.e., the Founder's blog can use different styling than the user blogs)
  * RSS 2.0 feeds
  * Ability to tag blog posts, filter blogs by tag
  * Ability to categorize blog posts
  * Blogs can be saved in draft mode before publishing
  * Built in support for gravatars
  * Bloggity maintains its own routes, controllers, models, and views.  Bloggity was designed to be as "drag and drop" as possible.  You shouldn't need to manually copy or add anything to your existing app (though the rake install task will copy a couple assets for you into /public/*/bloggity directories)
  * Model & controller test suite   

Installation
============

Full installation instructions (along with the ongoing Bloggity discussion) can be found at http://www.williambharding.com/blog/rails/bloggity-an-evolving-rails-blog-plugin/.  Here's the gist.

Prerequisites:  Bloggity uses attachment_fu, will_paginate, and the engines plugin.  In Rails 2.3, the Engines plugin shouldn't be necessary, but the tasks that copy assets into your public directories use Engines, so if you don't instsall it you will need to copy those assets manually.

Tested versions of all plugins are included in the bloggity/tested_plugins directory.

To use FCKEditor and the AJAX file uploading, you will also need jQuery, the jQuery form plugin and FCKEditor.  See instructions below on automatically adding them to your app. 

The gist:

1.  Grab Bloggity, put it in vendor/plugins/bloggity
2.  Run "rake bloggity:bootstrap_db" from your application's base directory
3.  Run "rake bloggity:bootstrap_bloggity_assets" to copy the images and stylesheets used with bloggity into your apps /public/stylesheets/bloggity and /public/images/bloggity directories.  
4.  Run "rake bloggity:bootstrap_third_party_assets" to copy FCKEditor and jQuery into your "/public/javascripts/bloggity" directory.  This is not required, but the WYSIWYG editor and asset uploading won't work without it. 
5.  Take a gander at bloggity/lib/bloggity/user_init.rb.  This shows the methods that bloggity will use to interface with your user model (for blog permissions and such).  Implement these in a sensible way in your user model.  Don't forget to copy the blog associations into your user.   
6.  There are two methods in bloggity/lib/bloggity/bloggity_application.rb:  current_user and require_login.  Implement these in your application_controller.rb if you haven't already.

And you're done!

Usage
=====

***** Creating Blogs and Blog Posts ***** 

By default, all blogs posts are members of a "Blog."  This allows you to maintain various blogs (e.g., CEO blog, main blog, user blogs) within the same application.  The URL to a given blog post is the combination of the blog name and the blog post name.  So...

To create a new blog post in the default (main) blog:
http://localhost:3000/blogs/1/blog_posts/new

To create a new blog:
http://localhost:3000/blogs/new
 
To view a blog post entitled "My first blog" that was posted to the main blog:
http://localhost:3000/blog/main/My_first_blog

***** I Am Only Planning to Use One Blog, Can this be Simpler? *****

Probably... :)

If you only plan to use one blog, and would like your URLs to simply be formatted as http://localhost:3000/blog/My_first_blog, you might just be able to add this to your routing file:

map.connect 'blog/:id', :controller => 'blog_posts', :action => 'show'

I haven't had a chance to test this yet, though.  If anyone is using bloggity with one blog, feel free to drop us a line at the WilliamBHarding blog with your results.

***** Setting Up User Permissions *****

All of the permissions for whether a user can post a blog, post a comment, moderate comments, and whether their comments are automatically approved are set by methods in your user.  Each permission takes an optional blog_id parameter, so you can configure permissions relative to a given Blog if you choose.  

If you followed the install instructions and ported the methods from user_init.rb, you've already setup Bloggity permissions in your app.  Bravo.

***** Uploading Assets *****

When you are posting a blog, you can choose an asset to upload near the bottom of the page.  Upon selecting your asset, it will immediately begin to upload.  After the upload is complete, you'll be given the URL to the uploaded asset.  If it's an image, you'll also be shown a picture of what you uploaded.  Bloggity remembers which assets were associated with which posts, so if you return the post later you'll still see the assets associated with that post, however your users will not be able to see the assets you've uploaded with the blog post until you link those assets from within the blog post itself in some way.

How you link to the asset will generally depend on what type of asset it is.  If it's an image, obviously you can just add an image tag that points at the asset URL.  If it's something else, you can probably figure it out.

If you'll be uploading assets other than images, you'll need to edit BlogAsset.rb and change the "content_types" to include the type of asset you want to upload.

Remember:  Uploading assets won't work unless you added jQuery and the jQuery form plugin with the "rake bloggity:bootstrap_third_party_assets" step.

***** Other Options *****

* Specify that a stylesheet other than the standard "blog.css" should be used to style a given blog:  edit the blog, there is a field for "stylesheet."  This path is relative to the base /public folder of your Rails app, so if you entered "stylesheets/bloggity/blog.css" you would point to the original blog.css file.
* To save a blog in "draft mode," just don't check the "is_complete" checkbox when you save your blog.  It won't be added to the blog index (or viewable by users) until "is_complete" is checked. 

Testing
=======

"rake bloggity:run_tests" from anywhere within your app. 

Todo
====

* Setup blog categories to do something meaningful
* If blog post page is refreshed via F5 (after clicking new), the request to create a new blog is re-POSTed, meaning user is sent to a new blog.  Would be nice if it weren't so.
* Better support for those who don't want to use FCKEditor
* akismet spam filtering
* Comment trackbacks


Acknowledgements
================

Many thanks to Robert Graff and the team at Goldstar (http://www.goldstar.com) for sponsoring Bloggity version 1.0.