Paperdragon is another gem for image processing in Ruby. It has a very explicit DSL that gives you full control about what is going on when.

Now, please don’t stop reading. I know exactly what you’re thinking: “We got Paperclip, we got CarrierWave, and there’s also Dragonfly. Why the hell another gem?”.

Alternative To What?

First of all: Paperdragon uses Dragonfly under the hood. It’s a great gem. However, I couldn’t get the model layer to do what I want.

Then, Paperclip is extremely helpful. This gem is perfect if you don’t need any fine tuning. It allows you to quickly declare formats, cropping, etc. with a nice configuration DSL. What then happens when uploading is not your business.

CarrierWave almost does what I wanted. But still, I was missing the ability to take control myself because I’m a control freak.

Also, all the other gems hook into ActiveRecord’s callbacks. I think the concept of AR’s callbacks is one of the worst things I’ve seen with Rails. Not that those gems use callbacks in the wrong way – the way other people use callbacks makes me mad.

Take Control Of Your Images!

Ok control freaks, here we go. Let’s look at how Paperdragon does it.

class User < ActiveRecord::Base
  include Paperdragon::Model
 
  processable :image
  serialize :image_meta_data
end

Oh, paperdragon doesn’t know anything about ActiveRecord or whatever ORM you use. You could use paperdragon in a PORO and it wouldn’t know it.

By calling processable paperdragon will add a reader method #image to your model that allows accessing the processing API – nothing else happens!

A second requirement is to provide accessors for a field named image_meta_data. It uses this field to store, well, meta data like the images’ paths as a hash. I use serialize from ActiveRecord. And of course, I added a TEXT column with the same name in my users table.

We’ll see how these two play together in a minute.

Uploading

Now, what’s happening when you upload an image?

Processing and storing an uploaded image is an explicit step – you have to code it! That’s right. You wanted control, now you got it.

This code usually goes to a separate class or an Operation in Trailblazer, don’t leave it in the controller if you don’t have to.

def create
  file = params.delete(:image)
  user = User.create(params) # this is your code.
 
  # upload code:
  user.image(file) do |v|
    v.process!(:original)                            
    v.process!(:thumb)   { |job| job.thumb!("75x75#") } 
    v.process!(:public)  { |job| job.watermark! } 
  end
 
  user.save
end

Whoooa, slow down. What’s all that?

file = params.delete(:image)
user = User.create(params) # this is your code.

Well, the first lines is Rails code: We simply create a user object. This is where paperclip and friends would hook in an start their magic. Paperdragon hates magic, that’s why I delete the uploaded file from params.

Explicit Processing.

After that setup, we finally get to process images.

user.image(file) do |v|
  v.process!(:original)                            
  v.process!(:thumb)   { |job| job.thumb!("75x75#") } 
  v.process!(:public)  { |job| job.watermark! } 
end

Do I really need to explain that? Ok.

I use the #image method we talked about earlier and pass the uploaded file into it.

In the block, I can create different versions of the image. It is an convention to name the unprocessed file :original – everything else is up to you!

The job objects are actually Dragonfly::Job instances and give you the entire API for processing, converting, cropping, resizing, analysing images. It’s insane and beautiful!

An important thing here is: once you call process! it happens. It’s your decision whether the entire block goes to a background job, if you want to crop the thumb right away, do the rest later, and so on.

Make It Persistent!

After the block is run, and you hopefully created some images, the last line seems odd.

user.save

This is to save the metadata! Remember, we have that field image_meta_data in the User model. And that very field gets populated with data when processing has finished.

Let’s check out this field’s content before we call #save and after the processing block.

user.image(file) do |v|
  v.process! #...
end
 
user.image_meta_data 
#=> {original: {uid:   "original-logo.jpg", 
#               width: 240, height: 800},
#    thumb:    {uid:   "thumb-logo.jpg", 
#               width: 48, height: 48},
#   ..and so on..

After processing, paperclip automatically updates this field, so it can find the images later.

This is a fundamentally different concept to paperclip, which uses 5 or more columns of the model to generate the address at run-time.

While this might save some disk space, it is a very dangerous concept: If any of these values change by only one byte, you’re gonna lose your image since the computed address will be wrong. Paperdragon goes the explicit way and saves the address in the metadata hash.

Rendering Images!

All this work is rewarded when rendering a beautifully cropped thumbnail.

user.image[:thumb].url

That’s ready to be used in an #img_tag. Not too hard, right?

Reprocessing.

This was uploading. Paperdragon also makes it extremely explicitly simple to reprocess image version. For instance, let’s assume the thumb had been re-cropped via the UI.

user.image do |v|
  v.reprocess!(:thumb, Time.now) do |job| 
    job.thumb!("#{params[:w]}x#{params[:h]}#") 
  end
end

Reprocessing has a similar semantic. Here, you don’t need to pass in a file as we already got it stored. Furthermore, I call #reprocess! which requires a second parameter: a fingerprint!

That’s right, paperdragon automatically adds a fingerprint to the file name when reprocessing (if you want it).

Ehm, And.. What Else?

I am getting bored as I am replicating paperdragon’s README which will tell you about all the other great features such as renaming images, deleting, S3 support, custom UIDs, paperclip compatibility, and more.

Check It Out!

