Correct coding convention for embedded code on web page templates.

Question

I had come experience with PHP a time ago and now I'm learning to use Ruby on Rails. But one simple question bothered me in both these languages, so I think I can cross-post it to both tags.

As you know, one of the concepts there is that one can embed PHP or Ruby code into web page template. Then these statements are executed and result of its execution is inserted in certain places of the page, marked with "brackets" <%= ... %>.

Or... wait. We program Ruby/PHP, but not HTML. Maybe we should treat template as Ruby/PHP code, into which sometimes HTML markup is inserted? So the process is treated like that HTML are inserted into ruby code into the "brackets" %> ... <%.

These are two different approaches:

1. HTML page is the primary entity, and it is affected by code execution; or
2. code is the primary entity, and it is executed, while HTML snippets are inserted in certain places.

This philosophy leads to different possibilities in coding conventions: result of code execution influences the page If we adhere the first insight, then the code would look like this:

<p>
<% (1..10).foreach do |i| %>
Iteration number <strong><%= i %></strong>. <br/>
<% end %>
</p>

But if we stick to the second alternative, the code would be formatted like this:

<%
%><p><%
(1..10).foreach do |i|
  %>Iteration number <strong><%
  %><%= i %><%
  %></strong>. <br/><%
end
%>

How should the concept of templates be construed? What concepts do you, way more experienced Web developers, account for the coding convention?

Answer 1

Maybe you should look into Haml? I don't know if there's a php equivalent, but as far as Rails goes, it's somewhere in between the two schemes. It's not quite code centric. But when used right, all the raw html is prepared programatically.

In short everything is considered text to be directly outputted, unless prefixed with either a %, - or =. Which translate to html-tag, ruby code that doesn't output. Ruby code that does output. Haml then uses whitespacing to nest things properly, much like python does. Raw html outputs untouched but using % to specify a tag handles closing tags.

Sample:

#outer-div
 - @items.each do |i|
   %span.item
   = i
   %br

Outputs

<div id="outer-div">
  <span class="item"> 
    item
  </span>
  <br>
</div>

See the haml tutorial for more information.

To answer the central question. The bulk of any page is going to be HTML or raw text. We reduce the bulk of that text with includes and helpers, but it's still there. If there were a truly code centered approach my use of it would depend on the ratio of program logic to html. Personally I'd rather go with the html centered approach.

Answer 2

If this is in your View layer (and it should be), then the HTML is the primary entity. It's the most pertinent part of that layer -- marking up your data to display in meaningful ways to the user.

Even aside from that, your second example is nearly unreadable. I see what you're doing, but it took me a minute to wrap my brain around it. I've also never, ever seen View-layer code like your second example (and I would make it one of my priorities to change it wherever I saw it if it was in a project I was working on).

To be more concise: you're putting the emphasis on the wrong thing. In my opinion, readability trumps just about everything else. The coding style that produces the most readable code is therefore the most superior (ceteris paribus and YMMV, of course).

Answer 3

If you are interested in a code-oriented view, this is something you might try implementing as a pure Ruby DSL:

tag :p, :class => 'iterations-container' do
  (1..10).each do |i|
    text "Iteration number "
    tag :strong { text i }
    text "."
    tag :br
  end
end

Or perhaps instead of tag :p do ... end, you may favor tag.p do ... end.

Answer 4

I recommend doing only very simple logic in your template files. That way designers who can edit HTML can easily edit even those files to alter the layout if need be.