Rationale

In HTML and CSS, just as in Python, consistent style makes code more maintainable and easier to develop.

Quick checklist for template code

Don’t use this

Use this instead

<b>

<th>, <dt><dfn>, <strong>

<br>

<li>, <div>...</div>

metal:fill-slot="pageheading"

metal:fill-slot="main"

<h3> (unless <h2> is used earlier in the page)

<h2>, <div>

<hr>

nothing, <table class="listing">

<i>

nothing, <em>, <var>

onclick=

MochiKit to attach event handlers to elements (and to create the elements too, if they do nothing without JavaScript).
See the JavaScriptStyleGuide for more information.

style= (unless this style is used nowhere else)

HTML elements, classes

<ul><li tal:repeat="bar bars"...

<ul tal:condition="bars"><li tal:repeat="bar bars"...

<div tal:replace=...
<span tal:replace=...

<tal:one-word-summary replace=...
<tal:one-word-summary replace=...
(functionally identical, but more informative for those reading the code later)

' (ASCII single quote used for an apostrophe), '

&#8217; oror

"foo" (ASCII double quotes), "

andorand

'foo' (ASCII single quotes)

andorand

Indentation

TAL precedence

When an element has multiple statements, they are executed in this order:

  1. define
  2. condition
  3. repeat
  4. content or replace
  5. attributes
  6. omit-tag

HTML guidelines

Comments

Don't give away implementation details in <!-- HTML comments -->. Instead, use code like this.

<tal:comment condition="nothing">
  Comment here.
</tal:comment>

Tables

Lists

Text and code to avoid

See UserInterfaceWording.

Defining a local macro that can be used in a page template

Use metal:define-macro like this:

<metal:define metal:define-macro="my-macro">
  <ul tal:condition="foobies">
    <li tal:repeat="foo foobies" tal:content="foo.name" />
  </ul>
</metal:define>

define-macro by itself defines the macro, but leaves the output untouched -- in other words, when processing the code snippet above the TAL engine generates an unordered list as output. You may also use names inside the macro as long as they are defined all in the contexts it is used, including its definition.

You can then access the macro from the template/macros namespace:

  <metal:use metal:use-macro="template/macros/my-macro" />

Reserved form parameter names

There are certain names for form controls that are reserved; for details see ReservedQueryParameters.

Unresolved issues

PageTemplateHacking (last edited 2011-11-23 20:28:08 by sinzui)