Paperdragon‘s API requires you to do all that work. In turn, it gives you control.

We are very happy with it, our site literally processes thousands of photos every day and paperdragon gives us exactly the amount of control we need, along with an abstraction that is not painful, yet.

BTW: The best Origami paperdragon image in the comments wins a free installation!

The new Reform 1.1 release brings several nice improvements and lots of fixes to the form object gem. This release is just a transitional one, the 2.0 version is gonna move huge chunks of code into a separate gem. Let me talk about this in a minute.

Non-Intrusive Validation.

Reform comes with a mechanism to populate your object graph by deserialising the incoming form data to objects.

class AlbumForm < Reform::Form
  collection :songs, populate_if_emtpy: Song do
    property :title
  end
end

This would create Song instances where they were missing in the album.

AlbumForm.new(album).validate(
  "songs" => [
    {"title": "Eat Your Words"}
  ]
)

In former versions of Reform, just by calling #validate Reform would already attach those new songs to the album model – by pushing them via songs[]=.

This created confusion. And is different now. The built-in populators do not touch the model at all. This only happens when saving or syncing the form.

Coercion Simplified.

Reform allows you to use virtus coercion.

class AlbumForm < Reform::Form
  property :released_at, type: DateTime
end

From 1.1 onwards, coercion only happens in #validate – any other API method will not trigger coercion. This makes the workflow predictable as we had problems with coercion happening where it shouldn’t.

Manual Coercion.

You can also implement your own filtering by overriding the setter for a property.

class AlbumForm < Reform::Form
  property :released_at
 
  def released_at=(v)
    super DateTime.parse(v)
  end
end

Note that you can use super to call the original setter but still provide your own code for filtering or sanitising or whatever fun stuff you’re after.

Overriding In Nested Forms.

This brings me to the next improvement. The above example only worked for top-level properties. That sucked and is fixed now, allowing you stuff as follows.

class AlbumForm < Reform::Form
  collection :songs do
    property :written_at
 
    def written_at=(v)
      super DateTime.parse(v)
    end
  end
end

Methods defined in nested forms actually extend that nested form class – as it should be!

Forms In Modules.

This is my favourite improvement as it maximises the reusability of forms: you can now define forms along with properties, validations and accessors/helpers in modules!

module SongsForm
  include Reform::Form::Module
 
  collection :songs
    property :title
    validates :title,  presence: true
  end
end

This module can now be included into real forms.

class AlbumForm < Reform::Form
  property :title
 
  include SongsForm
end

That should help to keep forms DRY, as it is a common pattern to have several different forms for the same model with lots of shared functionality.

Inheritance Improved.

Reform 1.1 uses representable 2.0 internally for all kinds of mappings and declarations. This actually allows you to “fine-tune” forms and overriding or extending properties that were inherited.

class AlbumForm < Reform::Form
  property :title
 
  include SongsForm
 
  collection :songs, inherit: true do
    property :artist
  end
end

This will extend the existing, inherited songs form and add the artist property. Read the docs for in-depth information about this or sign up for my upcoming book which discusses this pattern in detail.

Validations From Models.

While Reform/Trailblazer encourages you to have empty models that only configure your persistence layer, Reform now allows copying validations from models. This way you can quickly set up forms without having to write redundant validations.

class SongForm < Reform::Form
  property :title
 
  extend ActiveModel::ModelValidations
  copy_validations_from Song
end

Thanks to Cameron Martin for his excellent work.

Deserialise JSON.

A simple change in Reform now allows forms to deserialise JSON, XML and YAML besides the original support for hashes. While this might sound weird, this little improvement actually allows forms to become part of your HTTP API.

This is an integral part of Trailblazer: Here, every domain action is encapsulated in a so called “Operation” which internally uses a form object to deserialise incoming data, setup the object graph and validate the application state.

By making forms do JSON and friends, too, they can be used for normal web forms, console/model API and HTTP APIs, which is pretty awesome.

Again, this is all in my book but you can have a sneak peek in the Traiblazer example app gemgem – thanks to @GoGoGarrett for that name, BTW :)

class AlbumForm < Reform::Form
  representer_class.send :include, Representable::JSON
 
  def deserialize_method
    :from_json
  end
 
  property :title
 
  include SongsForm
 
  collection :songs, inherit: true do
    property :artist
  end
end

This rather clumsy extension (to be improved!) allows to call #validate with JSON.

AlbumForm.new(album).
  validate('"songs": [{"title": "Eat ..')

The API is not yet finalised, I just wanted to give you an out-sight on where this is going.

Reform 2.0 coming.

Speaking of out-sights: Reform 2.0 is already on its way. A major improvement here will be to move all the heavy model lifting (populating, syncing, saving, etc) into disposable which will be a model abstraction layer in Trailblazer (or without Trb).

Use it, and let me know what you think!

Is it just the crude title or is it true…? What makes Helpers Are Shit my most popular post ever? I felt like I have to write a follow-up now that Cells view models are replacing more and more helpers in many production apps out there.

Right, the last post is from 2011, that is old. What’s bad about this is that the write-up is still 100% accurate about the mess helpers and partials create in Rails apps. Nothing has changed in the Rails view layers for many years.

Helpers Are Shit.

