User Tools
Differences
This shows you the differences between two versions of the page.
| Next revision | Previous revision | ||
|
website_coding_guidelines [2014/03/18 14:51] admin angelegt |
website_coding_guidelines [2017/08/03 12:45] (current) |
||
|---|---|---|---|
| Line 5: | Line 5: | ||
| Please consider these examples: {{:wiki:mts-website-examples.zip|}} - some of them are referenced in the following text. | Please consider these examples: {{:wiki:mts-website-examples.zip|}} - some of them are referenced in the following text. | ||
| - | * Divide main layout css/less and blocks css/less like explained in the description of the example file. | + | === 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 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 combined class names for blocks consisting of module name and module view name (like "menu menu‐header") | ||
| - | * *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. | ||
| - | * Do not use Ids other than the main ids (see example files), use only classes for blocks and elements within. Blocks may be later inserted multiple times on the same page within the section. | ||
| * Use classes only if you need them (nav class="nav_menu" is redundant) | * 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. | * Encode special Characters in the HTML. Validate Your HTML on http://validator.w3.org. | ||
| - | * Use single line styles (not multiline and single line mixed) and use proper spacing (like space before and after curly brackets) | ||
| - | * Divide the blocks css and comment it (see example css files of Step 3). Always differentiate the block in css with comment. | ||
| * 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. | * 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. | ||
| - | * Use combined class names for blocks consisting of module name and module view name (like "menu menu-header" not "menuhead" or "headmenu"), do not use classes which indicate the layout (like top_left, top_right, lefter, formleft, button_yellow...) and use only english names (not "buchen", "cerca"). | + | * Do not put text in the HTML which is all uppercase or all lowercase. Use CSS instead: text-transform:uppercase; or text-transform:lowercase; |
| - | * Please use proper Indentation in the HTML (2 spaces) | + | |
| - | * Please use Google Webfonts, not the smiley hack:<code html><link href="http://fonts.googleapis.com/css?family=Open+Sans" rel="stylesheet" /></code> | + | |
| - | * Do not put text in the HTML which is all uppercase or all lowercase. Texts are dynamic and will be replaced by data from the database - use CSS instead: text-transform:uppercase; or text-transform:lowercase; | + | |
| - | * Please use JQuery UI where applicable. | + | |
| - | * You can use forms in blocks to wrap form elements, just not within the "editor" block. | + | |
| - | * .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. | + | |
| - | * .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)) | + | |
| * do not use inline styles. | * do not use inline styles. | ||
| - | * all elements within .editor-blocks should use less classes than possible (but they are allowed if really needed, for example if you need to differently styled <ul>). We have to create a new style in the cms manually for each class you use within the .editor-block. | + | * use the appropriate elements. Not "div.title" when it is a heading, use "h1".."h6". |
| - | * A "block" is the child of a "section". You can use another <div><div>-pair within the section, to use the full width, or a single <div>, if you don't need vertical positioning. If you need full width just for some blocks within a section, use the double-div-method within each block of that section, and let the section be 100% wide. | + | * Please use Google Webfonts, not the smiley hack or similar. |
| - | Example for blocks within sections which are 100% wide. The blocks themself are centered and use a fixed width. This may or may not be applicable for your project.<code html> | + | === CSS === |
| - | <footer> | + | |
| - | <div class="partner partner-footer"> | + | |
| - | <div><div> | + | |
| - | ... partner logos | + | |
| - | </div></div> | + | |
| - | </div><!.partner-footer> | + | |
| - | <div class="menu menu-footer"> | + | |
| - | <div><div> | + | |
| - | ... menu items | + | |
| - | </div></div> | + | |
| - | </div><!.menu-footer> | + | |
| - | </footer> | + | |
| - | </code> | + | |
| - | (Please see the example files provided (step-1-1.html)) | + | |
| - | + | * Divide main layout css/less and blocks css/less like explained in the description of the example file. | |
| - | * We provide you with a template for the sections and blocks. Please use these module and view names. | + | * 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. |
| - | * do not refer to a block in css/less with only it's class name. Always prefix with the element and use the last class name: not .menu-sidebar { }, but div.menu-sidebar { }. | + | * 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). |
| - | * 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. | + | * 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 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. | * 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. | ||
| - | * always put the element's name before the class. Not ".discountbtn" but "div.discountbtn". This is much easier to read and debug. | + | * 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 double classes at all, no ".editor.editor-content", just "div.editor-content" | + | * 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.\\ <code css>.clearfix() { |
| - | * use the appropriate elements. Not "div.title" when it is a heading, use "h1".."h6". | + | &:before, &:after { content:""; display:table; } |
| - | * you can define a css block for the module (e.g. div.menu { }) to set styles, which affect all different views of the block (div.menu-sidebar, div.menu-header ...). A common example is, that you don't want list style on all menus, then you can write something like: <code> | + | &:after { clear:both; } |
| - | div.menu ul { list-style:none; } | + | zoom:1; //IE 7 |
| - | ... (other div.menu styles) ... | + | } |
| - | div.menu-header li { display:inline-block; ... } | + | |
| - | ... (other div.menu-header styles) ... | + | |
| - | div.menu-sidebar li { display:block; ... } | + | |
| - | ... (other div.menu-sidebar styles) ... | + | |
| </code> | </code> | ||
| + | * 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:\\ <code javascript> | ||
| + | //menu-sidebar.js | ||
| + | | ||
| + | $(function() { | ||
| + | var b = $('.menu-sidebar'); | ||
| + | $('li.active', b).each( | ||
| + | .... | ||
| + | }); | ||
| + | </code> | ||
| + | | ||
| + | * Code efficiently. [[http://www.punkchip.com/2010/12/javascript-efficiency/|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 ** | ||
| + | * http://www.dreilaendertour.com/ | ||
| + | * http://www.marinaaltaprueba.com | ||
| + | * http://www.teutschhaus.it/ | ||
| + | * http://www.haus-gitschberg.com | ||
| + | * http://www.bike-trudnerhorn.com | ||
| + | * http://www.ristorante-da-anita.com/ | ||
| + | * http://www.ferienwohnung-vals.com/ | ||
| + | |||
| + | 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. | ||
| + | |||
| + | |||
| - | * set the default font-family and size on the body-tag in layout.css. | ||
| - | * define the default styles for headings in layout.css. This way you don't have to write every time the font-family within every blocks css, but only the differences from the default style. eg. | ||
| - | <code css>h1, h2, h3, h4, h5, h6 { fontfamily: "Open Sans", sansserif; fontweight: 400; font | ||
| - | size: 30px; color: #585858; marginbottom: 0.5em; } | ||
| - | h2 { fontsize: 18px; color: #c00518; } | ||
| - | h3 { ....</code> | ||
