Is the equal sign before merge fields necessary? about sablon HOT 13 CLOSED

That is a shame word places those implicit restrictions but I suppose not surprising. I don't see too much of an issue with supporting insert fields with and without an equals sign if the latter could be turned off or on with a config option (off being the default).

That would fix your use case with the additional benefit of allowing someone with a large cache of old mail merge templates to use them "as-is" without having to go through an update every single merge field with an equals sign. It is turned off by default to avoid breaking the current expected behavior. Any thoughts on this @senny?

Code Example:

# in your /config/application.rb or equivalent  file
Sablon.configure do |config|
  config.allow_insert_without_equals = true #false by default
end


# in lib/sablon/processor/document.rb
def consume(allow_insertion)
  @field = @fields.shift
  return unless @field
  case @field.expression
  when /^=/
    if allow_insertion
      Statement::Insertion.new(Expression.parse(@field.expression[1..-1]), @field)
    end
  when /([^ ]+):each\(([^ ]+)\)/
    block = consume_block("#{$1}:endEach")
    Statement::Loop.new(Expression.parse($1), $2, block)
  when /([^ ]+):if\(([^)]+)\)/
    block = consume_block("#{$1}:endIf")
    Statement::Condition.new(Expression.parse($1), block, $2)
  when /([^ ]+):if/
    block = consume_block("#{$1}:endIf")
    Statement::Condition.new(Expression.parse($1), block)
  when /comment/
    block = consume_block("endComment")
    Statement::Comment.new(block)
  else
    if allow_insertion && Sablon::Configuration.allow_insert_without_equals
      Statement::Insertion.new(Expression.parse(@field.expression), @field)
    end
  end
end

from sablon.

Ah nm! Got it! Thx for the feature @stadelmanma

from sablon.

Hi @skuark I would say the biggest consequence of removing the leading equals sign is that it prevents the user from mixing sablon targeted merge fields with regular merge fields.

Just out of curiosity have you tried quoting the merge field value in the excel cell? That might allow it to ignore the equals sign instead of thinking it's a formula i.e. '=field_name instead of field_name.

from sablon.

We did try the quote approach ('=field_name) but word doesn't add the equal sign when loading it.
cc @skuark

from sablon.

Yes, as @paucc says, we tried it. Word also has a UI to customize the list of fields (without Excel), and it neither works:

from sablon.

It doesn't work either with the quote:

from sablon.

The mindset behind sablon was that it is compatible with existing documents and doesn't interfere with whatever is already there. That's why I chose a distinct set of expressions from what you would see in regular MailMerge fields.

I can see that there are use-cases to use regular fields for insertion but I'm not fully convinced that sablon needs to address this use-case with a configuration option. What we could do though, is turn the whole case statement into a method. This would make it super easy to extend the behavior by using Module.prepend and super.

@stadelmanma what do you think?

from sablon.

@senny I had to do some reading on Module.preappend as I wasn't familiar with it but I think I'm following. That sounds like a decent option to me since it'll make it easier for the end user to extend without doing awkward monkey patches or forking the gem.

from sablon.

I am going to revisit this but from a slightly different angle. Instead of setting it up as a single method and using Module.preappend which is kind of hack-y and highly dependent on the implementation details. I am going to setup a formal API to register "merge field handlers".

This will work in the exact same fashion as adding new DOM Handlers. You will specify the pattern to check and a method or proc to handle processing the fields. A "default" handler will made be available to take the place of an else clause in the above case statement when no other handler gets invoked. To match current the behaviors the default case would be a noop unless configured otherwise by the end user.

In context of this specific issue you would copy the logic in the simple insertion handler over to the "default" handler to allow insertion without an equals sign.

The merge field handlers will probably accept the current instance of the document processor class (i.e. self in the above case statement), the current @field and the allow_insertion parameter. They would be expected to return a Statement::* class instance or something equivalent.

Edit (03/20/18): After looking through the code in PR #73 I need to be sure to have a way to delete an existing "builtin" handler. Perhaps adding a name field to the registration function would work. Then I could set it up so simple registration won't replace an existing key and instead the user would need to use a "replace_handler" function or combine a "delete_handler" and "add_handler" method call (which is what the "replace_handler" would do internally).

from sablon.

Hi @skuark I don't know if or how you ended up solving this issue but the recently merged PR will allow you to easily accomplish this without formal fork of the gem. I'm not going to cut a release yet but you can pull the gem from the master branch to try things out.

See the custom_field_handlers_test.rb file for an example on how to add your own merge fields to Sablon.

from sablon.

Oh, great @stadelmanma, thanks a lot!

We didn't solve the issue yet, so I'll give a try as soon as I can.

from sablon.

@stadelmanma this is great. Exactly what I need at the moment. However, is there by chance a better example of usage than the custom_field_handlers_test.rb file? I didn't see this issue mentioned in the README and I'm afraid putting the test example to use is a bit beyond my grasp.

from sablon.

Just figured this out myself for this exact use case. Used

class InsertionWithoutEqualsHandler < Sablon::Processor::Document::FieldHandler
  def initialize
    super(/^/)
  end

  def build_statement(_constructor, field, options = {})
    return unless options[:allow_insertion]

    expr = Sablon::Expression.parse(field.expression)
    Sablon::Statement::Insertion.new(expr, field)
  end
end

Sablon::Processor::Document.register_field_handler :insertion_without_equals, InsertionWithoutEqualsHandler.new

YMMV though - I am only using Sablon in a very very basic use-case.

from sablon.