The way helpers are being used in Rails encourages users to write “script-like” code using global variables and procedural functions in an environment that calls itself “object-oriented”.

Whenever I am refactoring complex Rails apps, the view layer is the worst part with hundreds of redundant helper methods accessing instance variables, calling other helpers, passing around models and options, and rendering random partials from a global directory.

Again, this mess is a result from the lack of a view abstraction layer in Rails: Helper invocations and partial rendering all happens in one monolithic ActionView instance – this is failure by design.

View Models.

Cells “view models” allow you to replace helpers entirely and forever. Instead of a global pile of mud you encapsulate parts of your view into a class. A class that can render templates, can inherit or mixin other methods, allows view inheritance, if needed.

This is faster than what you had before: In a view model, no data is copied between controller and view – the view model is the view context. Let me demonstrate that.

I will use the term “view model” and “cell” interchangeably (yepp, I had to look up that word).

Encapsulation Via Classes.

Encapsulating view logic happens in cell classes.

class CommentCell < Cell::ViewModel
  def show
    render
  end
end

Think of a cell as you think of a Rails controller (without all the HTTP overhead, of course). Per design, a cell has one public method #show. This is a convention. You can expose as many methods as you like from that cell. More on that later.

Where Is The Model?

I’ll walk you through that now. First, we need to render that cell somewhere in our app.

.sidebar
  = cell(:comment, Comment.last).show

Suppose this is somewhere in an application layout (it could be any view or in a controller). This will instantiate a CommentCell and execute the show method. This is a bit like calling a helper.

Note that I pass in a Comment model instance as the 2nd argument. This is the cell’s “model”, making the former a genuine view model™.

Encapsulated Rendering.

Let’s have a look again at the cell’s show method.

class CommentCell < Cell::ViewModel
  def show
    render
  end
end

Once the show method is called, it hits render. That will simply invoke the cell’s rendering as known from a Rails controller. With one exception: the view is located in a separate directory. Here’s how a cell directory looks.

app
├── cells
│   ├── comment_cell.rb
│   ├── comment
│   │   ├── show.haml

This is the old layout soon to be superceded by the Trailblazer-style “concept layout”. That doesn’t matter right now.

Good Old Views.

Now, let me show you how that show.haml could look like.

%h1 Comment
 
= model.body
By 
= link_to model.author.name, model.author

Two things.

  1. The cell’s model (the comment itself) is accessible via the #model method. Wow.
  2. You can still use helpers in a view. In this example, I use link_to.

No Code In My View!

We’ve learned that logic in views is bad. And this is exactly where view models start to be fun to work with.

class CommentCell < Cell::ViewModel
  def show
    render
  end
 
private
 
  def body
    model.body
  end
end

Remember: as the view model is the view context itself, any method called in the view will be simply called on the view model. That reduces complexity in the view a bit.

%h1 Comment
 
= body
By 
= link_to model.author.name, model.author

Embracing Helpers.

Still hating the link line. Why not move that into the cell, too?

class CommentCell < Cell::ViewModel
  def show
    render
  end
 
private
 
  def body
    model.body
  end
 
  def author_link
    link_to model.author.name, model.author
  end
end

Now, what? We can call helpers in the view model? Seerriously?

Well, I never said that helpers are a bad thing. They’re just shit when used to “encapsulate”. I personally love link_to, sanitize and form_for (sometimes). They save me a lot of work. I just don’t like the fact they all play together in a big monolithic class.

Here, the link_to can’t mess up anything as it is running in a limited scope – the cell instance.

Logicless Views.

The second refactoring reduces our view to a dumb template, as it should be.

%h1 Comment
 
= body
By 
= author_link

I love it already. What’s next?

Simple Decorating.

The task of delegating methods to the model is so tedious that it is built into cells. We can get rid of the body method.

class CommentCell < Cell::ViewModel
  property :body
  property :author
 
  def show
    render
  end
 
private
 
  def author_link
    link_to author.name, author
  end
end

Declaring body and author as propertys automatically delegates to the model, making it a no-brainer. It also states your dependencies to the model in a very clear way. Hooray to explicit code!

Object-Oriented Helpers.

What if we had to customise the body method, e.g. apply a markdown filter on the content?

class CommentCell < Cell::ViewModel
  include MarkdownHelper  
 
  property :body
  # ...
 
private
 
  def body
    markdown super
  end
end

First, I include the magic markdown helper to import the markdown method. Secondly, I can override the body method and call super to access the original property. Object-orientation back in the view land!

More Helpers!

A cell is not limited to one public method. It’s good to have only one but sometimes it comes in handy to not having to introduce a new class for every “helper”.

class CommentCell < Cell::ViewModel
  # ...
 
  def show
    render
  end
 
  def related
    render
  end
 
private
  # ...

Here, I add a second public method related. This will render another view, the related.haml. Dump it into the cell’s directory and you’re good to go.

app
├── cells
│   ├── comment_cell.rb
│   ├── comment
│   │   ├── show.haml
│   │   ├── related.haml

You can now use this “helper” anywhere you want.

= cell(:comment, Comment.last).related

Isn’t that nice? We encapsulated a huge part of a mess into a clean, reusable component. This feels good.

Don’t Stop Me Now!

