Creating a plugin

Creating a plugin

FatFreeCRM plugins are really just Rails Engines and can be included as gems in your FatFreeCRM instance. They can be used when FatFreeCRM is running 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!
      "Turning up the 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
=> "Turning up the 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.

Loading assets

To include javascript/stylesheets/images in your own engine, just recreate the app/assets/ folder structure (just as you would in a normal Rails application).

• ffcrm_awesome/app/assets/javascripts/ffcrm_awesome.css
• ffcrm_awesome/app/assets/stylesheets/ffcrm_awesome.css
• ffcrm_awesome/app/assets/images/…

Plugin tests

The best way to test your plugin is to create a dummy rails project, load your plugin into it and run the tests. Thankfully, there’s a simple way to do this and the best explanation I’ve found so far is here . I use this link everytime I create a new FFCRM plugin.

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