I started out using macvim and the janus vim distrubution.  It is packed with all kinds of goodies for Ruby/Rails development.  The first 2 weeks were painful and I had to force myself to stick with it.  I was definitely less productive during those 2 weeks, but after I got past the learning curve my productivity started increasing and now I am much more productive than I was with Textmate.  I am far from mastering it and I think those productivity gains will continue to increase as I learn more and get more comfortable with the keyboard shortcuts.

2 weeks ago, I tried to upgrade Janus and it caused my environment to become unstable.. crashes, performance problems, etc..  I decided to trash my whole vim environment and start over.  In the process I found another vim distribution – YADR.  I had to use it after reading the documentation.  IMO it is better than Janus, but it is also very opinionated.. so definitely not for everyone.

I will be keeping a log of customizations, workarounds, etc in this blog post mainly for my own reference.

Problems:

1. SCSS syntax checker fails to recognize SCSS imports from a Rails Engine

I am using thoughtbot’s bourbon SCSS mixins.  The mixins are part of an engine that outputs to the asset pipeline, so the vim plugin syntastic was not able to recognize the includes.  For some reason it would kill the syntax highlighting and throw the cursor to the start of the file every time I saved w/ Command+s.  I don’t really need the syntax checking for SCSS, since the asset pipeline will automatically show me errors.  To disable it, I just deleted the the syntax checker (I guess you could rename it also if you wanted to keep it around):

Open up a new terminal and you should be on zsh

Problem

I need to add HTML inside the <li> tag that is produced by the formtastic input helper. The helper produces HTML that looks like this:

I want to insert a link in betweent the input field and the inline hints. This is not possible, since the formtastic input helper outputs this entire HTML snippet. You can customize plenty of things within the helper, but I did not see a way to add more html content.

Solution

As I started to dig through the formtastic source I noticed that all of the input elements are using a wrapper module that produces the content inside the <li> tag. Take a look at this module:

All of the Formtastic input classes (StringInput, TextInput, HiddenInput,etc..) pass a block to the input_wrapping method inside their to_html method. The content_tag method takes the element name, content and element options as arguments. See here for more info: http://apidock.com/rails/ActionView/Helpers/TagHelper/content_tag
In order to add my content, I will need to add a String element (my HTML) to this array:

As you can see in the code above, it is just an array of strings that are joined together by carriage returns and marked as safe using the Rails String core_ext html_safe. So I will have to insert my HTML code in the desired position of this array. In my scenario, it makes sense to put the extra HTML between the input tag and the error html. I decided to monkey patch this method (oops, maybe dangerous if I ever upgrade formtastic for this app). I added this code to /app/config/initializers/formtastic_monkey_patch.rb:

The first thing I needed to patch was the Html module. 3 methods were added to this module to allow me to pass :extra_html and :extra_html_class to the formtastic input helper. This was pretty much a copy/paste from “Formtastic::Inputs::Base::Hints”. Then I just had to add the “extra_html” to the array inside the “input_wrapping” method. Now I can do this in my form:

This will output:

I can take this a step further by adding another option for the order that the extra html will appear inside the <li> tag. New monkey patch:

I added one method inside the Html class to set a default extra_html_position within the options hash. Then I modified “input wrapping” so it inserts the extra_html into the specified position. Here is the new formtastic input call in my view:

By passing the :extra_html_position option with a value of zero, formtastic will now insert the extra_html before the input tag. So there ya go… monkey-patched and ready to roll.

Add a test app on Facebook

The first thing you need to do is set up a test app on the Facebook developers site. This will allow you to use localhost as the callback url. Otherwise, FB API will not let you authenticate, b/c the FB App configuration URL will not match your app’s URL. You will probably want 3 different FB apps. One for dev, test, and prod using localhost:3000, locahost:3001 and yourprodurl.com.

In your test FB app settings, click the “Web Site” tab and make the Site URL = localhost:3001

Save your setttings.

Add mongrel to Gemfile

I added mongrel to my test environment instead of using webrick (b/c of issues with header size of google apps callback). I would recommend doing the same. Just add it to your gemfile under the dev and test groups. Here is my Gemfile (with a bunch of other testing gems included):

Make sure you run:

Change Capybara server settings

Add these lines to “features/support/env.rb”:

You need to specify the port so mongrel is forced to start on 3001. You also need to specify the app_host as localhost, because the default “127.0.0.1″ was causing problems with FB API (url encoding I think)

Use Selenium in your scenarios

Preface your cucumber scenarios with @selenium, so you can navigate through external sites like Facebook

Of course you need to set up your cucumber step, based on how you are authenticating against facebook. I don’t provide the implementation details here. Just know that cuc is hitting the facebook URL in the first step of this scenario.