I want to talk more about the benefits of cells, like view inheritance, testability, reusing components, hooking them directly to routes, sharing decorators between cells and other layers, but.. I’m writing this blog post at work and feel like I should stop now.

And, did you know? Recent surveys have concluded that 79.3% of all cells users did not regret their choice and can’t do without cells anymore.

Let me know if you have any questions.

Kaminari-Cells Is Ready!

The kaminari gem is a project to simplify pagination – often used in Rails apps. Cells provides view components for Rails. Those two just got married and their child is called kaminari-cells. Yay!!!

Kami..what?

Kaminari adds pagination logic to finders – it works with all kinds of ORMs, e.g. in ActiveRecord. It also gives us a bunch of helpers to render pagination links.

It is extremely popular as it doesn’t pollute objects with pagination logic.

Typically, a controller, an operation or a model will accumulate models to display.

@users = User.order(:name).page params[:page]

Later, in a view, after rendering the rows itself you want to display a link to jump to the next or previous page.

= paginate @users

A really simple and cool thing.

Pagination In Cells.

As kaminari uses global partials to render the pagination links, we had to make it work with cells, which usually does not use global partials. Thanks to the fine kaminari team, this was implemented, tested and merged within hours.

All you need to do to make the paginate helper work in a cell view is add the gem to your Gemfile.

gem "kaminari-cells"

And then extend the class.

class CommentsCell < Cell::Rails
  include Kaminari::Cells

This works for both conventional cells and view models.

Representable 2.0 comes with a bunch of cool new features. I’d like to thank the community for coming up with ideas, working with me on features and trying out new stuff. Speaking of new stuff – have you seen my favicon? It’s new, and I’m a bit proud of it.

Let’s quickly go through the changes.

Changes?

Well, if you’ve been a cautious person and were only using representable’s public API, nothing will break! Even when you’re one of the “power users”, you shouldn’t have too much trouble getting up-to-date, again.

Partial Inheritance.

Inheriting properties from other representer has been working fine for a long time, either by including modules into other modules or decorator classes, or by deriving decorators.

It is now possible to partially override inherited properties.

Suppose we have the following base representer (this could be a module or a class, doesn’t matter). For simplicity, I leave away the noisy includes.

module SongRepresenter
  property :title, as: :Title
 
  property :band do
    property :name
  end
end

Very simple. Now imagine a HitRepresenter needed to inherit all the above plus add a property to the inline band block. This is where :inherit enters the stage.

module HitRepresenter
  include SongRepresenter
 
  property :band, inherit: true do
    property :location
  end

This will add the location property to the band’s representer without destroying the original representer.

You can also use this directive with scalar properties that don’t have a block. This will add the options you provide.

property :title, inherit: true, type: String

The coercion option :type will be added to the existing options, preserving :as and whatever else you specified.

Having this new inheritance “fine tuning” makes representable really powerful and maximises reusability of representers across your project.

Modules In Decorators.

One thing I found not working and fixed in representable 2.0 was when including modules with inline representers into decorators – this works all fine now.

class SongDecorator
  include SongRepresenter
 
  property :label
end

This will work as expected and inherit all properties from SongRepresenter into the decorator – and add the label.

Automatic Collections.

Many users have been asking for this for a long time, and @timoschilling was the power user who submitted a draft more than a year ago! Sorry for the delay. I was busy drinking Australian Beer™.

Representable comes with a feature called lonely collection which allows you to represent an array of objects.

module SongsRepresenter
  include Representable::JSON::Collection
 
  items extend: SongRepresenter, class: Song
end

As you can see, every item will be represented (rendered or parsed) with the specified SongRepresenter (which could also be inline, BTW).

[song, song].extend(SongsRepresenter).to_json

Now, this is explicit and needs to be defined for every collection. I personally am a big fan of explicit code, but lots of users don’t want that boilerplate code.

That’s why you can now use ::for_collection to let representable create this lovely lonely collection for you.

module SongRepresenter
  property :title
end

Assuming you use this simple singular representer to render and parse songs, here’s how you’d render collections with it.

[song, song].extend(SongRepresenter.for_collection).
  to_json

Note how I use the singular representer! Representable will internally create a lonely collection representer and render the collection.

For parsing, it needs to know a bit know, e.g. the class to deserialize the songs to. You need to specify that in the singular representer, again.

module SongRepresenter
  property :title
 
  collection_representer class: Song
end

::collection_representer lets you configure the – surprise! – collection representer. Everything you pass to this method will be forwarded to the ::items call when creating the collection representer.

[].extend(SongRepresenter.for_collection).
  from_json("[{title: ..]")

Automaticer Collections.

If that’s still too much code for you, go ::represent fo’ real!!

SongRepresenter.represent(song).to_json       #=> 1
SongRepresenter.represent([song, ..]).to_json #=> n

This method figures out if it’s working with an array or a singular object. It’s a matter of days until this will make its way into Roar and roar-rails and simplify your user code there.

Filters!

If you ever needed to massage a string before it gets rendered, or a fragment after it got parsed… you’re lucky. Representable now gives you :render_filter and :parse_filter.

property :title, render_filter: 
  lambda { |value, doc, *args| value.markdown }

This is run right before the fragment is inserted into the document.

property :title, parse_filter: 
  lambda { |value, doc, *args| Markdown.parse(value) }

