Webflow API bindings

In the beginning of this year, I’ve started into a new direction, exploring unknown territory. Exciting times are lying ahead and I already learned a lot in the past month:

In march I joined forces with some amazing people and we founded a company called Penseo.

Working in such an early phase of a startup gives me a lot of freedom. There is room for experiments and I can decide myself what I like and want to try out! For sure, there are a lot of things, that need to be done. Luckily, I can try to find the best tool for the job.

One thing that I was investigating right in the beginning were Rails based CMS solutions. To make it short, none of them are amazing…

This is why we went with Webflow (special thx to Paul for the recommendation)!

It’s composed of 3 main elements:

  • The Webflow-Designer, which is kind of a Photoshop for the Web, embracing Web-technologies at it’s core.
  • The Webflow-Editor, a WYSIWYG, inline on site, content manager.
  • The Webflow-CMS itself, where one can define collections and relationships similar to a RDBMS.

On top of that you get a proper RESTful API which is actually really useful!

Since there were no Ruby API bindings, I created a thin wrapper in order to make my life a little easier.

I hope that someone else might find it useful too. I’d also love to get your feedback, or even better, pull-requests!

using domainFACTORY with heroku and SSL

I’m working on a small side project that requires proper SSL configuration. Since I like using heroku to bootstrap my projects, I thought it would also be a great idea to do that in this case… As it turns out, it was quite a hassle to get it up and running the way I want it to be.

When you create a new app on the cedar stack you get SSL for fee. The only downside here is that this is only true for the your-app.herokuapp.com subdomain that hosts your application. If you want to add SSL to your custom domain it get’s a bit hairy.

Custom Domain SSL

Once you have added your domain to heroku and delegated the the name-server lookup via CNAME, you need to provision a SSL addon that costs $20 per month. This is just for the addon, no batteries included! So you also need to buy a SSL-certificate from the authority of your choice.

This setup is unfortunately not working with my hosting provider domainFACTORY as they allow only subdomains to be aliased via CNAME, the root-domain is not configurable. So you can forward www.yourdomain.de but not yourdomain.de.

CloudFlare to the rescue

The CDN provider CloudFlare has free SSL support when using the Pro Plan that also costs $20. This is a bargain compared to the heroku SSL-plugin as CloudFlare has way more use-cases than just SSL.

Configuring the DNS on domainFACTORY is quite simple. Just go to Für Profis > Nameserver-Einstellungen in your admin setup and remove all the DNS entries. Add the CloudFlare name-server settings to the bottom:


DNS + SSL made simple!

structuring your RSpec project

it is an established convention to put all your rails tests or spec in the test/spec folder. even jasmine javascript files go in spec/javascripts… seriously, wtf?

cucumber features on the other hand go in the features folder… so?

while i don’t like cucumber (because of the additional complexity that comes with gherkin), i like the idea that they think about features as something different.

when writing acceptance tests i put them in the acceptance folder and have a different spec_helper file (usually called acceptance_spec_helper.rb as RSpec runners get confused with multiple spec_helper-files).

acceptance tests and normal rails tests have orthogonal requirements that should be handled in using different setups!

i like to have use_transactional_fixtures and random test execution turned on for regular Rails tests because it’s super fast and each spec should be independent of other tests.

it’s a different thing when writing acceptance specifications with capybara and a real browser that cover a user-session on a separate rails process and runs arbitrary actions against the server, executing JavaScript code within that context.

those acceptance tests have a basic problem when it comes to database queries. changes in one process/thread might not be seen in another one because of transactional visibility. this is often times hard to debug and mind-boggling. there are some “hacks” to get rid of this problem by sharing the same database connection, but they introduce other problems like race conditions.

long story short, i like to turn use_transactional_fixtures of and use fixtures (or hard-coded factory data) for running acceptance tests, as this fits more into the idea of acceptance tests. if you combine this approach with state-full page-objects, than you can write pretty readable tests like LoginPage.new.login(:bob).

I like to run DatabaseCleaner between each group of specs and recreate the fixtures, so they are fresh for each capybara spec file.
This setup comes pretty close to how cucumber does it, without all the cucumber-world craziness.

Some benefits that come with this approach:

  • faster spec runs for both suites
  • easy to separate out suites for CI
  • great for coverage reports
  • simple spec_helpers
  • separation of concerns via custom test modules

See the example configurations for more details.

monkey-patching Rails

