Introduction to Drops

[Ian Leitch]

Just a quick introduction to drops... I may write some more docs when I get bored of my real work.

Liquid Drops
============

Drops let you provide the user with custom functionality. They're very much like a standard Ruby class, but have all un-needed and potentialy dangerous methods removed. From the user's perspective a drop acts very much like a Hash, thought methods are accessed with dot-notation aswell as element selection. A drop method cannot be invoked with arguments. Drops are called just-in-time thus allowing you to lazily load objects.

Standard drop methods:

  before_method(method):

    Called once for every invokation, even if the destination method doesn't exist. Can be used to provide dynamically named methods.

    Example:

      class MembersDrop < Liquid::Drop

        def before_method(method)

          user = User.find_by_name(method)

          user ? UserDrop.new(user) : nil

        end

      end

      ==== View ==================================

      {% assign user = members.ian %}
      {{ user.name }}

  invoke_drop(method):

    Called by liquid to invoke the target drop method.

  has_key(name):

    Currently returns true regardless.

  to_liquid:

    Returns the drop instance.


Drop usage:

  class ProductDrop < Liquid::Drop

    def initialize(product)

      @product = product

    end

    def name

      @product[:name]

    end

    def description

      @product[:description]

    end

    def price

      @product[:price]

    end

  end

  === Controller =============================

  template = Liquid::Template.parse( File.read( product_view.liquid ) )
  template.render( { :product => ProductDrop.new(@product) } )

  === View =================================== 

   Viewing product: {{ product.name }}
   <br/><br />
   {{ product.description }}
   <br />
   £{{ product.price }}

[Tobias Lütke]

Very cool. Could you add this to the liquid home page?

--
Tobi
http://shopify.com - modern e-commerce software
http://typo.leetsoft.com - Open source weblog engine
http://blog.leetsoft.com - Technical weblog

[b.d...@gmail.com]

Ian,

thank you very much :-)

and.... give us more ;-D

--Björn

[Ian Leitch]

I'm not sure I can. I don't see an 'edit' link anywhere, and the login page gives me "Authentication information not available" error.

[Tobias Lütke]

Right, sorry about that. I had to disable anonymous editing because of spam :(

I added your documentation to the HowTo page

[nichola...@gmail.com]

Should the example:

template.render( { :product => ProductDrop.new(@product) } )

be

template.render( { 'product' => ProductDrop.new(@product) } )

I couldn't get the rending to work with a symbol, but works with a
string. Is this correct?

[Tobias Lütke]

Correct.

[Ian Leitch]

Good catch. I've wrote a patch a while ago to let me use symbols for assigns, I guess I forgot to use just strings :)

The patch has actually been in the tracker for 3 weeks with no attention ( http://home.leetsoft.com/liquid/ticket/298). Currently the bug tracker looks more like a home for spam than anything else.

[Tobias Lütke]

The patch only changes symbols to strings in a shallow way. It doesn't
reverse into nested hashes.

I don't want to indulge in premature optimizations but it seems to me
that it would be a bit wasteful to traverse the entire nested hash
tree to switch keys to strings. This problem will go away with ruby
2.0 anyways because strings and symbols will be interchangeable.

[nichola...@gmail.com]

Don't forget to change it on the wiki :)
http://home.leetsoft.com/liquid/wiki/HowTo