And this lambda is invoked just after the fragment got picked from the incoming document when parsing.

In case you need multiple filters: those two options are implemented using Representable::Pipeline, you can add lambdas later, the results will be passed on from filter to filter.

Apparently, this feature already made its way into grape-roar.

Ditch Lambdas For Callable.

I always disliked the verbose, clumsy lambda syntax in my properties. Representable 2.0 lets you specify “callable” objects in favour of lambdas.

property :title, render_filter: Sanitizer.new

Now, how does it know that Sanitizer instance is invokable? Here’s the trick.

class Sanitizer
  include Uber::Callable
 
  def call(representer, fragment, doc, *args)
    fragment.sanitize
  end
end

All the object needs is a #call method that gets – admittedly – a bunch of parameters. In that, you can do whatever you need. Including Uber::Callable marks this instance as a callable one – no magic here.

I Need More Data!

Another new option helps you retrieving all the possible information you might need in your lambdas (or, cooler, callable objects). Let’s say you need to know the property options, whether :extend is set, or not. :pass_options can help.

property :title, 
  pass_options: true,
  parse_filter: 
    lambda { |value, doc, options|
      options.binding[:extend]
      options.user_options
      options.represented
    }

The options object keeps references to all stakeholder objects involved at that point of representing. This :pass_options is definitely an advanced option, but some peeps might find it helpful. I use it all across my gems.

Enjoy your day and keep smiling!

Organic Testing?

Either I’m missing something or the current test frameworks [1] don’t support what I call an “organic test”.

[1] …which are all excellent and have helped me sooo much in the past, present and future!

The fact that I prefer MiniTest over Rspec doesn’t matter in this write-up, as I couldn’t find a way to do what I want in either framework.

What I Do.

I constantly find myself writing tests like this.

it do
  song = Song.new(:title => "Dragonfly")
 
  song.size.must_equal 1
  song.title.must_equal "Dragonfly"
  Something.else.must_equal 2
end

Note that the actual tested code needs to be run before the assertions, but not before every assertion. It’s important to me to run it once, have the same result for every assertion and save time. The result is treated as immutable.

What I Should Do.

The three assertions are what I’d love to have in it {} blocks to have a better overview how many assertions I broke. So, following “the rules” I’d end up with the following ugly code.

describe do
  before { @res = Song.new(:title => "Dragonfly") }
  let(:song) { @res }
 
  it { song.must_equal 1 }
  it { song.title.must_equal "Dragonfly" }
  it { Something.else.must_equal 2 }
end

This just feels wrong. I hate before blocks in general, and usually, I want to set up more variables so I’d have several let lines. It’s not readable.

I can’t use subject or let or let! . As you have already seen, the third line doesn’t call subject and relies on the test state after before.

What I Want.

My idea is to extend MiniTest/Rspec to support this syntax.

spec do
  song  = Song.new(:title => "Dragonfly")
  title = Song.find(song.id).title
 
  it { song.size.must_equal 1 }
  it { title.must_equal "Dragonfly" }
  it { Something.else.must_equal 2 }
end

That is super straight-forward: Setup your variables, and then test them with isolated it blocks. How can I do that with existing frameworks?

Hello. I am a gem author and I got a problem. It’s called versioning.

Yes, you’re right. Versioning. It’s the third big problem of computer science, after expiring caches and naming things.

My gems are all under active development. For some strange reasons, I am avoiding major releases as people might be expecting a major new break-through feature, but all I changed was a minor detail that will affect 1% of all users.

I do minor version bumps instead and try to deprecate as much as possible. Apparently, this is not enough as there’s always angry users with broken builds that “didn’t expect that change with a minor release”.

What Is Semantic Versioning?

The idea of semantic versioning is very clever, and I’m happy there’s something close to a standard.

A semantic version is a string like 1.0.3, the three segments are called major, minor and patch version. You increment major when you made an “incompatible change”, meaning that the new gem version might break your old code. The minor is bumped when the change is “backward-compatible”, so your code is guaranteed to work with the updated gem. Patch is used when incorporating bug fixes and feature additions.

Semantic Versioning And Gems.

The problem arises when you’re actively working on your gems – which I happen to do! Actively in terms of adding features, fixing bugs and constantly refactoring older parts of code. When I refactor stuff I often find better, cleaner ways to achieve something and not uncommonly the restructuring comes with a “minor” behaviour change of the code.

Here are two examples to illustrate my dilemma.

A while ago I started moving common code I use in all my gems into the uber gem. For instance, in representable I allow “dynamic options”.

property :title, if: Rails.env == "production"
property :title, if: lambda { policy.ok? }

That’s a common pattern found in many gems. The :if (or any other option) allows providing a string, a lambda, a symbol, etc and evaluates that at run-time.

Evaluating those options is now handled by uber – which saves me a lot of work. In uber, a dynamic option lambda always receives arguments (at this point it is totally irrelevant what options).

Breaking Things.

So, after updating from representable 1.7.8 to 1.8.0, the above code would break as the old code does not accept arguments.

The fix is to change code as follows.

property :title, if: lambda { |*| policy.ok? }

It’s a really really simple fix. It basically says “I know there might be options passed into my block but I don’t care”.

