Creating a plugin

Creating a plugin

Recent changes to the codebase mean that FatFreeCRM plugins can now be developed as Rails Engines and included as gems. They can be used whether FatFreeCRM is running either as an engine itself (see Running-as-a-Rails-Engine) or as a standalone application (see Setup-Linux-or-Mac-OS or Setup-Microsoft-Windows).

Various plugins have already been updated to use the new engine-based plugin architecture. These include:

• ffcrm_merge
• ffcrm_crowd
• ffcrm_service_hooks

If you’re feeling adventurous, feel free to browse the source to get a feel for what is required.

Starting from Scratch

The steps below essentially just create a rails engine and link it to FatFreeCRM. If you’d like to skip straight to the code or have a copy of this tutorial checked out to follow along, you can clone the ffcrm_awesome repo.

git clone git://github.com/fatfreecrm/ffcrm_awesome.git

• Firstly, ensure you have a recent version of rails checked out. I’m writing this with v3.2.6, which is what FatFreeCRM is currently pegged to.

rails -v

• Then, create a new rails plugin. The following line will create a new plugin called ffcrm_awesome, ensure ruby 1.8 compatible hashes are used and selects postgresql as the default database.

rails plugin new ffcrm_awesome --old-style-hash --full -d postgresql

• Next, cd into your newly created plugin folder and start editting your Gemfile. Add fat_free_crm (we’re using the git version as a gem hasn’t been released for a while).

gem 'fat_free_crm', :git => 'git://github.com/fatfreecrm/fat_free_crm.git'

• Run bundle install to include FatFreeCRM.

Adding a new controller action

Here’s how to add a new controller action called ‘awesome’ that will apply to all your entities within FatFreeCRM.

• Inside your plugin, create a new file called {plugin_root}/lib/ffcrm_awesome/controllers.rb with the following text:

[Account, Campaign, Contact, Lead, Opportunity, Task].each do |model|
  controller = (model.name.pluralize + 'Controller').constantize
  controller.class_eval do
    def awesome
      # Insert awesome controller action code here      
    end
  end
end

• Next, ensure your controller hooks into the plugin initialisation process: augment the Engine class in {plugin_root}/lib/engines.rb with a config block as follows:

class Engine < Rails::Engine
  config.to_prepare do
    require 'ffcrm_awesome/controllers'
  end
end

• Configure your {plugin_root}/config/routes.rb file to include the new action:

Rails.application.routes.draw do
  %w(accounts campaigns contacts leads opportunities tasks).each do |controller|
    match "/#{controller}/awesome" => "#{controller}#awesome", :as => "#{controller}_awesome"
  end
end

Adding your plugin to your FatFreeCRM instance

To test your plugin straight-away on your local FatFreeCRM instance, simply add your plugin to the Gemfile using the path where your gem resides.

For example:

gem 'ffcrm_awesome', :path => '/home/steve/rails/ffcrm_awesome'

• Run bundle install and rake routes | grep awesome. You should see your “awesome” method added to all the controllers as above.

Note: when you release your awesome gem, don’t forget to remove the :path part of the gem file above.

Adding model methods to your plugin

To enhance an existing FatFreeCRM model, one approach is to create a new module and then include it into the existing FatFreeCRM model.

• Create a new module in your plugin at {plugin_root}/lib/ffcrm_awesome/awesomeness.rb with the following code:

module FfcrmAwesome
  module Awesomeness
    def awesome
      "Do something that makes FatFreeCRM awesome"
    end
  end
end

• Now ensure your module is loaded and added to the Account entity. Extend @{plugin_root}/lib/engine.rb

module FfcrmAwesome
  class Engine < ::Rails::Engine
    config.to_prepare do
      require 'ffcrm_awesome/controllers'
      require 'ffcrm_awesome/awesomeness'
      Account.class_eval do
        include FfcrmAwesome::Awesomeness
      end
    end
  end
end

• Load your FatFreeCRM app in a rails console and confirm that Accounts now have the awesome! method

>> Account.first.awesome
=> "Do something that makes FatFreeCRM awesome"

Note: if you make changes to your plugin code you will need to restart your rails console. Simply typing reload will not reload the plugin code.

Testing your plugin with Combustion

Combustion helps you test your rails engines by providing an interface to the parts of rails that you need in order to test. The github page contains detailed setup information and the steps below mainly come from there.

• Add rspec-rails and combustion to your plugin’s gemspec file

s.add_development_dependency 'rspec-rails', '~> 2.0'
s.add_development_dependency 'capybara', '~> 1.1.2'
s.add_development_dependency 'combustion', '~> 0.3.1'

• Run bundle install and initialise rspec

bundle install && rails generate rspec:install

• Edit spec/spec_helper.rb to include Combustion.initialize!. This must go before rspec/rails and capybara/rspec. The top of your file should start like this:

require 'rubygems'
require 'bundler'
require 'rails/all'

Bundler.require :default, :development

require 'capybara/rspec'

Combustion.initialize!

require 'rspec/rails'
require 'rspec/autorun'
require 'capybara/rails'


... rest of spec_helper file goes here.

• Now initialize combustion which will create a rails project in your spec/internal folder.

bundle exec combust

• To ensure combustion uses your FatFreeCRM schema, copy your db/schema.rb file from your FatFreeCRM instance to spec/internal/db/schema.rb.

• Edit spec/internal/config/database.yml to point to your test db.

test:
  adapter: postgresql
  database: ffcrm_awesome_test
  username:
  password:
  schema_search_path: public
  min_messages: warning

• Write a test for the awesome controller method we created above. Call the file spec/routing/awesome_spec.rb.

require 'spec_helper'

describe ContactsController do
  describe "routing" do
    it "generates awesome route for contacts" do
      { :get => "/contacts/awesome" }.should route_to(:controller => "contacts", :action => "awesome")
    end
  end
end

• Run rspec spec and you should find you have a passing test.

Thanks for reading and hopefully now you can go and make FatFreeCRM even more awesome!