thr3ads.net - Rails - Rails lack of documentation (render nested layouts) [Sep 2008]

If this information is useful, please help other people find it:
Share via:

Rodrigo Rosenfeld Rosas

2008-Sep-02 20:58 UTC

Rails lack of documentation (render nested layouts)

I''ve posted some days ago about the lack of proper documentation for
the
testing framework used by Rails.

Today, among other days, I noted one more method missing documentation.

I''ve read the past year about nested layouts in some blog I
don''t remember.

Today I had to write a new application and needed the nested layouts again.

First, I looked at the documentation, as I use to do. Didn''t find. Then
I
looked at my other project code and found how, although I couldn''t find
this feature documented.

Into the documentation there are references for:
render (ActionView::TemplateHandlers::Compilable)
render (ActionView::TemplateHandler)

But none of them had any documentation available (although I''m not sure
these are the methods I should be looking for. Maybe it should be "render
(ActionController::Base)").

Well, the requirements are quite simple, so is the solution, but finding it
on documentations is impossible, unless I''m missing something.

To keep it clear, here is the actual case:

I want to have a master layout (application.erb) and another layout
(another.erb) for the AnothersController, based on master layout.

application.erb:
<html>
...
<%= yield :further_header %>
...
</html>

another.erb:
<% content_for :further_header do %>
Further content here
<% end %>

<%= render ''layouts/application'' %>

Quite simple, don''t you think? So what am I complaining about? This is
a
very useful hidden feature. It is not documented. Even worse, the render
method is not documented. And even if I didn''t care about others
reaching
this feature, I would care if this feature will continue working in the
next Rails releases. Once a feature is documented, there is a great chance
it will continue to be supported...

I would like to help documenting such missing documentation, but I need some
instructions how can I do that: how to make patches, and need to know how
do these methods actually work.

Thanks in advance,

Rodrigo.



--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Talk" group.
To post to this group, send email to
rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
To unsubscribe from this group, send email to
rubyonrails-talk+unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
For more options, visit this group at
http://groups.google.com/group/rubyonrails-talk?hl=en
-~----------~----~----~----~------~----~------~--~---

Frederick Cheung

2008-Sep-03 06:19 UTC

head link

Re: Rails lack of documentation (render nested layouts)

On 2 Sep 2008, at 21:58, Rodrigo Rosenfeld Rosas wrote:
>
> I''ve posted some days ago about the lack of proper documentation
for
> the
> testing framework used by Rails.
>
> Today, among other days, I noted one more method missing  
> documentation.
>
> I''ve read the past year about nested layouts in some blog I
don''t
> remember.
>
> Today I had to write a new application and needed the nested layouts  
> again.
>
> First, I looked at the documentation, as I use to do. Didn''t find.
> Then I
> looked at my other project code and found how, although I couldn''t
> find
> this feature documented.
>
> Into the documentation there are references for:
> render (ActionView::TemplateHandlers::Compilable)
> render (ActionView::TemplateHandler)
>
> But none of them had any documentation available (although I''m not
> sure
> these are the methods I should be looking for. Maybe it should be  
> "render
> (ActionController::Base)").
>Which is there as far as I can tell:
http://api.rubyonrails.com/classes/ActionController/Base.html#M000848>
> Well, the requirements are quite simple, so is the solution, but  
> finding it
> on documentations is impossible, unless I''m missing something.
>
> To keep it clear, here is the actual case:
>
> I want to have a master layout (application.erb) and another layout
> (another.erb) for the AnothersController, based on master layout.
>
> application.erb:
> <html>
> ...
> <%= yield :further_header %>
> ...
> </html>
>
> another.erb:
> <% content_for :further_header do %>
> Further content here
> <% end %>
>
> <%= render ''layouts/application'' %>
>
> Quite simple, don''t you think? So what am I complaining about?
This
> is a
> very useful hidden feature. It is not documented. Even worse, the  
> render
> method is not documented. And even if I didn''t care about others  
> reaching
> this feature, I would care if this feature will continue working in  
> the
> next Rails releases. Once a feature is documented, there is a great  
> chance
> it will continue to be supported...
>Well the key thing is for there to be tests describing the  
functionality. Tests get automatically checked, docs
don''t> I would like to help documenting such missing documentation, but I  
> need some
> instructions how can I do that: how to make patches, and need to  
> know how
> do these methods actually work.
lifo''s docrails project on github is the place to go.

Fred

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Talk" group.
To post to this group, send email to
rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
To unsubscribe from this group, send email to
rubyonrails-talk+unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
For more options, visit this group at
http://groups.google.com/group/rubyonrails-talk?hl=en
-~----------~----~----~----~------~----~------~--~---

Russell Norris

2008-Sep-03 16:39 UTC

head link

Re: Rails lack of documentation (render nested layouts)

could not disagree more. but that''s another issue. ;)

On Wed, Sep 3, 2008 at 12:40 PM, Rodrigo Rosenfeld Rosas
<lbocseg-/E1597aS9LRfJ/NunPodnw@public.gmane.org>
wrote:> This assumes everyone knows about test units. There shouldn''t be
the case.
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Talk" group.
To post to this group, send email to
rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
To unsubscribe from this group, send email to
rubyonrails-talk+unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
For more options, visit this group at
http://groups.google.com/group/rubyonrails-talk?hl=en
-~----------~----~----~----~------~----~------~--~---

Rodrigo Rosenfeld Rosas

2008-Sep-03 16:40 UTC

head link

Re: Rails lack of documentation (render nested layouts)

Frederick Cheung wrote:
> 
> 
> On 2 Sep 2008, at 21:58, Rodrigo Rosenfeld Rosas wrote:
> 
>>
>> I''ve posted some days ago about the lack of proper
documentation for
>> the
>> testing framework used by Rails.
>>
>> Today, among other days, I noted one more method missing
>> documentation.
>>
>> I''ve read the past year about nested layouts in some blog I
don''t
>> remember.
>>
>> Today I had to write a new application and needed the nested layouts
>> again.
>>
>> First, I looked at the documentation, as I use to do. Didn''t
find.
>> Then I
>> looked at my other project code and found how, although I
couldn''t
>> find
>> this feature documented.
>>
>> Into the documentation there are references for:
>> render (ActionView::TemplateHandlers::Compilable)
>> render (ActionView::TemplateHandler)
>>
>> But none of them had any documentation available (although I''m
not
>> sure
>> these are the methods I should be looking for. Maybe it should be
>> "render
>> (ActionController::Base)").
>>
> Which is there as far as I can tell:
> http://api.rubyonrails.com/classes/ActionController/Base.html#M000848
The documentation is there, but if it is the right documentation to look
for, it doesn''t include description about the behaviour of specifying a
string as the "options" param. It only describes action rendering and
partial rendering.
>>
>> Well, the requirements are quite simple, so is the solution, but
>> finding it
>> on documentations is impossible, unless I''m missing something.
>>
>> To keep it clear, here is the actual case:
>>
>> I want to have a master layout (application.erb) and another layout
>> (another.erb) for the AnothersController, based on master layout.
>>
>> application.erb:
>> <html>
>> ...
>> <%= yield :further_header %>
>> ...
>> </html>
>>
>> another.erb:
>> <% content_for :further_header do %>
>> Further content here
>> <% end %>
>>
>> <%= render ''layouts/application'' %>
>>
>> Quite simple, don''t you think? So what am I complaining about?
This
>> is a
>> very useful hidden feature. It is not documented. Even worse, the
>> render
>> method is not documented. And even if I didn''t care about
others
>> reaching
>> this feature, I would care if this feature will continue working in
>> the
>> next Rails releases. Once a feature is documented, there is a great
>> chance
>> it will continue to be supported...
>>
> Well the key thing is for there to be tests describing the
> functionality. Tests get automatically checked, docs don''t
This assumes everyone knows about test units. There shouldn''t be the
case.
The documentation should also state the supported features... A change patch
should group the code change, the documentation change and the test unit
change, when they apply...
>> I would like to help documenting such missing documentation, but I
>> need some
>> instructions how can I do that: how to make patches, and need to
>> know how
>> do these methods actually work.
> 
> lifo''s docrails project on github is the place to go.
Thanks for pointing that, I''ll look forward that.

Rodrigo.



--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Talk" group.
To post to this group, send email to
rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
To unsubscribe from this group, send email to
rubyonrails-talk+unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
For more options, visit this group at
http://groups.google.com/group/rubyonrails-talk?hl=en
-~----------~----~----~----~------~----~------~--~---

Rodrigo Rosenfeld Rosas

2008-Sep-03 17:28 UTC

head link

Re: Rails lack of documentation (render nested layouts)

I agree with you that everybody would be benefited a lot if they know about
unit tests. But a framework should not expect this from the end user. It
should be up to (s)he to be enlighten...

Besides that, it is much easier to look for a feature in documentation than
in the test units...

That is what I meant...

Rodrigo.

Russell Norris wrote:
> 
> could not disagree more. but that''s another issue. ;)
> 
> On Wed, Sep 3, 2008 at 12:40 PM, Rodrigo Rosenfeld Rosas
> <lbocseg-/E1597aS9LRfJ/NunPodnw@public.gmane.org> wrote:
>> This assumes everyone knows about test units. There shouldn''t
be the
>> case.


--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Talk" group.
To post to this group, send email to
rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
To unsubscribe from this group, send email to
rubyonrails-talk+unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
For more options, visit this group at
http://groups.google.com/group/rubyonrails-talk?hl=en
-~----------~----~----~----~------~----~------~--~---

Frederick Cheung

2008-Sep-04 07:38 UTC

head link

Re: Rails lack of documentation (render nested layouts)

On 3 Sep 2008, at 19:28, Rodrigo Rosenfeld Rosas wrote:
>
> I agree with you that everybody would be benefited a lot if they  
> know about
> unit tests. But a framework should not expect this from the end  
> user. It
> should be up to (s)he to be enlighten...
>
> Besides that, it is much easier to look for a feature in  
> documentation than
> in the test units...
>That''s not what I was getting at: What I meant that it is easy to make
a small change that inadvertently changes how something behaves. At  
that point a unit tests guard against such inadvertent changes,  
documentation does not.

Fred> That is what I meant...
>
> Rodrigo.
>
> Russell Norris wrote:
>
>>
>> could not disagree more. but that''s another issue. ;)
>>
>> On Wed, Sep 3, 2008 at 12:40 PM, Rodrigo Rosenfeld Rosas
>> <lbocseg-/E1597aS9LRfJ/NunPodnw@public.gmane.org> wrote:
>>> This assumes everyone knows about test units. There
shouldn''t be the
>>> case.
>
>
>
> >

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Talk" group.
To post to this group, send email to
rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
To unsubscribe from this group, send email to
rubyonrails-talk+unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
For more options, visit this group at
http://groups.google.com/group/rubyonrails-talk?hl=en
-~----------~----~----~----~------~----~------~--~---