I didn’t deprecate the former behaviour, but that’s another issue. I knew this was gonna break “some” people’s code. I announced that in the CHANGES, blogged about it, and supported wherever I could.

I didn’t deprecate it as the new solution is way cleaner and consistent – all options receive arguments, are evaluated using the same mechanism, and so on.

Not deprecating this change was stupid. However, deprecating things is pain and not every development team has a horde of willing programmers as in Rails core to work on deprecations.

Most users just updated their :if blocks to receive args and moved on. Some users complained – legitimately – that they were expecting a major bump.

Minor Details.

Another example, also in representable, is when I changed the way inline representers are created. This is a completely internal change.

class SongRepresenter < Representable::Decorator
  property :title
  property :label do
    property :manager
  end
end

Again, the details here are irrelevant. Look at that block.

property do .. end

That’s what we call an “inline representer”. What happens behind the scenes is a new decorator class gets created for that nested block.

Until today, that new class was inherited from SongRepresenter. This is wrong as this might lead to unexpected behaviour in the inline representer. In the new version, that new decorator would be derived from Representable::Decorator.

And, right – that change is so internal that 99% of the users won’t even notice that change because nothing changes or breaks for them.

However, 1% of your users, I call them “power users”, do amazing stuff with your gem – stuff you didn’t even think of when designing the framework.

Their code might break with that update. They will complain and I have to lower my head in shame and admit that I didn’t properly version my shit.

What makes me frustrated here is that you simply cannot deprecate it – there’s no way to find out if a users relies on the old superclass for the inline representer. It’s a dilemma.

Semantic Versioning – Done Right.

The solution I suggest is to add a fourth segment to the semantic version and shift its meanings down one level. That would mean 1.2.0.1 to 1.3.0.0 is not backward-compatible. I find this a stupid idea and I know you hate it, too.

That’s why the only way to keep my beloved users happy is to do semantic versioning right. I have to consistently release major versions whenever I change behaviour without deprecating it.

This would lead to fast growing major numbers, e.g. 14.1.0 or something like that. I am not sure about the acceptance in the Ruby community for that.

To me, it feels strange to see those version numbers. Others, like my friend Ricardo, find it totally ok. Ryan refers to Chrome which is currently at v35.

It appears that semantic versioning was designed to have big major numbers – how would you follow an innovative path for development otherwise?

What’s your thought on that? Fast growing majors? Catch-all deprecations? No changes at all???

UPDATE: The ~> Operator

Thanks for all the twitter responses (and comments)! @bhuga pointed out that fast-growing major numbers make it (almost) impossible to define a dependency using the ~> operator in other gems. The “eating bacon” or “sperm” operator only works with minor and patch level and allows you to lock the dependency to particular minor and patch version ranges.

I didn’t even think of that! As you can see – it’s a real dilemma!

Today’s a fantastic day.

Not only has it been nice and sunny so far, also did I release Cells 3.11! It is the last minor release before Cells 4.0, which will finally and forever get rid of the stinky ActionController dependency that has sometimes made our life painful. In 4.0, the new view model will become the default “dialect” for cells.

Anyway, back to 3.11. It got two new features that I personally started loving. You can now bundle assets into your cell’s directory (JS, CSS, images, fonts, whatever) making a cell a completely self-contained MVC component for Rails.

The second addition is purely structural: Cell::Concept introduces a new file layout for cells following the Trailblazer architecture. This new layout feels more natural, is easier to understand and allows cleaner encapsulation.

Packaging Assets.

It often makes sense to package JavaScript and CSS that belongs to a logical part of your page into the cell that implements it. We used to have those assets in global directories and it just felt wrong.

You may now push assets into the assets/ directory within the cell.

app
├── cells
│   ├── comment_cell.rb
│   ├── comment
│   │   ├── show.haml
│   │   ├── assets
│   │   │   ├── comment.js
│   │   │   ├── comment.css

How cool is that? A cell can now ship with its own assets, making it a hundred times easier to find related code, views, and assets. Your designers are gonna love you.

Hooking Into The Pipeline.

In order to use the assets in the global assets pipeline, two steps are necessary.

First, you need to configure the Rails app to find assets from the cell.

Gemgem::Application.configure do
  # ...
  config.cells.with_assets = %w(comment)
end

The with_assets directive allows to register cells that contain assets.

Second, you need to include the files into the actual asset files. In app/assets/application.js, you have to add the cell assets manually.

//=# require comment

Same goes into app/assets/application.css.sass.

@import 'comment';

I know it feels a bit clumsy, but it actually works great and if you have a better idea please let us know!

When compiling the global asset, the assets from your cell are now included.

Think In Concepts.

In the process of implementing the Trailblazer architectural style in Rails, the new Concept cell plays a major role. It allows a completely self-contained file layout. Here’s how that looks.

app
├── cells
│   ├── comment
│   │   ├── cell.rb
│   │   ├── views
│   │   │   ├── show.haml
│   │   │   ├── author.haml
│   │   ├── assets
│   │   │   ├── comment.js
│   │   │   ├── comment.css

See how all relevant files are under the comment/ directory? Views got their dedicated directory, and the actual cell code goes into cell.rb.

This slightly changes the way a cell looks.

# app/cells/comment/cell.rb
 
class Comment::Cell < Cell::Concept
  def show
    render
  end
end