Run cucumber scenarios

You should be good to go now. Facebook will use the correct callback URL and your server will be running on the correct port to handle it.

It is much simpler than I anticpated. You just need to multiply by the the inverse of the fraction (am I saying that right??), round the number and divide by the same number. So if you want to round to half places, you would do this:

Lets start with the first one in my example and run through the steps:

And here it is in a Ruby method:

So you can pass any fraction to this method and it will round to that fraction. For example, you can try this with 20ths:

Remember to add the .0 to the end of the numbers you are dividing, so it forces ruby to treat it as a float. 1.0 / 20.0

This rake task adds a new instance method, so the model can have access to the private method “record_create” in paper_trail. Then it takes all model classes, iterates through them and detects the classes that have paper_trail enabled. If the record has no versions, then it creates the initial version and prints out the result. Now I have a fresh set of data that makes it look like paper_trail was installed to begin with (minus any history I’ve already lost).

Here is how you use it in your own application:

1. Install the gem

2. Generate the password file

3. Add the lock configuration to application_controller.rb

4. Unlock the app

visit this URL and enter the password you created with the generator

5. Override the views:

By default, these views will render inside your default layout. To create a custom layout for these files, just add /app/views/layouts/lock.html.erb The layout must contain a yield.

TECH DETAILS ABOUT THE GEM

(if you are interested in how the gem was created)

The design around this was simple. Use a class method within the application_controller that accepts controllers & actions as parameters. The class method creates a before_filter and that takes these controllers & actions and compares them against the requested URL. If the URL matches the controller/action and the user has not unlocked the app, then access to the page is denied. Using Rails 3 engines makes it easy to add views and a LockController to handle the login, failed login and unlock confirmation pages. Here are the gory details about how this gem was created:

A Note about TESTING

I am using RSpec and Cucumber to test this engine.  Engines are a different beast than other gems, because they are so closely tied to Rails.  As a result of this, I prefer to create a new Rails 3 app inside my gem called “test_app” for any testing.  I have seen a few things out there about creating a dummy app, that I am guessing is a stripped down version of a real rails app, but I am not sure what the advantage is over a real Rails app for testing.  The footprint of a blank Rails app is not that large, so I doubt it is a concern about gem file size (which should not matter, since the test files are not packaged with the gem).  I still need to read up and give it a fair comparison, but for now I dont see a problem with using a real Rails app to test engines.

First, I bootstrap the “test_app” with rspec and cucumber.  Then I include the local path to the gem in the Gemfile:

Providing the path to the local gem, will tell Bundler to load the files in that directory as opposed to installed the packaged gem. This is necessary, in order to avoid building your gem after every code change. If I remember correctly, you will need to generate a gemspec in the root of the gem before you bundle install with the “path” option.

Start with a gem skelaton and make it an engine

The skelaton can be as simple as a “lib” directory and a file inside the lib directory named “lock.rb”. To make it an engine only one file is needed. I always call it “engine.rb” and place it within a subdirectory of lib that matches the name of my engine. So here is my directory structure so far:

When the gem is loaded, it will first execute lock.rb, so the engine.rb file must be required in lock.rb:

The engine.rb file needs to subclass Rails::Engine, require rails and lock itself, in order to make it an engine that Rails can load:

Now the gem can function as an engine. So what does that really mean? Well for one, you use the same directory structure as you would in a normal Rails app. And you can add initializers to engine.rb to interact with rails when it is loading at boot.

Add the Rails-like directory structure

Take a look at my Rails-like directory structure:

The helper & model directories are not necessary for this gem, but I went ahead and added them in case I need them later.

Add the views & controllers

As I mentioned earlier I have 3 views that I use for the login form, unlock confirmation, and refusal page… there is not much to these views. Rails Engines also allow you to add routes, so I placed mine in /lock/config/routes.rb. Most of the code (and its not really much) is in the controllers. I have a lock_controller that handles the login. As you can see, it just checks to see if the form password is equal to the generated password. I placed the “password_match?” method in /lib/lock.rb, to reduce the logic in the controller.

I wrote a few blogs in March about how Rails prevents you from reopening engine classes. Basically, if you have the file in the parent Rails app, then the one in the engine is ignored. For this reason, I was not able to create a file named “application_contoller.rb” and simply add my methods to it. In order to make this work, I have to use a different file name (lock_application_controller.rb) and include/extend the methods into action_controller using an initializer. Here is what the module looks like:

