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

Note: we’re essentially just creating a rails engine here and then including fat_free_crm in the gemspec.

• 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 gemspec. Add the following as a dependency:

s.add_dependency ‘fat_free_crm’

• Fill out the rest of the gemspec file as necessary.

• Run bundle install and bundle show to confirm fat_free_crm has been included in your plugin.

bundle install

bundle show fat_free_crm

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.

TODO