.tmpl code-formatting convention changes

 
From: "Shane Clintberg" <shaneclintberg@PROTECTED>
Date: July 29th 2005
 
Here's an "end-of-a-slow-work-week" update for you:
 
Inspired by the coding conventions doc Justin proposed, I've now done a once-over of all the template files in /dada/DADA/Template/templates/ to check their XHTML compliance. Had a nice little visit while I was there, too: made a couple of JavaScript tweaks along the way [which I'll summarize in a separate email], proofread some of the page content, and left behind a few comments for my next go-around.
 
At the same time, I also decided to tighten up and standardize the markup/coding conventions used in the .tmpl files. And in doing so, I made a few changes to those conventions, which I thought I should summarize here for anyone who's interested.
 
(Note: the word "formatting" in my CVS log comments refers only to the files' markup formatting, and not to the page layouts. Sorry, should've been more specific with that!)
 
 
1) <br /> tags separated
 
With minor exceptions, all the tags in the .tmpl files are separated by line breaks, so:
 
<p>Is there an <em>echo</em> in here?</p>
 
is coded as:
 
<p>
 Is there an
 <em>
  echo
 </em>
 in here?
</p>
 
Although this isn't the way most standalone webpages are coded, as far as templates are concerned it's very helpful to have things written out in long-form like this. (Kudos to the coder here!)
 
...So in the same spirit, I've put all the <br /> tags on their own lines, too. Most weren't...and now that they are they're much easier to find. It would be great if we continue to follow this convention from here forward.
 
 
2) indentation issues
 
As seen in the example above, separate lines in the templates are nested with single-space indentation. That's cool -- both the proper XHTML nesting & the single-space indentation were double-checked in my first go-around, and should now be golden.
 
However, I was running into problems when trying to review the places that included HTML::Template code (that is, all the comments that begin with "<!-- TMPL_" ). The reason for that trouble was that the HTML::Template code was indented with tabs rather than single spaces:
 
<!-- tmpl_if foo -->
     <!-- tmpl_loop bar -->
     <!-- /tmpl_loop -->
<!-- /tmpl_if -->
 
...and then the HTML was nested within that (with blank lines to separate one from the other):
 
<!-- tmpl_if foo -->
 
<p>
 Is there an
 <em>
 
     <!-- tmpl_loop bar -->
 
       echo
 
     <!-- /tmpl_loop -->
 
 </em>
 in here?
</p>
 
<!-- /tmpl_if -->
 
In this simple example, it's easy enough to find the word "echo", to understand where it fits in the bigger scheme, and to add to, change, or delete from it if necessary. But in the actual templates, having big chunks of code shoved to the right like this was making  it considerably harder to parse -- especially when the HTML::Template code was nested more than one tab deep.
 
So to make things easier for myself I removed the nesting altogether, so that each coding type is formatted independently of the other:
 
<!-- tmpl_if foo -->
 
<p>
 Is there an
 <em>
 
     <!-- tmpl_loop bar -->
 
  echo
 
     <!-- /tmpl_loop -->
 
 </em>
 in here?
</p>
 
<!-- /tmpl_if -->
 
That can be good enough for me, I suppose, and I'm sure it's even easier for people whose text editors automatically color-code comments differently from everything else. But with all those blank lines still in there it's really not the best solution, in my opinion.
 
So, following an example I found over in the W3C, I'd like to propose that we nest all HTML::Template code within the regular flow of the HTML, as follows:
 
<!-- TMPL_IF FOO -->
<p>
 Is there an
 <em>
  <!-- TMPL_LOOP BAR -->
  echo
  <!-- /TMPL_LOOP -->
 </em>
 in here?
</p>
<!-- /TMPL_IF -->
 
As shown, this would also -- preferably, anyway -- mean standardizing the HTML::Template code to allcaps, which I'll be more than happy to do during my second go-around. (Right now, the templates' HTML::Template code isn't standardized at all: some is already allcaps, some is lowercase, and some is mixed.)
 
I like this latter option the best because I find it the cleanest...but ultimately, Justin's the guy who'll be looking at these templates more than anyone else -- and, hey, it's his program! -- so I'll leave the final decision to whichever one he prefers.
 
...So which will it be, J.? Change things back to the way they were before, leave 'em as I have 'em now, or change 'em to follow the "no-blank-lines-needed" convention?
 
 
3) un-separating sections
 
Besides all the blank lines separating the HTML and the HTML::Template code, many of the templates also had additional blank lines in them to visually distinguish different sections, or to separate one chunk of code (like a form or table) from the rest of the flow. However, the combination of the two became quite a muddle in certain spots...and there were errors that I almost missed seeing as a result.
 
So to make the overall structure easier to review in the short term, I deleted all those "extra" blank-line section separators. Temporarily.
 
I'll put them back in when I'm done with my review of the templates' overall structure. Please bear with the current state of things in the meantime.
 
 
P.S. - Given the extent of these changes, other devs working on the templates are advised to update their local repositories before doing so.

Post:
mailto:dadadev@PROTECTED

Unsubscribe:
http://mojo.skazat.com/cgi-bin/dada/mail.cgi/u/dadadev/

List Information:
http://mojo.skazat.com/cgi-bin/dada/mail.cgi/list/dadadev

Archive:
http://mojo.skazat.com/cgi-bin/dada/mail.cgi/archive/dadadev

 
rss/atom
‹ Re: unsuscribe
Index
.tmpl JavaScript changes ›
  • This mailing list is a public mailing list - anyone may join or leave, at any time.
  • This mailing list is a group discussion list (unmoderated)

  • Start a new thread, email: dadadev@dadamailproject.com

This is the developer discussion mailing list for Dada Mail.

If you are just looking for support Dada Mail, consult the message boards at:

https://forum.dadamailproject.com

Documentation for Dada Mail:

https://dadamailproject.com/d

Specifically, see the Error FAQ:

https://dadamailproject.com/d/FAQ-errors.pod.html

To post to this list, send a message to:

mailto:dadadev@dadamailproject.com

All subscribers of this list may post to the list itself.

Topics that are welcome:

  • Constructive critiques on the program (I like, "x", but, "y" needs some work - here's an idea on how to make this better...)
  • Bug/Error reports
  • Bug fixes
  • Request For Comments on any changes to the program
  • Help customizing Dada Mail for your own needs
  • Patches
  • Language Translations
  • Support Documentation/Doc editing, FAQ's, etc.
  • Discussion of any changes that you would like to be committed to the next version of Dada Mail -

Dada Mail is on Github:

https://github.com/justingit/dada-mail/

If you would like to fork, branch, send over PRs, open up issues, etc.

Privacy Policy:

This Privacy Policy is for this mailing list, and this mailing list only.

Email addresses collection through this mailing list are used explicitly to work within this email discussion list.

We only collect email addresses through our Closed-Loop Opt-In system.

We don't use your email address for any other purpose.

We won't be sharing your email address with any other entity.

Unsubscription can be done at any time. Please contact us at: justin@dadamailproject.com for any help regarding your subscription, including removal from the mailing list.

All mailing list messages sent from us will include a subscription removal link, which will allow you to remove yourself from this mailing list automatically, and permanently.

All consent to use your email address for any other purpose stated at the time of the mailing list subscription will also be revoked upon mailing list removal.