I’ve been working a bit on a rails plugin for debugging html templates that we use at Shopify called partially_useful.

It’s a very simple helper that adds HTML-comments to the rendered source, so that you can inspect it easily in your browser’s developer toolbar. The comment hints look like this:

<-- start rendering 'some_partial' with locals '[:all, :assigned, :locals]'-->
<div class="hello">
    <div class="world">
<-- end rendering 'some_partial' with locals '[:all, :assigned, :locals]'-->

There are way more sophisticated plugins out there like xray-rails, but I prefer to have very simple tools that can be used without installing plugins or the like.

I used the plugin in various projects and ported it from Rails 3 to Rails 4, but it has never been more than a GIST on GitHub. Taking the time to actually convert it into a Railtie did not take long and allows everyone to use this plugin in their Rails projects.

All it does is intercepting the ActionView::PartialRenderer#render method, taking the return value of the call and wrapping it in HTML comments.

The tricky bit is how to inject this functionality into the original Rails code…

shoot yourself in the foot way

Just open up the ActionView::PartialRenderer class and overwrite the method!

While this might seem like the obvious way to do it, it makes everyones life worse, because it makes it much harder to find out where the f**** this new behavior is coming from…


The nicest solution is to use Module#prepend. It allows you to inject a Ruby module in the first position of the inheritance chain. By doing this, your new render-method will get called and you can just pass everything along to super aka the original method.

The big downsides here are that this is not compatible with Ruby 1.9 and JRuby.


This is a feature that Rails adds to Module and that allows you put another method in the call-chain by aliasing methods. I’m not a huge fan of it as I find the API rather confusing and it just works with Rails.

bare metal

