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

maul-esel · 2013-06-11T14:14:02Z

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)

parkr · 2013-06-11T16:44:44Z

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 · 2013-06-11T18:10:15Z

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!

maul-esel · 2013-06-11T18:15:30Z

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 · 2013-06-11T18:19:24Z

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 · 2013-06-11T18:19:54Z

site/docs/templates.md

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


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

paulmsmith · 2013-06-12T09:05:04Z

You guys are awesome!

This also introduces single-quote support.

maul-esel · 2013-06-14T19:47:41Z

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.

maul-esel · 2013-06-15T16:33:53Z

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

imathis · 2013-06-15T22:04:24Z

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 · 2013-06-15T22:04:28Z

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.

imathis · 2013-06-15T22:32:36Z

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

maul-esel · 2013-06-19T15:24:50Z

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- · 2013-06-22T03:41:40Z

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 :)

mattr- · 2013-06-22T04:04:01Z

I'm cool with supporting variables.

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

parkr · 2013-06-22T10:48:53Z

@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.

bcomnes · 2013-06-30T09:10:12Z

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.

paulmsmith · 2013-07-04T09:18:48Z

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

parkr · 2013-07-04T09:21:54Z

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 · 2013-07-05T11:30:02Z

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 · 2013-07-05T11:34:51Z

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 :)

parkr · 2013-07-07T22:12:44Z

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

mattr- · 2013-07-08T15:51:56Z

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.

mattr- · 2013-07-08T15:53:08Z

👍 from me, even with the comment above.

mattr- · 2013-07-08T16:09:16Z

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?

@mattr-

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

parkr · 2013-07-08T18:16:01Z

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?

maul-esel · 2013-07-08T19:05:20Z

Despite the build failure, this actually runs fine.

Support parameters for liquid include tags.

parkr · 2013-07-09T21:17:51Z

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- · 2013-07-09T21:19:59Z

🎉 🎆

paulmsmith · 2013-07-10T08:06:56Z

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

mattr- · 2013-07-10T17:17:43Z

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

maul-esel · 2013-07-10T20:31:46Z

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

maul.esel added 5 commits May 24, 2013

add a cucumber feature for passing parameters to includes

73e589d

add support for parameters to {% include %} tags

f612330

document include tag parameters

fad2101

add unit tests for include tag parameters

Loading status checks…

5a990f7

fix cucumber feature to obey new date format

Loading status checks…

1e15df0

parkr reviewed Jun 11, 2013
View changes

parkr mentioned this pull request Jun 11, 2013

Support parameters for liquid include tags #876

Closed

maul.esel added 4 commits Jun 12, 2013

fix liquid syntax in the docs

Loading status checks…

1b20a18

do parameter parsing with @imathis' incredible regex

639acea

This also introduces single-quote support.

add single-quote cucumber testing

Loading status checks…

53dec6a

stupid Ruby 1.8.7 doesn't support named groups

Loading status checks…

0fa03d2

parkr mentioned this pull request Jun 13, 2013

Includes with args/parameters #848

Closed

maul-esel reviewed Jun 14, 2013
View changes

maul.esel added 2 commits Jun 15, 2013

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

Loading status checks…

99721ee

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

Loading status checks…

bdd84f2

mattr- reviewed Jun 22, 2013
View changes

maul.esel added 2 commits Jun 22, 2013

move regex to the top

00ed567

move parameter parsing to render time

f8f6784

parkr reviewed Jul 4, 2013
View changes

parkr reviewed Jul 5, 2013
View changes

code improvements according to @parkr's suggestions

Loading status checks…

ef22ebd

mattr- reviewed Jul 8, 2013
View changes

lib/jekyll/tags/include.rb Outdated

def parse_params(markup, context)

params = {}

pos = 0

This comment has been minimized.

Sign in to view

mattr- Jul 8, 2013
Member

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

mattr- reviewed Jul 8, 2013
View changes

more code improvements

Loading status checks…

f72365d

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

parkr reviewed Jul 8, 2013
View changes

lib/jekyll/tags/include.rb Outdated