A concept cell is always a view model. I’ll blog about the latter in a separate post. Apart from the slightly different name (see discussion below) everything else remains the same.

A New Helper.

Rendering (or just instantiating) a concept cell works with the new concept helper.

= concept("comment/cell", comment).call

This is exactly the same syntax as found with view models.

One cool new feature comes with that, too! You can also render collections of cells easily.

= concept("comment/cell", collection: Comments.all)

This helper is available in controllers, views and in the cell itself (for nested setups).

An in-depth discussion how to structure cells will be in the Trailblazer book.

Why The New Trailblazer Layout?

Trailblazer is all about structuring – an essential element of software development that Rails has failed to establish.

In Trailblazer, the Rails app is structured by concepts. A concept is usually a domain concern like comments, galleries, carts, and so on. A concept not only contains the cell, but also forms, domain objects (“twin”), operations and more. It has proven to be more intuitiv to structure code by concepts and not by controller, view and model.

The cell is still a fully self-contained component of the concept and can be moved, removed or changed without breaking the app.

More To Come.

I’m lucky to have a great team of developers and we started to deploy several concept cells to production. It just feels so much better and natural. Give it a go!

During the last months I had a few controversial chats about the “Single Responsibility Principle” (SRP), which is a concept in object-oriented programming for better encapsulation. Interestingly, the same conversation flamed up again and again when discussing Reform’s validate method.

Since that “validate” method does a bunch of things I was accused of exposing “a method that breaks SRP”.

What Is Not SRP?

A Reform form object comes with a handful of public methods, only. Their names are ::new, #validate, #errors, and #save. There are a couple more but that’s not relevant now. As their names are pretty self-explaining let me briefly talk about #validate.

Here’s how you use this obscure method.

result = form.validate(params)

So, what validate does is it first populates the form’s internal attributes with the incoming params. It then runs the defined validations in that form instance and returns the result.

Several people complained that this is not a good API as it breaks SRP – the validate method was “doing too much”.

I don’t really know if SRP only applies to classes but I can say one thing for sure: SRP can in no way be used with methods. If you say “this method breaks single responsiblity” you are talking about private concerns within a class.

You’re right, because it’s a good thing to break up logic into small methods. But you’re wrong, because you’re talking about the private method stack and not the public API of a class.

In my understanding, when talking about SRP you talk about classes.

What Is SRP?

I had this eye-opening moment in a brillant keynote by Uncle Bob at Lonestar RubyConf a few years back: An SRP’ed class is reflected by having exactly one public method.

Having this pretty simple rule, I admit that Reform is not SRP. To have a clean architecture, I should split Reform into one class per public method: Reform::Setup, Reform::Validate, and so on.

form = Reform::Setup.new(model).call
result = Reform::Validate(form).call(params)

Each class would only expose the #call method, in an SRP setup there’s no need to name the only public method, the class name tells you what’s gonna happen.

Of course, this is super clumsy and no one wants to work with a single responsible “API”. :D

As a side note, Reform does exactly that behind it’s manly back – it provides you all the necessary methods via one instance, then orchestrates to separate objects. You don’t need to know how it works as a user.

About API Design.

I have no clue where it comes from, nevertheless, exposing as many methods as possible to your class’ user seems to be “OK” or even “cool”, coming from Rails where an unconfigured ActiveRecord model offers you 284 public methods right away.

During +10 years of designing open-source frameworks I realised that the more public methods I allow my users to call the more work it gets to change my framework’s API later. Deprecating public methods is a pain in the ass.

Coming back to Reform, people suggested to split #validate into two public methods: One to populate (or “fill out”) the form instance, one to actually validate it afterwards.

The word “after” indicates only one of the problems you introduce by extending the API:

  1. Users will fuck it up. They will call #validate without calling #fill_out, then ask why validate doesn’t validate and then someone else will reply that they forgot to call #fill_out before.
  2. They will call #validate, then #fill_out – in the wrong order.
  3. Reform is a form object – there simply is no case where you wanna fill out a form but then leave it unvalidated.

I decided to leave the validate method as it is and I do not regret it. Acceptance for this rebelious method increased after improving its documentation.

Sum Up.

Don’t use SRP when talking about methods. It’s a concept to be used with classes that expose a single public method.

The more methods you expose, the more things can go wrong due to wrong order, not calling a method or general confusion. Don’t make methods public because they “could be helpful”. A good API has a limited set of methods, only. If people ask for more, think about moving it to a separate class.

Applying SRP to workflows and generally to objects in (Rails) app, and orchestrating those, is one of the numerous interesting topics discussed in my upcoming book. Sign up for the mailing list!

Dear friends – Reform 1.0 is out. It took a while, and a lot of work went into thinking about changes and if they make sense. Not much of the public API has changed, which is a good sign. Internally, Reform has become simpler as I learned what Reform actually is: a validation concept with additional logic for UI and workflows.

The public API is now limited to a handful of methods with well-defined semantics. Tons of “discrepancies” were fixed by simplifying internals.

We also introduce Reform::Contract which is an exiting concept to decouple validations entirely from your models. Even if you’re not interested in the form part of Reform, make sure to check out contracts.

A form class still looks the same.