When you create a class method and put it in action_controller, then application_controller can call this method and make it look like a nice DSL (as you can see in step #3 of the gem installation tutorial). So this class method just adds a before_filter and an instance method is created that matches what the before_filter is calling. lock_filter checks to see if it is a locked action and if the user has already unlocked the app. It redirects them to the refusal URL if they have not unlocked and the action is on the lock list. Note that you may prefer to use ActiveSupport::Concern when coding a module that includes instance methods and extends class methods. I am not using it here, but many find the syntax a bit sweeter, so if you dont know about it then google it.

Use an initializer to include the instance methods and extend the class methods in action_controller

There is a pretty cool feature in Rails 3, which allows you to lazy load code in initializers. Check out Simone Carletti’s tutorial on Lazy Load Hooks for details on how this works. In short, when action_controller is loaded, our code can be placed in that class. So I want to include/extend my methods in action_controller. Here is what the engine.rb file looks like after I add this code:

I find that the engine.rb is the best place to put code that dynamically modifies classes at boot. It gives you a central location where you can place all of these calls, and IMO makes engines easier to read. You know exactly what modifications are being made to Rails, just by looking at the engine file.

Creating the password generator

The last piece of the puzzle is to create a Rails generator to spit out our hashed password file. When you make your gem an engine, Rails automatically picks up your generator if you put it in the default path that is expected from an engine. Here is what the directory structure looks like:

So Rails is expecting this path for the generator class (expressing variables in uppercase):

/GEM_NAME/lib/generators/GEM_NAME/GENERATOR_NAME/GENERATOR_NAME_generator.rb

USAGE will allow rails to ouput some documentation for it, and the templates directory (which I don’t use in lock) can house any template files needed by the generator. The generator class is pretty basic:

Subclassing “Rails::Generators::Base” gives you the functionality you need to make this a generator. Any methods contained within this class will be executed. Notice that the argument class method is necessary to pull in the command line arg for the password. source_root will tell the generator where your templates are stored. This code generates a salt and a password hash from the password & salt combination and writes it to a file using the create_file method. You can read more about Rails generators HERE.

So there you have it. Pretty basic, but IMO useful. I hope you find this gem useful and also hope you learned something about Rails Engines. If you have any problems with this gem, leave me a comment or open a github issue. As always, suggestions are welcome, as well as criticism!

Here is how you use Yettings in your own app:

Install the gem

Add Yettings to your Gemfile and “bundle install”

Create a YAML file: app/config/yetting.yml

This file will define all of your key/value pairs. Include all relevant key/value pairs in the default section and anything related to a specific environment in the dev, test, production sections. Note that custom environments will also work without any additional setup. staging for example. Any valid YAML will work, and you can also use erb within the YAML.

Access the values anywhere in your Rails app

Creating custom named Yettings

If you need separate Yettings for different pieces of your app (or if you are using this in a rails plugin), then you can add the yml file to a subdirectory named “yettings”. For instance:

Yettings will append the name you specified in camel case to the class that you access the values with:

I am using this with several of my rails apps and so far it seems to be working well. If you have any suggestions or issues, please leave me a comment or open up a github issue in the repo.

Enjoy!

This can be useful for several reasons:
1. Adding methods to your engine’s models, controllers etc from the parent app.
2. Overriding engine methods from the parent app.  In the example above, I wanted to add some behavior to the create method.

Although not everyone will care about the internals of a widely used open source engine, many developers will find this useful when they write their own engines. You don’t want to have to copy the source from an engine controller or model over to your parent app, just to add or overwrite a method.

If you try to reopen the class using the method at the beginning of this post, then your engine UsersController class is never loaded. The app will instead load the users_controller.rb within its own “/app/controllers” directory. I figured their must be a sane reason for this… and I wanted to get to the root of the problem, so I started digging in the Rails source. From first glance, it looks like this restriction was possibly unintentional (although I don’t know enough about the internals to say for sure). Let’s see what is happening inside Rails:

The engine’s app directory will be in the eager_load_paths and it will hit the “require_dependency” line. “require_dependency” is part of ActiveSupport and it will search for the filename by iterating through the autoload paths and finding the first match in that autoload paths list. Here is the code in ActiveSupport (look at “search_for_file”):

debugging the autoload_paths produced the following result (with a few things removed for readability):

As you can see from the array above, the app paths show up before the engine paths.  As a result, Rails will always search for the file in the parent app’s paths before it searches in the engine’s paths, so *OUCH* it is not possible to re-open the class.  There are probably ways this can be done.. like maybe requiring the files explicitly in an initializer in the engine, but I would rather not resort to such hacks.  My temporary fix is to use class_eval in the parent app, but this is still really ugly.  Anyways.. its getting late and I am done for tonight. I guess I will keep poking around to see if there is a suitable workaround.

UPDATE

After looking around SO, I found a patch for ActiveSupport::Dependencies

With this patch, the require_or_load method is aliased and the engine classes are loaded before the original method is called. Gave it a quick test and so far so good.