value = match[3].gsub(/\\'/, "'")

elsif match[4]

value = context[match[4]]

end

This comment has been minimized.

Sign in to view

parkr Jul 8, 2013
Member

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

set value outside if/else block

Loading status checks…

9d2849c

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

Merge pull request #1204 from maul-esel/include-params2

Loading status checks…

08f6f3c

Support parameters for liquid include tags.

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.

Loading status checks…

42ac16b

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

heyLu mentioned this pull request Jul 26, 2013

Only works with latest Jekyll. heyLu/heylu.github.com#1

Closed

coffeetocode mentioned this pull request Aug 19, 2013

Lay out columns in team.html using a loop in Liquid. swcarpentry/DEPRECATED-site#29

Closed

tfoote mentioned this pull request Aug 25, 2014

find minimum jekyll and docker version tfoote/design#34

Closed

jekyll locked and limited conversation to collaborators Feb 27, 2017

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

jekyll / jekyll

Sponsor jekyll/jekyll

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

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

Conversation

maul-esel commented Jun 11, 2013

parkr commented Jun 11, 2013

This comment has been minimized.

parkr Jun 11, 2013 Member

This comment has been minimized.

maul-esel Jun 11, 2013 Author

This comment has been minimized.

parkr Jun 11, 2013 Member

maul-esel commented Jun 11, 2013

This comment has been minimized.

parkr Jun 11, 2013 Member

This comment has been minimized.

maul-esel Jun 12, 2013 Author

This comment has been minimized.

maul-esel Jun 12, 2013 Author

This comment has been minimized.

parkr Jun 12, 2013 Member

This comment has been minimized.

maul-esel Jun 12, 2013 Author

This comment has been minimized.

parkr Jun 12, 2013 Member

This comment has been minimized.

paulmsmith Jun 12, 2013

This comment has been minimized.

maul-esel Jun 12, 2013 Author

This comment has been minimized.

parkr Jun 12, 2013 Member

This comment has been minimized.

maul-esel Jun 13, 2013 Author

This comment has been minimized.

parkr Jun 11, 2013 Member

This comment has been minimized.

maul-esel Jun 12, 2013 Author

paulmsmith commented Jun 12, 2013

This comment has been minimized.

maul-esel Jun 14, 2013 Author

This comment has been minimized.

parkr Jun 15, 2013 Member

This comment has been minimized.

maul-esel Jun 15, 2013 Author

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

imathis commented Jun 15, 2013

maul-esel commented Jun 19, 2013

This comment has been minimized.

mattr- Jun 22, 2013 Member

This comment has been minimized.

parkr Jun 22, 2013 Member

mattr- commented Jun 22, 2013

parkr commented Jun 22, 2013

bcomnes commented Jun 30, 2013

paulmsmith commented Jul 4, 2013

This comment has been minimized.

parkr Jul 4, 2013 Member

This comment has been minimized.

maul-esel Jul 4, 2013 Author

This comment has been minimized.

parkr Jul 5, 2013 Member

This comment has been minimized.

parkr Jul 5, 2013 Member

This comment has been minimized.

parkr Jul 5, 2013 Member

parkr commented Jul 7, 2013

This comment has been minimized.

mattr- Jul 8, 2013 Member

mattr- commented Jul 8, 2013

This comment has been minimized.

mattr- Jul 8, 2013 Member

This comment has been minimized.

parkr Jul 8, 2013 Member

maul-esel commented Jul 8, 2013

parkr commented Jul 9, 2013

parkr Jun 11, 2013
Member

maul-esel Jun 11, 2013
Author

parkr Jun 11, 2013
Member

parkr Jun 11, 2013
Member

maul-esel Jun 12, 2013
Author

maul-esel Jun 12, 2013
Author

parkr Jun 12, 2013
Member

maul-esel Jun 12, 2013
Author

parkr Jun 12, 2013
Member

maul-esel Jun 12, 2013
Author

parkr Jun 12, 2013
Member

maul-esel Jun 13, 2013
Author

parkr Jun 11, 2013
Member

maul-esel Jun 12, 2013
Author

maul-esel Jun 14, 2013
Author

parkr Jun 15, 2013
Member

maul-esel Jun 15, 2013
Author

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- Jun 22, 2013
Member

parkr Jun 22, 2013
Member

parkr Jul 4, 2013
Member

maul-esel Jul 4, 2013
Author

parkr Jul 5, 2013
Member

parkr Jul 5, 2013
Member

parkr Jul 5, 2013
Member

mattr- Jul 8, 2013
Member

mattr- Jul 8, 2013
Member

parkr Jul 8, 2013
Member