class AlbumForm < Reform::Form
  property :title
  validates :title, length: {minimum: 9}
 
  collection :songs do
    property :title
    validates :title, presence: true
  end
 
  validates :songs, length: {minimum: 2}
end

You gotta love that intuitive DSL – it has been copied in several other form gems already, so it must be good!

Unlimited Nesting.

I’m not sure if I like the fact but Reform can now do as many nestings as your crazy models need. In earlier versions there were problems that models in the 3rd layer and more didn’t get validated. Not anymore. Go nuts.

Validations Against Nested Models.

In older versions it was a bit of a pain to validate, say, the minimum amount of nested Songs. This is all simplified now in Reform and as always, the simpler the better. Validations like the following just work now.

collection :songs do
  property :title
  validates :title, presence: true
end
 
validates :songs, length: {minimum: 2}

The validation will fail if there’s less than two Song objects in the collection.

Automatic Population.

A big show-stopper for lots of new users was when validating a new form with nested models: When rendering the form, they set up the form correctly.

AlbumForm.new(Album.new(songs: [Song.new, Song.new]))

This renders two song forms into the album form. Submitting usually ended in a fiasco of exceptions, as in the intercepting validating action, the code wasn’t setting up the object graph, again.

AlbumForm.new(Album.new).validate(params[:album])

Reform now tried to validate the incoming song data against Song models that weren’t there (Album.new doesn’t provide Songs). This was a misunderstanding: Reform is not supposed to be stateful over requests and remember how many songs it displayed in the last request.

Whatever – you can tell Reform to “auto-populate” in #validate now.

collection :songs, populate_if_empty: Song do
    property :title
    validates :title, presence: true
  end

This will create Song instances where they’re missing in validate. You can use a lambda and more options in case you wanna customize this process.

Lambdas are executed in the form’s context and need to return an instance (not the class).

collection :songs, 
  populate_if_empty: lambda { |input, args| 
    model.songs.build 
  },

This is all for #validate. I’ planning something similar for the rendering part to configure the number of forms to render, etc.

Syncing.

Synchronizing data with the underlying model has caused some confusion, too. That’s why we split it into two parts with very limited behaviour scopes. BTW – many changes in Reform 1.0 were triggered by vivid, colourful discussions on the issues forum – I hope you guys keep contributing great ideas and criticism.

To write data back to your models, you use the #sync method now. This will go through all models and use the specified writers to sync data from the form to the models.

form = AlbumForm.new(Album.new)
 
form.validate(params[:album])
 
form.sync 
#=> album.title = "Best Of"
#=> album.songs[0].title = "Roxanne"
# and so on

Note that this does change the state of your (persistent) models – it does not save changes, yet!

Saving.

When hitting the #save method Reform will call save on all models – unless you tell it not to do so:

collection :songs, save: false do
  property :title

In earlier version of Reform, saving would only call save on the top model. The idea behind that was that the underlying models are saved using ActiveRecord’s autosave: true feature. This design is still valid, however, Reform can do this for you, if you want it.

Contracts.

This is by far my favourite refactoring: parts of Form have been extracted into Contract which allows validating models without the UI aspect. Allowing you to define nested validations in a separate layer paves the way for dumb data models that just contain associations and persistence-related logic as targeted in Trailblazer.

A contract looks like a form. Actually, contracts can be derived from forms (and cells, and representers) automatically, but this would go too far now. Just keep in mind that there won’t be redundancy.

class AlbumContract < Reform::Contract
  property :title
  validates :title, length: {minimum: 9}
 
  collection :songs do
    property :title
    validates :title, presence: true
  end

This looks familiar. Now, a contract exposes three public methods.

album    = Album.find(1).update_attributes(..)
contract = AlbumContract.new(album)

The contract’s constructor accepts a model, just like a form.

if contract.validate
  album.save
else
  raise contract.errors.messages
end

You then use validate to run validations on the underlying model. Note that it doesn’t accept params – remember, it’s a contract validating the state of a model.

Eventually, you wanna display errors by calling errors on the contract.

The state of the model does not change during contract’s workflows.

See how contracts help you to decouple validations from your persistence layer? On long term, they will help you getting to a layered architecture.

An in-depth discussion of this architecture can be found in my upcoming book (scroll up, left!).

Renaming

Finally, renaming works for all properties, whether it’s Composition or a model form or nested or whatever.

collection :songs, as: :tracks do
  property :title

This will expose songs as “tracks”, i.e. setters/getters on the form and in the HTM, it’ll say “tracks”.

Internals.

Some things have changed in Reform 1.0. The internal workflows have been generalized. They all use representable for mapping data, it might look cryptic but once you got the hang of representable you will easily understand all the transformations that happen (I also added comments, some people complained about the lack of internal documentation).

The Form class is nothing more than an entry point delegating to the requested behaviour. This is reflected in four new modules.

  • Setup contains transformation logic to populate the form when instantiating it.
  • Validate – surprisingly – implements the #validate method along with the new populator option.
  • Sync writes form data to models.
  • Save delegates #save calls to all nested models.

This new file and class layout makes it very easy to navigate through Reform’s codebase – personally, I started structuring all my other gems like that.

Every workflow is implemented by exposing exactly one public method (e.g. #save) which goes through the form’s attributes on that level only. It then calls itself recursively on nested forms, making it a very clean implementation.