Clone this wiki locally
CanTango is split up into a few major logical units that we call engines. Currently CanTango comes with these engines:
Note that the Cache engine is not a "real" engine, as it doesn't subclass
CanTango::Engine and isn't executed.
You can configure each engine to some extent and even replace the engine entirely with your own custom implementation by using the
#factory config method. See Configuration for more details.
CanTango also lets you create and register your own engine into the mix.
Any CanTango engine can be configured and examined with the engine config API as demonstrated here:
CanTango.config.engine(:permit) do |engine| puts engine.modes engine.mode = :cache engine.set :on engine.reset! # state to default value puts "ON" if engine.on? puts "OFF" if engine.off? end
Note that control of caching is now done by setting execution modes and not by setting the caching engine directly (like it used to).
Engine Registration and configuration
CanTango lets you register engines and configure the execution order in the Ability execution flow.
Engines Config API
active- list of symbols for all active engines (that respond true to on?)
Engine Registration API
Engine Execution order API
execute_before existing_name, name
execute_after existing_name, name
Example engines registration and configuration:
CanTango.config.engines do |engines| engines.register :my_engine => MyCoolEngine, :performance => PeformanceTool engines.execution_order :permit, :my_engine, :permission engines.execute_before :permit, :performance_tool engines.execute_last :performance_tool end
CanTango::PermissionEngine are classes that both implement the generic
Creating Custom engines
Creating a custom CanTango engine is not too difficult. Start by subclassing the base
class MyCustomEngine < CanTango::Engine end
This will automatically register the engine with CanTango, similar to Users, Accounts and Permits, using an inherited hook on
Now implement the CanTango Engine API. You need an
#initialize method that takes an ability and a
#permit_rules method that populates the rules set.
class MyCustomEngine < CanTango::Engine def initialize ability super end def permit_rules ... rules << my_rules if !my_rules.blank? ... end def engine_name :permit end def valid? return false if !valid_mode? stuffies.empty? end def key_method_names [:stuffies] end end
Currently you also need an
#engine_name method which returns the name of the engine. In the future this name will be extracted from the class name unless this method is specified.
#valid? method should return true only if this engine is valid for the current context (fx the cache mode).
#key_method_names should return an array of methods to be called on the ability candidate to be used for calculating the cache key for this engine.