Reable and maintainable templates

Discussions and requests related to new CMSimple features, plugins, templates etc. and how to develop.
Please don't ask for support at this forums!
Post Reply
cmb
Posts: 14225
Joined: Tue Jun 21, 2011 11:04 am
Location: Bingen, RLP, DE
Contact:

Reable and maintainable templates

Post by cmb » Sat Oct 21, 2017 5:14 pm

Hi!

In the following I like to present some of my personal preferences for writing readable and maintainable templates (actually, I have not designed a CMSimple_XH template for a long time, but the rules basically apply to view templates as well, of which I'd written a lot lately). Since these are my personal preferences, don't treat them as hard rules, but rather as suggestions.
  1. Use a good text editor which is able to apply good syntax highlighting to PHP template files – because this is what CMSimple_XH templates are (despite the filename extension .htm). Switch to PHP mode if necessary.
  2. Write readable HTML. For me, that includes
    1. Proper indentation – the amount of indenting spaces is very much personal preference; 4 maybe too much, so 1 or 2 may be preferable. Using tabs is also an option, but make sure not to mix tabs and spaces – that leads to unreadable templates depending on the editor settings.
    2. Wrap overlong lines with hard-coded line breaks. Not doing so requires either horizontal scrolling, or to let the editor do the wrapping, which often has suboptimal results.
    3. Keep CSS and JS out of the templates. Use CSS classes or other selectors to assign the desired styles and scripts to the elements. If possible, put the JS scripts at the bottom of the <html> element for faster processing of the HTML.
    4. (HTML) comments are good – meaningful structure with meaningful names is better, e.g. prefer

      Code: Select all

      <div class="tpl_main_content">
      over

      Code: Select all

      <!-- The main content area -->
      <div>
  3. Use PHP tags prudently, to avoid them destroying the readable HTML. For me, that includes:
    1. Don't add trailing semicolons. These are not required, and easily distract from the important parts.
    2. Printing text is best accomplished by using the short PHP echo tags (which are always available as of PHP 5.4.0). E.g.:

      Code: Select all

      <?=content()?>
    3. Indent such print tags in the same way you would indent respective HTML elements.
    4. Distinguish between HTML and plain text whenever you're printing something. Plain text should always be escaped with XH_hsc() to avoid invalid HTML and cross-site-scripting. All CMSimple_XH template functions are supposed to return HTML, so these must not be escaped. Language texts may be regarded as HTML, but it might be preferable to treat them as plain text.
    5. Avoid complex expressions or even multi-line code snippets. It's better to move them out of the template into a separate PHP file which defines respective functions, to include this file at the top of the template, and to simply call the function where appropriate.
    6. Do not indent non-printing PHP tags, as this make them more outstanding from the HTML.
    7. Conditionals and loops should prefer the "template syntax", e.g.

      Code: Select all

      <?php if ($some_condition):?>
          <?=newsbox('News02')?>
      <?php endif?>
      instead of

      Code: Select all

      <?php if ($some_condition) {?>
          <?=newsbox('News02')?>
      <?php }?>
    8. Nested conditionals and loops (which are probably rare for CMSimple_XH templates) should be indented after the opening <?php, e.g.

      Code: Select all

      <?php if ($cond1):?>
      <?php     if ($cond2):?>
          <!-- some HTML -->
      <?php     endif?>
      <?php endif?>
    9. Consider to abstract over global PHP variables. Firstly, complex array variables such as $pth are hard to write and read, and secondly, using such variables prevents CMSimple_XH from changing their representation. However, this kind of abstraction might better be left to the core.
Originally, I had planned to also write about $tpl_cf and $tpl_tx, but for time reasons I'm postponing this.

Anyhow, these are my personal preferences; your preferences may be considerably different and work better for you – that's fine! More important than any particular style preferences is to be consistent at least for each template. So if you modify an existing template, better stick with its style preferences (unless you're going to refactor the template completely).
Christoph M. Becker – Plugins for CMSimple_XH

Post Reply