Support parameters for liquid include tags [take 2] #1204

maul-esel · Jun 11, 2013

This is a resubmission of #876 due to the heavy changes that have been made to master since it was submitted.

This PR adds the ability to send parameters to includes:

{% include foo.md bar="baz" %}

It can be used like this:

# in _includes/foo.md
{{ include.bar }} # outputs "baz" (without the quotes)

Thank you!! Sorry to ask yet another thing of you but would you mind writing a quick comment outlining exactly how this works from a user standpoint?

parkr · Jun 11, 2013

Thank you!! Sorry to ask yet another thing of you but would you mind writing a quick comment outlining exactly how this works from a user standpoint?

parkr · Jun 11, 2013

parkr reviewed Jun 11, 2013

View changes

parkr · Jun 11, 2013

features/include_tag.feature

+  Scenario: Include a file with parameters
+    Given I have an _includes directory
+    And I have an "_includes/header.html" file that contains "<header>My awesome blog header: {{include.param}}</header>"
+    And I have an "_includes/params.html" file that contains "Parameters:<ul>{% for param in include %}<li>{{param[0]}} = {{param[1]}}</li>{% endfor %}</ul>"


What if we made it so that we had this:

{% for param in include %} {{ param.key }} = {{ param.value }} {% endfor %}

I kind of like named accessors more than index accessors.

That's just standard liquid (e.g. http://stackoverflow.com/questions/8206869/iterate-over-hashes-in-liquid-templates) for hashes.

Ok cool :) Thanks!

You can write your {% include %} tags like before, so all old things should still work.

But if, for a particular include, you want some extra variables available depending on where they are included from, you add parameters to the tag, like {% include param='value' %}.

Inside the include, you can then access these from the liquid variable include. You can for example use this for navigations (pass the "current" section and mark it) or conditional styling (pass the CSS class to use in the include) etc.

maul-esel · Jun 11, 2013

You can write your {% include %} tags like before, so all old things should still work.

But if, for a particular include, you want some extra variables available depending on where they are included from, you add parameters to the tag, like {% include param='value' %}.

Inside the include, you can then access these from the liquid variable include. You can for example use this for navigations (pass the "current" section and mark it) or conditional styling (pass the CSS class to use in the include) etc.

parkr · Jun 11, 2013

parkr reviewed Jun 11, 2013

View changes

parkr · Jun 11, 2013

lib/jekyll/tags/include.rb

