merged branch fabpot/render-function (PR #926)

merged branch fabpot/render-function (PR #926)

This PR was merged into the master branch.

Commits
-------

f4f88a5 added an include function

Discussion
----------

added an include function

---------------------------------------------------------------------------

by stof at 2012-12-09T14:12:25Z

I see an issue with this naming: it will confuse Symfony users because of the ``render`` tag doing something different than the ``render`` function. And it will force to break BC for Silex users where the subrequest logic is using a ``render`` function right now

---------------------------------------------------------------------------

by fabpot at 2012-12-10T12:49:57Z

@stof: I know about the possible confusion. For Silex, as it is not stable yet, we don't need to keep BC. And I don't have any other better name. What I want to introduce next is a `render_request` function in both Silex and Symfony (which will do the same as the current render tag in Symfony and the render function in Silex).

---------------------------------------------------------------------------

by Taluu at 2012-12-10T14:13:31Z

Hi,

I may be absent-minded, but I don't really understand the difference between `render` function and the `include` tag... ?

---------------------------------------------------------------------------

by fabpot at 2012-12-10T14:16:09Z

@Taluu Using a function allows you to do whatever you want with the output (which is not possible with a tag), like a simple:

```jinja
{{ set content = render('some_template') }}
```

Also, semantically, using a tag to output some content is less correct.

---------------------------------------------------------------------------

by vicb at 2012-12-10T14:18:17Z

could it be named `include` ?

---------------------------------------------------------------------------

by tcz at 2012-12-10T14:18:40Z

I agree that it's confusing for Symfony users. It is the same as raw filter and raw tag. I would prefer execute as name or something like that

---------------------------------------------------------------------------

by Taluu at 2012-12-10T14:19:29Z

@fabpot so, does it means that it could replace the include tag ? Then, we could could name it `include` as @vicb suggested... ?

---------------------------------------------------------------------------

by titomiguelcosta at 2012-12-10T14:21:51Z

I agree with @stof, naming it render will be confusing, parse or execute or compile are other names that come to my mind for this purpose.

---------------------------------------------------------------------------

by silentworks at 2012-12-10T14:24:36Z

How about calling it `partial`? even though you are rendering a full template, it is being included in another so this could be seeing as a partial of that template.

---------------------------------------------------------------------------

by stof at 2012-12-10T14:26:05Z

@titomiguelcosta parse is totally wrong. The function is not parsing the string you give it. you don't pass the content of the template but its name. and ``compile`` is also wrong. It is not compiling a template but rendering it.

---------------------------------------------------------------------------

by jmather at 2012-12-10T14:30:53Z

I think `render` is probably the most appropriate name, but also may cause confusion, however I don't have another suggestion that is nearly as clear as to context and meaning.

---------------------------------------------------------------------------

by emgiezet at 2012-12-10T14:31:26Z

Can you pass the array of params as an argument to the `render` function?

---------------------------------------------------------------------------

by titomiguelcosta at 2012-12-10T14:31:59Z

@stof true that we pass the filename as argument, but we end up parsing the file.

---------------------------------------------------------------------------

by stof at 2012-12-10T14:32:48Z

@emgiezet you mean passing some variables available in the included template ? Sure you can. See the doc. the argument is named ``variables``

---------------------------------------------------------------------------

by stof at 2012-12-10T14:34:36Z

@titomiguelcosta But the goal of the function is not to parse the file (btw, it may not parse it if the template was already compiled in the cache). The goal is to render the template.

Btw, I agree with @jmather. As far as Twig is concerned, ``render`` is the best name. The only issue comes from the fact that Symfony already use a ``{% render %}`` tag with a different meaning

---------------------------------------------------------------------------

by emgiezet at 2012-12-10T14:39:02Z

@stof thx a lot didn't noticed the doc link. Maybe `render_partial` will be good in this case?

---------------------------------------------------------------------------

by tcz at 2012-12-10T14:44:13Z

In an ideal world the Symfony2 `render` tag would be renamed to `subrequest` or something like that and the new function in Twig would get the `render` name. The question is how many people use Twig because of Symfony2 and how many of them use it in itself (in my company we use standalone Twig for example).

I think it's important to avoid `raw`-style confusions for the former group.

---------------------------------------------------------------------------

by stof at 2012-12-10T15:16:28Z

@tcz The issue with renaming the tag in Symfony is that it would be a BC break. So we cannot simply drop the tag (we can provide a new name and deprecate the current one, but we would still keep it).

---------------------------------------------------------------------------

by Taluu at 2012-12-10T15:18:56Z

I think `partial` would be a good idea... But still, does it mean that the `include` tag would be deprecated in favor of `render` (or whatever the name will be) function ?

---------------------------------------------------------------------------

by tcz at 2012-12-10T15:19:49Z

@stof Yes :( hence my remark "in an ideal world"

---------------------------------------------------------------------------

by stof at 2012-12-10T15:27:52Z

@Taluu It depends if @fabpot wants to keep the compatibility with Jinja where possible (as it is where the ``include`` tag comes from)

---------------------------------------------------------------------------

by WouterJ at 2012-12-10T15:48:26Z

I like the function, but I don't like the name. I like the name `partial`.

I am a front-end developer from origin and all files you include in the base CSS stylesheet are called 'partials' in SASS or other preprosessors. Twig is used to make live easier for front-end developers and I think a function called `partial` is more familiair for them than `render`.

---------------------------------------------------------------------------

by silentworks at 2012-12-10T16:17:24Z

@stof I guess based on @fabpot wanting to keep Twig compatibility with Jinja, calling the tag `partial` rather than `render` shouldn't be a problem since Jinja doesn't have any of these.

---------------------------------------------------------------------------

by Taluu at 2012-12-10T16:19:25Z

@silentworks @stof was talking about my question, about why keep the `include` tag if the `render` (or whatever the name will be) is indeed inserted into Twig. :)

---------------------------------------------------------------------------

by stof at 2012-12-10T16:19:38Z

@silentworks I was not talking about the name of the function, but about the removal of the ``include`` tag

---------------------------------------------------------------------------

by silentworks at 2012-12-10T16:22:37Z

Thanks for clarity from both.

On the basis of keeping to conformity to Jinja, should this function not be a part of twig extensions rather than in the core?

---------------------------------------------------------------------------

by mvrhov at 2012-12-10T17:20:03Z

Well search and replace for symfony users when upgrading shouldn't be that hard so I'd say that we rename the symfony block into subrequest or sth similar.

---------------------------------------------------------------------------

by Taluu at 2012-12-10T17:26:22Z

If we were to follow your recommandations, we could say the same for all and every changes inducing a BC break huh...

---------------------------------------------------------------------------

by markstory at 2012-12-10T17:49:36Z

What about naming the function `include`?  It would share a name with the tag, but it also does the same type of thing as the tag.  The function has the advantage of having its return captured.  I think  `{{ include(template) }}` semantically does what it looks like it does when operating on the template object as well.

Other names that I think could fit well are `partial` and `display`. Render works well, but I understand people not wanting to overlap with existing symfony features that do very different things.

---------------------------------------------------------------------------

by Baachi at 2012-12-10T18:13:25Z

I think "partial" is a better name for this function and it would keep BC.