Create a rails plugin to preprocess assets - ruby-on-rails

Question

I created a small CSS preprocessor, which is somewhat similar to SASS, and now I would like to test it in a 'real life' scenario, so I'm trying to create a rails plugin for it, like the way sass-rails works.
I tried this, without being really sure of what I was doing:
require 'toss-ruby'
require 'sprockets'
module Toss
module Rails
class Template < ::Tilt::Template
def prepare
end
def evaluate(scope, locals, &block)
g = ::Toss::Generator.new
g.parse_string data
g.generate_string
end
end
end
end
Sprockets.register_engine '.toss', ::Toss::Rails::Template
According to the documentation, the last line should register my template so sprockets can use it, but it doesn't happen, so I assume it's never called. How do some gems like thin, sass-rails, etc... manages to work only by being put in a Gemfile ? When and how is their code called ?

Answer 1

There is a convention that executes code in gems that are included in your Gemfile.
If a file exists in the lib directory of a gem's codebase with the same name as the gem and with a .rb extension, it is required by default when Bundler loads the gem.
Take a gem called "Mygem" as a example. This is a typical directory structure for a gem:
mygem/ (gem's root directory)
|-- lib/
| |-- mygem.rb <-- automatically required!
| `-- mygem/
| |-- base.rb
| `-- version.rb
|-- test/
|-- bin/
|-- Rakefile
`-- mygem.gemspec
When Bundler loads the 'mygem' gem, it automatically requires lib/mygem.rb. Rails plugins and engines rely on this behavior to load their code. Typically, they use this file to require other files in the lib directory. In this case, the lib/mygem.rb file may require lib/mygem/base.rb file, etc.
While developing a gem, it's common to add it to your Gemfile by using the Bundler :path directive, which tells Bundler to look for the gem at a certain path on your local filesystem, rather than on rubygems. Let's assume you are building your gem under the vendor/engines directory of your test application.
Your test app's Gemfile:
gem 'rails'
gem 'mygem', path: './vendor/engines/mygem'
When the Rails app is started, one of the first steps is to load it's gems. When the 'mygem' gem is loaded, Bundler requires './vendor/engines/mygem/lib/mygem.rb' which executes the code in it. Any code you put in there will be run even before Rails is initialized.
If you have code that needs to be run as part of application initialization, you need to follow the guide for creating Rails plugins/engines. Typically, you'll inherit your plugin from ::Rails::Engine and call initializer in it and pass a block containing your initialization code.
With all this in mind, have a look at source code for the sass-rails gem again, specifically lib/sass-rails.rb which gets required when the gem is loaded and how it recursively requires lib/sass/rails/railtie.rb, which does the necessary setup and initialization for the plugin to integrate with Rails.