+eos
+        end
+
+        while pos = markup.index(/[=\"\s]/, pos)


Why not use regexp for this?

http://rubular.com/r/FbVfmDUIU6

😲 How did you come up with this? I tried, but couldn't think of any regex that does the job.

One thing though: Your regex supports both single and double quote, but a double quote can terminate a string started with single quote. This leads to problems with code like the following:

param='and" dg=' abc="d"

With your current regex, the dg=' portion is leftover, though I'd expect it to be part of param.

Do you have a fix for this, god of regex? Or drop single-quote support?

What do you think of this?

http://rubular.com/r/6P8aGivX9g

That seems to fail on your other test data - it reads everything as one param.

@paulmsmith You seem pretty excited about this. Can you come up with a use-case for a param whose value includes the = character? I can't think of anything.

If I'm understanding you chaps correctly, then a use-case might just be a string of copy text. For example I could want to do:

{% include headline='Jekyll include parameters are here' strapline='Using them = EPIC WIN!' %}

and from within the include:

<div class="somemodule"> <h1>{{ include.headline }}</h1> <p>{{ include.strapline }}</p> </div>

I'd expect that to output:

<div class="somemodule"> <h1>Jekyll include parameters are here</h1> <p>Using them = EPIC WIN!</p> </div>

Hope that makes sense.

That's the only thing I could think about as well. On the other side, most cases like that can be solved by using an HTML entity for the equal sign - we'd just need to document it.

So, guess what! @imathis (the true Regexp god) fixed everything: http://rubular.com/r/kmNhn2806o

Impressive! And indeed, the regex shortens the code immensely - definitly worth it.

parkr · Jun 11, 2013

parkr reviewed Jun 11, 2013

View changes

parkr · Jun 11, 2013

site/docs/templates.md

+
+{% highlight ruby %}
+{{ "{% include sig.textile param=value " }}%}
+{% endhighlight %}


Let's use {% raw %} blocks in here instead of that weird {{ "{% syntax.

You guys are awesome!

paulmsmith · Jun 12, 2013

You guys are awesome!

maul-esel · Jun 14, 2013

maul-esel reviewed Jun 14, 2013

View changes

maul-esel · Jun 14, 2013

lib/jekyll/tags/include.rb

+        pos = 0
+
+	# ensure the entire markup string from start to end is valid syntax, and params are separated by spaces
+        full_matcher = Regexp.compile('\A\s*(?:(?<=\s|\A)' + MATCHER.to_s + '\s*)*\z')


I used this to make sure the entire markup is valid, not only portions of it. However, 1.8.7 doesn't like look-behind (?<=...) - any advice?

Hm... not sure. What is the look-behind necessary for?

To make sure there's a space between the individual params. I could solve this issue by using a look-ahead at the end of the pattern instead.

OK, the tests finally pass. Anything else left to do?

maul-esel · Jun 15, 2013

OK, the tests finally pass. Anything else left to do?

imathis · Jun 15, 2013

What if we used this regex instead. ([\w-]+)\s*=\s*(?:"([^"\\]*(?:\\.[^"\\]*)*)"|'([^'\\]*(?:\\.[^'\\]*)*)'|([\w\.-]+)) that would add a few new options.

Supports spaces around the equals sign
Supports variable names with a dash (like YAML does).
Supports existing variables in match[4](see next comment)

imathis · Jun 15, 2013

This comment has been minimized.

Show comment

Hide comment

imathis Jun 15, 2013

If you set @markup = markup then you can move this regex parsing into the render method. Then using context, you can assign include variables using values from variables in the context. Using the new regex I commented about above, you'll have match[4] which will be an unquoted variable name derived from a match on something like foo=bar.baz. Then you can do the following:

elsif match[4]
  value = context[match[4]]
end

This will allow you to do something like this:

{% for post in site.posts reverse %}
  {% capture post_title %}{{ post.title | titlecase }}{% endcapture %}
  {% include post.html title=post_title %}
{% endfor %}

Then you can reference {{ include.title }} in your post template partial. By allowing variables as well as strings, template partials have to rely less on conditionals and global variables and aren't restricted to static strings like the current proposal would suggest.

If you set @markup = markup then you can move this regex parsing into the render method. Then using context, you can assign include variables using values from variables in the context. Using the new regex I commented about above, you'll have match[4] which will be an unquoted variable name derived from a match on something like foo=bar.baz. Then you can do the following:

elsif match[4]
  value = context[match[4]]
end

This will allow you to do something like this:

{% for post in site.posts reverse %}
  {% capture post_title %}{{ post.title | titlecase }}{% endcapture %}
  {% include post.html title=post_title %}
{% endfor %}

Then you can reference {{ include.title }} in your post template partial. By allowing variables as well as strings, template partials have to rely less on conditionals and global variables and aren't restricted to static strings like the current proposal would suggest.

Oh, if you want to see this new regex in action, here's the rubular.

imathis · Jun 15, 2013

Oh, if you want to see this new regex in action, here's the rubular.

Very interesting, thanks. I considered supporting variables, just didn't know how to. Unless @parkr or @mattr- have a different opinion, I'm happy to include it.

maul-esel · Jun 19, 2013

Very interesting, thanks. I considered supporting variables, just didn't know how to. Unless @parkr or @mattr- have a different opinion, I'm happy to include it.

mattr- · Jun 22, 2013

mattr- reviewed Jun 22, 2013

View changes

mattr- · Jun 22, 2013

lib/jekyll/tags/include.rb

+        end
+      end
+
+      MATCHER = /(\w+)=(?:"([^"\\]*(?:\\.[^"\\]*)*)"|'([^'\\]*(?:\\.[^'\\]*)*)')/


I'd prefer if the constant was at the top but I'm willing to be flexible.

@parkr do you have a preference here?

I also prefer the top if that's ok :)

I'm cool with supporting variables.

@parkr @mojombo Anything you're aware of that keeps us from supporting variables as in @imathis' example?

mattr- · Jun 22, 2013

I'm cool with supporting variables.

@parkr @mojombo Anything you're aware of that keeps us from supporting variables as in @imathis' example?

@mattr- @mojombo I think supporting extraction of variable values if the string input is a variable is a good idea.

@imathis also suggested we try something more direct (albeit Rails-like) with something like this:

{% include post.html locals: { author_class: "blue icon-notice", title: "Herein Lies the Story" } %}

So we'd take everything after .extname and parse it as JSON. It definitely takes more work in terms of styling, but also offers hierarchies and such. Might very well be too complicated for any solution Jekyll should hold in its core, but it's a pretty neat suggestion nevertheless. I'd say go with our current implementation in order to be more designer-friendly.

parkr · Jun 22, 2013

@mattr- @mojombo I think supporting extraction of variable values if the string input is a variable is a good idea.

@imathis also suggested we try something more direct (albeit Rails-like) with something like this:

{% include post.html locals: { author_class: "blue icon-notice", title: "Herein Lies the Story" } %}

So we'd take everything after .extname and parse it as JSON. It definitely takes more work in terms of styling, but also offers hierarchies and such. Might very well be too complicated for any solution Jekyll should hold in its core, but it's a pretty neat suggestion nevertheless. I'd say go with our current implementation in order to be more designer-friendly.

Adjusted according to @imathis' suggestion, moved the regex up (@mattr-).

maul-esel · Jun 22, 2013

Adjusted according to @imathis' suggestion, moved the regex up (@mattr-).

This seems similar to the extended include tag in shopify: {% include 'foo' with 'bar' %}

I can't seem to get that to work in Jekyll though, and this PR looks more useful. 👍 Can't wait to get my hands on it.

bcomnes · Jun 30, 2013

This seems similar to the extended include tag in shopify: {% include 'foo' with 'bar' %}

I can't seem to get that to work in Jekyll though, and this PR looks more useful. 👍 Can't wait to get my hands on it.

Sorry to push. What's the latest on this @imathis @parkr ? Going to be in Jekyll one day soon?

paulmsmith · Jul 4, 2013

Sorry to push. What's the latest on this @imathis @parkr ? Going to be in Jekyll one day soon?

parkr · Jul 4, 2013

parkr reviewed Jul 4, 2013

View changes

parkr · Jul 4, 2013

lib/jekyll/tags/include.rb

+        end
+
+        while match = MATCHER.match(markup) do
+          markup = markup[match.end(0)..-1]


in practice, i think this will only ever execute once. @imathis's pattern above seems to encompass the entire call, no?

No. If you look at the rubular he linked, there are several matches, so this should execute for each of them.

parkr · Jul 5, 2013

parkr reviewed Jul 5, 2013

View changes

parkr · Jul 5, 2013

lib/jekyll/tags/include.rb

+        if markup.include?(' ')
+          separator = markup.index(' ')
+          @file = markup[0..separator].strip
+          @params = markup[separator..-1]


@file, @params = markup.split(' ', 2)

should work :)

and it applies to both with and without params, so both of these work:

# No params @markup = "some_fun_thing.html" @file, @params = markup.split(" ", 2) @file # => "some_fun_thing.html" @params # => nil # With params @markup = "some_amazing_thing.html name='henry' title='king'" @file, @params = markup.split(" ", 2) @file # => "some_amazing_thing.html" @params # => "name='henry' title='king'"

parkr · Jul 5, 2013

parkr reviewed Jul 5, 2013

View changes

parkr · Jul 5, 2013

lib/jekyll/tags/include.rb

+
+	# ensure the entire markup string from start to end is valid syntax, and params are separated by spaces
+        full_matcher = Regexp.compile('\A\s*(?:' + MATCHER.to_s + '(?=\s|\z)\s*)*\z')
+        if not markup =~ full_matcher


unless is a bit more idiomatic here :)

@mattr-, would you please take another look at this? Looks pretty ready to me.

parkr · Jul 7, 2013

@mattr-, would you please take another look at this? Looks pretty ready to me.

mattr- · Jul 8, 2013

mattr- reviewed Jul 8, 2013

View changes

mattr- · Jul 8, 2013

lib/jekyll/tags/include.rb

+
+      def parse_params(markup, context)
+        params = {}
+        pos = 0


I think we can remove the pos variable. I'm not seeing it used anywhere.

👍 from me, even with the comment above.

mattr- · Jul 8, 2013

👍 from me, even with the comment above.

mattr- · Jul 8, 2013

mattr- reviewed Jul 8, 2013

View changes

mattr- · Jul 8, 2013

lib/jekyll/tags/include.rb

+        params = {}
+        pos = 0
+
+	# ensure the entire markup string from start to end is valid syntax, and params are separated by spaces


Looking at this again, the comment tells me that this should be in a separate method, something like below, perhaps?

def validate_syntax full_matcher = Regexp.compile('\A\s*(?:' + MATCHER.to_s + '(?=\s|\z)\s*)*\z') unless markup =~ full_matcher raise SyntaxError.new <<-eos Invalid syntax for include tag: #{markup} Valid syntax: {% include file.ext param='value' param2="value" %} eos end end

and then you can change the parse_params method to be like so:

def parse_params(markup, context) params = {} validate_syntax ... end

Thoughts?

parkr · Jul 8, 2013

parkr reviewed Jul 8, 2013

View changes

parkr · Jul 8, 2013

lib/jekyll/tags/include.rb

+            value = match[3].gsub(/\\'/, "'")
+          elsif match[4]
+            value = context[match[4]]
+          end


what do you think about having this block return the value and setting value outside the block?

Despite the build failure, this actually runs fine.

maul-esel · Jul 8, 2013

Despite the build failure, this actually runs fine.

MERGED!! Thanks so much for your hard work and patience with us on this @maul-esel and props to @imathis for crazy amazing Regexp-fu.

parkr · Jul 9, 2013

MERGED!! Thanks so much for your hard work and patience with us on this @maul-esel and props to @imathis for crazy amazing Regexp-fu.

🎉 🎆

mattr- · Jul 9, 2013

🎉 🎆

Awesome!! Thanks for all the work @maul-esel, @parkr, @imathis and chums! Looking forward to using it!!

paulmsmith · Jul 10, 2013

Awesome!! Thanks for all the work @maul-esel, @parkr, @imathis and chums! Looking forward to using it!!

@maul-esel Great work! Thanks so much for sticking with this through all the various revisions and comments.

mattr- · Jul 10, 2013

@maul-esel Great work! Thanks so much for sticking with this through all the various revisions and comments.

Happy to help this awesome project grow and develop further. And thanks to you both for bringing it back to life❗️

maul-esel · Jul 10, 2013

Happy to help this awesome project grow and develop further. And thanks to you both for bringing it back to life❗️

parkr referenced this pull request Jun 11, 2013
Closed
Support parameters for liquid include tags #876

parkr referenced this pull request Jun 13, 2013
Closed
Includes with args/parameters #848

maul-esel added some commits Jun 15, 2013

To satisfy Ruby 1.8.7, use look-ahead instead of look-behind

99721ee

Ruby 1.8.7 only supports 1 param to Regexp.match()

bdd84f2

code improvements according to @parkr's suggestions

ef22ebd

more code improvements
Remove unused variable, extract validation to method (@mattr-). Do not require markup to be passed to parse_params as argument.

f72365d

set value outside if/else block

9d2849c

parkr added a commit that referenced this pull request Jul 9, 2013

Merge pull request #1204 from maul-esel/include-params2
Support parameters for liquid include tags.

08f6f3c

parkr merged commit 08f6f3c into jekyll:master Jul 9, 2013
1 check passed

1 check passed

default The Travis CI build passed
Details

parkr added a commit that referenced this pull request Jul 9, 2013

Update history to reflect merge of #1204.

42ac16b

maul-esel deleted the maul-esel:include-params2 branch Jul 10, 2013

heyLu referenced this pull request Jul 26, 2013
Closed
Only works with latest Jekyll. #1

coffeetocode referenced this pull request Aug 19, 2013
Closed
Lay out columns in team.html using a loop in Liquid. #29

tfoote referenced this pull request Aug 25, 2014
Closed
find minimum jekyll and docker version #34

jekyll locked and limited conversation to collaborators Feb 27, 2017

jekyllbot added the frozen-due-to-age label Feb 27, 2017

jekyll/jekyll

Join GitHub today

Support parameters for liquid include tags [take 2] #1204

Conversation

maul-esel commented Jun 11, 2013

maul-esel added some commits May 24, 2013

This comment has been minimized.

parkr commented Jun 11, 2013

parkr reviewed Jun 11, 2013 View changes

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

maul-esel commented Jun 11, 2013

parkr reviewed Jun 11, 2013 View changes

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

parkr reviewed Jun 11, 2013 View changes

This comment has been minimized.

This comment has been minimized.

parkr referenced this pull request Jun 11, 2013

This comment has been minimized.

paulmsmith commented Jun 12, 2013

maul-esel added some commits Jun 12, 2013

parkr referenced this pull request Jun 13, 2013

maul-esel reviewed Jun 14, 2013 View changes

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

maul-esel added some commits Jun 15, 2013

This comment has been minimized.

maul-esel commented Jun 15, 2013

This comment has been minimized.

imathis commented on lib/jekyll/tags/include.rb in 0fa03d2 Jun 15, 2013

This comment has been minimized.

imathis commented on lib/jekyll/tags/include.rb in 0fa03d2 Jun 15, 2013

This comment has been minimized.

imathis commented Jun 15, 2013

This comment has been minimized.

maul-esel commented Jun 19, 2013

mattr- reviewed Jun 22, 2013 View changes

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

mattr- commented Jun 22, 2013

This comment has been minimized.

parkr commented Jun 22, 2013

maul-esel and others added some commits Jun 22, 2013

This comment has been minimized.

maul-esel commented Jun 22, 2013

This comment has been minimized.

bcomnes commented Jun 30, 2013

This comment has been minimized.

paulmsmith commented Jul 4, 2013

parkr reviewed Jul 4, 2013 View changes

This comment has been minimized.

This comment has been minimized.

parkr reviewed Jul 5, 2013 View changes

This comment has been minimized.

This comment has been minimized.

parkr reviewed Jul 5, 2013 View changes

This comment has been minimized.

This comment has been minimized.

parkr commented Jul 7, 2013

mattr- reviewed Jul 8, 2013 View changes

This comment has been minimized.

This comment has been minimized.

mattr- commented Jul 8, 2013

mattr- reviewed Jul 8, 2013 View changes

This comment has been minimized.

parkr reviewed Jul 8, 2013 View changes

parkr reviewed Jun 11, 2013

View changes

parkr reviewed Jun 11, 2013

View changes

parkr reviewed Jun 11, 2013

View changes

maul-esel reviewed Jun 14, 2013

View changes

imathis commented on `lib/jekyll/tags/include.rb` in `0fa03d2` Jun 15, 2013

imathis commented on `lib/jekyll/tags/include.rb` in `0fa03d2` Jun 15, 2013

mattr- reviewed Jun 22, 2013

View changes

parkr reviewed Jul 4, 2013

View changes

parkr reviewed Jul 5, 2013

View changes

parkr reviewed Jul 5, 2013

View changes

mattr- reviewed Jul 8, 2013

View changes

mattr- reviewed Jul 8, 2013

View changes

parkr reviewed Jul 8, 2013

View changes