User Tools

Trace: • website_coding_guidelines

MTS Website Coding Guidelines

In order for us to easily understand eachothers code when working in a team and for quality assurance of our products we build these coding guidelines, which we recommend to be followed by all of our programmers.

Please consider these examples: mts-website-examples.zip - some of them are referenced in the following text.

HTML

  • A “block” is the child of a “section”. Use Ids only for sections (see example files) and use only classes for blocks and elements within. Blocks might be later inserted multiple times on the same page within the section.
  • We provide you with a template for the sections and blocks. Please use these module and view names. Within the blocks you are free to name the blocks like you want, just keep it clean and short, and use descriptive class names, describing the content, not the layout, of course.
  • *Do not* use CaMelCaSe in class names. <div class=“productDescription”> is not acceptable, please use “product-description” or “description” instead. Please try to avoid underscores.
  • Use single line styles which you break after 80-120 chars, so that they remain readable without horizontal scrolling.
  • Use combined class names for blocks consisting of module name and module view name (like “menu menu‐header”)
  • Use classes only if you need them (nav class=“nav_menu” is redundant)
  • Encode special Characters in the HTML. Validate Your HTML on http://validator.w3.org.
  • Closing a <div>-tag with class or id in the html must be commented with <! ‐‐.classname/#id‐‐ > (see example files), to see where a block ends. Other comments in HTML are not required.
  • Do not put text in the HTML which is all uppercase or all lowercase. Use CSS instead: text-transform:uppercase; or text-transform:lowercase;
  • do not use inline styles.
  • use the appropriate elements. Not “div.title” when it is a heading, use “h1”..“h6”.
  • Please use Google Webfonts, not the smiley hack or similar.

CSS

  • Divide main layout css/less and blocks css/less like explained in the description of the example file.
  • use a reset css before all other css. I provide you with one, see attached. do not change this, insert it right after the google webfont css or at the top of all other css.
  • always put the element's name before the class. Not “.discountbtn” but “div.discountbtn”. This is much easier to read and debug and less error prone. Note: This does not apply to editor-styles (see below).
  • our frontend converts images to data-uris. for this to be successful, the url has to be wrapped into single quotes: Please do not write background:url(../images/flower.png); but background:url('../images/flower.png'), else it won't be recognised from the system. Also, in most HTML IDEs, image urls are easier to spot.
  • .editor block and all other blocks must be independent from each other. if you delete the css/less for one block, the others must keep their layout.
  • do not use CSS-hacks. Write valid CSS. Use a class on the <HTML>-Element to refer to “ie”, “ie8”, “ie7” etc. - this later will be added automatically by the frontend, e.g. <html class=“ie ie8”> …
  • do not use double classes at all, no “.editor.editor-content”, just “div.editor-content”
  • please use proper spacing. A space needs to be before and after '{', after ':' and after ';'. Please no tabs.
  • set the default font-family and size on the body-tag in layout.css.
  • do not refer to a block in dependance to it's module name. not “.menu.menu-sidebar { }” but “div.menu-sidebar { }”
  • do not refer to a block in dependance of it's section. No “header nav” or “header div.menu”. <header> is a section, thus it can only be styled in “layout.css”. Do not refer to blocks in “layout.css”, only to sections or the body itself.
  • please always refer to inner block styles beginning from the block's container. This does not mean you need to explain the full DOM hierarchy in the less.
  • Do not use empty div elements for clearing (div class=clearar), use the short “overflow:hidden” on the container wherever applicable (which also clears the float), on blocks with floating and overflowing elements inside use css clearfix on the container.
    .clearfix() { 
  &:before, &:after { content:""; display:table; }
  &:after { clear:both; }
  zoom:1;  //IE 7
}
  • do not put the clearfix class on every block. the class name we provide for blocks must remain the same with no strings attached. Include it in the less-mixin for the block. Not acceptable: <div class=“offers offers-sidebar clearfix”> … </div>
Editor
  • the “editor” is a special block class. it's css is used in the backend and the frontend. In the backend, the class name like “.editor-content” is attached to the body of the editor, not to a div. Use “div.editor-content” (with the elements name) only if you need to style the container in the frontend. For all other stylings, like paragraphs, lists, etc., use “.editor-content p”, “.editor-content ul”, etc. The .editor-class is attached to the <body>-element when in the backend, thus div.editor-content only works in the frontend. This is okay and needed if you have to position only the block's container div.editor-content in the frontend, but for all elements within div.editor-content, don't use the elements name 'div.' in the css, otherwise we have to rewrite it to make it work in the backend editor.
  • .editor‐blocks may contain only <h1>‐<h6>, <p>, <strong>, <em>, <hr />, <br />, <img>, <ul>, <ol>, <li>, <table>, <caption>, <thead>, <tbody>, <tfoot>, <tr>, <td>, <blockquote>, <span> (only in rare cases, use <em> or <strong> instead of <span> wherever possible, <span> is not editable well with the editor-component we use in our cms (TinyMCE))
  • You can use forms in blocks to wrap form elements, just not within the “editor” block.
  • inside the editor-styles, for right floating img, use “img.align-right”, for left floating img, “img.align-left”. These are standard for .editor-blocks and the only classes which contain a reference to their layout. In other blocks, refer directly the element <img> for styling or use your own class.
  • Do not use tables for layouting. Tables are allowed within .editor-blocks, e.g. for price lists. If there are such, don't style tables globally, only within the css for the .editor, like .editor-content table { … }
  • for .editor-blocks, style at least all headings, from <h1>-<h6>, <p>, <ul> and <ol>, <img> (floating and inline) and <a> (hover and normal state).

Scripts

  • Please use JQuery UI and JQuery Tools where applicable. Don't use other libraries like Motools, Dojo, etc., please only JQuery.
  • Javascript should be coded modular like the blocks themselves.
  • It is important to end lines with semicolon not just newlines since the javascript code will we compressed with JSMin when in production.
  • Naming the JS-files
    If for example we have the module “menu” with the views “menu-sidebar” and “menu-header”, you can name one javascript file “menu.js”, which will be used in any case when either “menu-sidebar” or “menu-header” are on the page (but that's rather unusual, since js-code for the views in most cases differ). Most of the time you name the js-files like the views of the module, “menu-sidebar.js” and the other “menu-header.js”, distinct files for any of the views. Later the c-mts frontend will pick one or both of these js-files when the view of the module is on the page.
    Inside these files you refer to just this block, defining a variable for the element, and then giving it any selector you use in the closure as parameter, to limit them to that block, like:
        //menu-sidebar.js
 
    $(function() {
      var b = $('.menu-sidebar');
      $('li.active', b).each(
      ....
    });
  • Code efficiently. Please follow rules 1-4 in this article. We don't use CDN hosted files to guarantee the availability of the libraries.
  • To start you can put these js-files in one single folder. Later you will then distribute the files to the according module folders.
  • You may use any jQuery-validation plugin you like, for the balloons we suggest to use the tooltip-plugin from bootstrap (just that one module, please don't put the whole bootstrap code in the project).

You may also review the markup of our other sites - you will see they are all coded pretty much the same way. Please see

You can view the source, copy it and use Netbeans www.netbeans.org to indent the HTML Code, it has the Function pressing ALT+SHIFT+F. I'm sure you will get the similarities and code new pages this way.

Page Tools

MTS online wiki

Site Tools