If you include a Module that has a method with the same name as the method in the target class, the method of the Module will not get called when you invoke it on the class. This is because the methods of the class take precedence in the method-dispatch over those of ancestors in the inheritance chain (hence the Module#prepend). Because of that, you have to make way for the new method so that it can be invoked properly when you include a Module to override a method.

A way to do that is to use the Module#included callback to alter the class and alias the old method and remove the original afterwards

  def self.included(klass)
    klass.send :alias_method, :original_rails_render, :render
    klass.send :remove_method, :render


Meta-programming is hard, especially if you want to support multiple Ruby runtimes…

Debugging Rails Applications in Development

I’ve been spending a lot of time answering questions on Stack Overflow lately. From what I read, most of the questions come from unexperienced developers. It’s not easy to understand their questions because they often lack code examples, stack-traces or application logs. Because of that I keep repeating a lot of stuff in the comments or in my answers. I thought that it might be better to write everything down in a blogpost, so everyone has a chance to pick it up all at once.

The basics

When working with Ruby on Rails you will have to learn a lot of stuff to master debugging your own application. There are so many moving parts in a Rails app, it’s not just MVC…

  • Views (Partials, Layouts, Templating-Engines)
  • Controllers (Actions, Filter)
  • Models (Relations, AREL, Callbacks, Database-Systems)
  • Mailers
  • Routes (REST, HTTP-Verbs, Constraints)
  • Environments and Initializers
  • Caching (Redis, Memcached)
  • Assets (CSS, SASS, JavaScript, CoffeeScript, Pipelining)
  • Bundler and dependency management
  • Tests (RSpec, Capybara)
  • gems, plugins and engines used in the app

WOW, that is a LOT and I probably forgot some stuff…

Because of this overwhelming complexity, it is very important to know the basic tools that come with Rails and that help me in my everyday computering.

Using rake

Rake was intended as a Make for Ruby. It’s basically a build-tool that handles tasks. It has become the swiss-army-knife of Ruby and Rails. So make sure you know when it can be useful for you! The basic commands are rake -T to get a list of public commands and rake -D to get the full description of the tasks. If one of the commands fail, you can pass the --trace option to see what rake is doing under the hood and find possible error causes.

Here is a list of useful commands that I use when running into strange errors during development:

rake routes
rake middleware
rake assets:clobber
rake assets:clean
rake tmp:clear
rake log:clear

Reading stack-traces

It is happening to me all the time. The application spits out an error and I have no clue what is going on. Providing meaningful error messages is one of most neglected parts in writing maintainable software. On average, Ruby is very helpful in that regard, Rails is not! Nevertheless, you should always read the errors and stack-traces because they contain helpful information like the source file and the line number where an error was caused. It even provides information about the context, like the calling object and the call-stack when the error happened.

Let me give you an example exception:

undefined local variable or method `role' for #<Cucumber::Rails::World:0xc4722f8> (NameError)
  ./features/step_definitions/event_steps.rb:10:in `create_visitor'
  ./features/step_definitions/event_steps.rb:14:in `create_user'
  ./features/step_definitions/kid_steps.rb:107:in `/^I am exists as a parent$/'
  features/manage_kids.feature:11:in `And I am exists as a parent'

What I can see at a glance:

  • it’s about cucumber
  • we are in a step definition
  • the context object is of class Cucumber::Rails::World
  • there should be a role but it is not available
  • calling create_visitor caused this error
  • the source of create_visitor is in event_steps.rb on line 10

The source code that matches this error is this:

# event_steps.rb
def create_visitor
  @visitor ||= { 
    :email => "[email protected]",
    :password => "test123", 
    :password_confirmation => "test123", 
    :role => Role.find_by_name(role.to_s) # this is line 10

It is just an excerpt of the code, so it’s a good idea to add real line-numbers or an anchor so other people know where we are. In this example, this would not even be necessary, because role is only called once. Without knowing anything about the source, I can immediately see that the author wanted to use something that is not there.
So possible solutions to this might be to use @role or maybe @visitor.role or to have a method called role or pass it in as a parameter to that method. If the test has run successfully before doing any changes, the error was probably introduced by some changes you did and should be easy to find.
So always make sure your test suite passes before writing new code.

Side Note

Never throw away exception information unless there is a good reason! Swallowing exceptions causes a lot of pain for people that have to maintain the running application, so please at least log the error message when you rescue from something.

Reading code

One of the key skills for writing code is reading code in the first place. Whether it is code I wrote some time ago, code of my coworkers or library code. It’s super important to understand the code at hand and the code that my application is executing. Compared to other languages, where one has to deal with compiled sources, it’s incredibly easy to have a look at ruby sources. I often run bundle open some_gem to look at the source or when you are not using bundler run gem env and look at GEM PATHS where your gems are installed

gem env

RubyGems Environment:
  - RUBY VERSION: 2.0.0 (2013-06-27 patchlevel 247) [x86_64-darwin12.4.0]
     - /Users/paule/.rbenv/versions/2.0.0-p247/lib/ruby/gems/2.0.0

subl ~/.rbenv/versions/2.0.0-p247/lib/ruby/gems/2.0.0/gems/rails-4.0.0/

I also often use dash to get method documentation.

Debugging the running server

Rails coding is often CMD+R driven. I sit in front of the browser and reload the page to see if something happens… Unluckily it does not work the way I expected, so what to do next?

It’s in the logs stupid!

When I am working on a Ruby or Rails application i like to run stuff in iTerm2 with split views. One session for running spec, rails or the console and one session with the corresponding logs with tail -f log/development.log

Screen Shot 2013-10-16 at 10.22.00

Logs help with a lot of stuff and are a powerful tool to debug your running code. Things that can be extracted from the logs:

  • direct error information
    • error-messages
    • complete stack-traces
    • logged warnings or errors (attribute accessible warnings, deprecations)
  • context information
    • request parameters
    • request types (html, json, xhr…)
    • response codes
    • sql queries
    • rendered views and partials
    • callback informations

Since Rails introduced the asset pipeline, logs became pretty useless, because they were cluttered with asset calls. Disabling those logs does not need any ugly middleware monkey patches anymore because you can use the quiet_assets gem for this purpose!

One thing that I do to pimp my logs to be even more useful is to use the tagged logger that was introduced in Rails 3.2. It allows you to put even more context information into the log like the session-id and request-id:

# application.rb
config.log_tags = [
  lambda { |request| "#{request.uuid}"[0..15] },
  lambda { |request| "#{request.cookie_jar["_on_ruby_session"]}"[0..15] },

Quick inspects

There are a couple of “workflows” which I tend to use in my everyday debugging, starting with simply adding p some_object, puts some_object.inspect or logger.debug some_object calls randomly to the code. For view templates i use = debug(some_object).
This helps in about 50% of the error cases because it gives me enough context to find the problem quickly.

Another thing is putting a raise some_object.to_s into the code. This is especially helpful if I want to find out when and how some part of the code is executed. Callbacks are a good example where this is a nice shorthand method for debugging.

Insight tools

A running Rails server can provide a lot of useful information for debugging, especially if you curry it with the right helpers. Rails 4 already comes with some better error reporting and a route helper that can be accessed through navigating to an unknown route (thx ecki for the clarification). I use the /routes path for this purpose:

Screen Shot 2013-10-16 at 13.04.18

This functionality can be improved with a nice UI and a mini Rails console running in your browser if you add Better Errors and the Binding of Caller gem. These tools allow you to dive right into the error context and find out what might have went wrong. Combining this with raising my own errors gives me a lot of flexibility to quickly get to the point where I assume that something fishy is going on in the code.

Screen Shot 2013-10-16 at 13.02.46

When you are doing a lot of ActionMailer related stuff, you probably want to install the Letter Opener gem to develop and inspect your E-Mails.

The debugger

Having tools like Better Errors is super nice, but they are only suited for usage in the Browser. This is not always possible and I fall back to real debuggers that allow for moving around in the call-stack and inspecting objects at runtime.

The ruby-debug gem was the go-to-guy for a long time in Ruby land. It was a PITA to get this up and running in latest Ruby versions. That’s why I use the IRB replacement pry with a lot of extensions like pry-debugger or pry-nav. If you want to hook into a remote Rails process (ie. running rails via foreman) you can hook into it with pry-remote. Have a look at the Pry Railscast for more information.

Debugging through the console

The console is very important for me when writing new or changing existing code. I often create new finders and scopes in the console directly. A very important command in the console is reload!. It reloads all the code in the current session, similar to what happens when you hit CMD+R in the browser:

reload!; something_i_changed_in_the_editor.check_if_it_works

A thing that I find very helpful when stuck in a debugging session is the method.source_location functionality introduced in Ruby 1.9. It allows me to see where a method is defined:

=> ["/Users/paule/Documents/rails/on_ruby/app/models/user.rb", 39]

Use the force Luke

I like to use pry-rails as my default Rails Console. It enables me to browse source code, inspect objects and do a lot of other crazy stuff. Just type help in a pry session to see what commands are available. My favorite command is wtf? which shows the last raised exception and stack-trace.

Debugging through testing

I love test driven development! It is an everyday part of my programming routine. The only thing that I hate when doing TDD in Rails is the slow feedback loop. I don’t like using tools like spork or zeus as they introduce a lot of complexity and make debugging even harder.

So my approach to get away with minimal turnaround time is to start my new expectations by writing somthing like this:

describe User do
  it "does crazy stuff" do

This rspec expectation will just open a new pry session where I can start coding right away, exploring my test with direct feedback from executing the code I want to test. This eliminates all the iteration- and startup time when running red/green cycles. It is especially useful when I don’t know exactly how something should function in the first place…

Debugging capybara

The last pattern is super useful when writing acceptance tests in capybara! I always forget how to use capybara expectations and matchers, because I write only a few of those tests. This is mainly due to the test pyramid and me being a backend developer.

There are also a lot more moving parts in acceptance tests, especially when running JavaScript tests in a headless browser. It’s super useful when you can just check page.body or temper with X-PATH expressions directly in the pry session.

If there is some strange behavior during test execution, I just put a breakpoint somewhere in the test and call save_and_open_page or even better: print out current_url and open the running test instance directly in the browser!

Other helpful tools

The Rails ecosystem comes with a lot of tools for debugging, but it can be enhanced even further:

Rails Panel

If you are using Google Chrome like me, you can use the Rails Panel plugin in combination with the Meta Request gem to get a Rails Developer Console in your browser. Super sweet!

Screen Shot 2013-10-16 at 11.21.51


If I want to look into response headers or other request/response specific information, I use curl in addition to the Chrome Developer Tools:

curl -I "http://hamburg.onruby.dev:5000/"

HTTP/1.1 200 OK

It is even possible to use the “Copy as cURL” option in the Chrome Developer Tools to get all the parameters necessary to redo some request!


I use Navicat as a multi db frontend. It allows me to inspect what is going on in the database, check query results, indices and create data on the fly. Always have a good client for your data stores available!


I love git! It’s not the most self explanatory tool on the planet but it helps me so much when debugging applications. Just one example here is using git bisect. It executes a command for a range of commits, so that it is possible to find out which commit introduced a problem I am trying to debug.

Resources worth reading

Here are some websites that I keep referring to in a lot of my answers on stackoverflow. Go ahead and check all of them, really, I mean it!