Abel

2008-Sep-04 08:34 UTC

head link

Re: Rails lack of documentation (render nested layouts)

Hi Rodrigo:

I know a screencast from railscasts.com that shows how to contribute
to Rails with patches. In the example, the author contributes some
documentation wich is precisely what you intend to do.

http://railscasts.com/episodes/50-contributing-to-rails

Enjoy.

On Sep 2, 10:58 pm, Rodrigo Rosenfeld Rosas
<lboc...-/E1597aS9LRfJ/NunPodnw@public.gmane.org>
wrote:> I''ve posted some days ago about the lack of proper documentation
for the
> testing framework used by Rails.
>
> Today, among other days, I noted one more method missing documentation.
>
> I''ve read the past year about nested layouts in some blog I
don''t remember.
>
> Today I had to write a new application and needed the nested layouts again.
>
> First, I looked at the documentation, as I use to do. Didn''t find.
Then I
> looked at my other project code and found how, although I couldn''t
find
> this feature documented.
>
> Into the documentation there are references for:
> render (ActionView::TemplateHandlers::Compilable)
> render (ActionView::TemplateHandler)
>
> But none of them had any documentation available (although I''m not
sure
> these are the methods I should be looking for. Maybe it should be
"render
> (ActionController::Base)").
>
> Well, the requirements are quite simple, so is the solution, but finding it
> on documentations is impossible, unless I''m missing something.
>
> To keep it clear, here is the actual case:
>
> I want to have a master layout (application.erb) and another layout
> (another.erb) for the AnothersController, based on master layout.
>
> application.erb:
> <html>
> ...
> <%= yield :further_header %>
> ...
> </html>
>
> another.erb:
> <% content_for :further_header do %>
> Further content here
> <% end %>
>
> <%= render ''layouts/application'' %>
>
> Quite simple, don''t you think? So what am I complaining about?
This is a
> very useful hidden feature. It is not documented. Even worse, the render
> method is not documented. And even if I didn''t care about others
reaching
> this feature, I would care if this feature will continue working in the
> next Rails releases. Once a feature is documented, there is a great chance
> it will continue to be supported...
>
> I would like to help documenting such missing documentation, but I need
some
> instructions how can I do that: how to make patches, and need to know how
> do these methods actually work.
>
> Thanks in advance,
>
> Rodrigo.--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Talk" group.
To post to this group, send email to
rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
To unsubscribe from this group, send email to
rubyonrails-talk+unsubscribe@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/rubyonrails-talk?hl=en
-~----------~----~----~----~------~----~------~--~---

Rodrigo Rosenfeld Rosas

2008-Sep-05 13:45 UTC

head link

Re: Rails lack of documentation (render nested layouts)

Thanks, Abel. I''ve downloaded and watched it.

Frederick Cheung has also noted about lifo''s docrails project on
github.

It seems more interesting, and now I''m playing a bit with git, before
trying
to contribute.

The next step is to understand the related source code. When trying to get
the picture, I''ve found the following piece of uncommented code that I
couldn''t understand. I tried to ask on ruby-talk newsgroup, but no one
answered...

def templates_in_path
  (Dir.glob("#{@path}/**/*/**") |
Dir.glob("#{@path}/**")).each do |file|
    unless File.directory?(file)
      yield Template.new(file.split("#{self}/").last, self)
    end
  end
end

That got me intrigued. What is the difference between
Dir.glob("#{@path}/**/*/**") | Dir.glob("#{@path}/**")
and just
Dir.glob("#{@path}/**")
?

Thanks,

Rodrigo.

Abel wrote:
> 
> Hi Rodrigo:
> 
> I know a screencast from railscasts.com that shows how to contribute
> to Rails with patches. In the example, the author contributes some
> documentation wich is precisely what you intend to do.
> 
> http://railscasts.com/episodes/50-contributing-to-rails
> 
> Enjoy.


--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Talk" group.
To post to this group, send email to
rubyonrails-talk-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
To unsubscribe from this group, send email to
rubyonrails-talk+unsubscribe-/JYPxA39Uh5TLH3MbocFFw@public.gmane.org
For more options, visit this group at
http://groups.google.com/group/rubyonrails-talk?hl=en
-~----------~----~----~----~------~----~------~--~---

Rails - Sep 2008 - Rails lack of documentation (render nested layouts)

Rails lack of documentation (render nested layouts)

Re: Rails lack of documentation (render nested layouts)

Re: Rails lack of documentation (render nested layouts)

Re: Rails lack of documentation (render nested layouts)

Re: Rails lack of documentation (render nested layouts)

Re: Rails lack of documentation (render nested layouts)

Re: Rails lack of documentation (render nested layouts)

Re: Rails lack of documentation (render nested layouts)