Overview

HTML

CSS/SCSS

We use Bootstrap.

JavaScript

We use jQuery-Library.

Bitbucket

This chapter contains description of the formal requirements or standards regarding commits in Bitbucket.

TYPO3

This chapter contains description of the formal requirements or standards regarding coding that you should ad here to when you develop TYPO3 extensions or core parts.

Golden Rule!

Remember our rules always!

“90% of what is considered "impossible" is, in fact, possible. The other 10% will become possible with the passage of time & technology.”

Hideo Kojima

HTML

Syntax

  • Don't capitalize tags, including the doctype.
  • Use soft tabs with two spaces—they're the only way to guarantee code renders the same in any environment.
  • Nested elements should be indented once (two spaces).
  • Always use double quotes, never single quotes, on attributes.
  • Don't include a trailing slash in self-closing elements—the HTML5 spec says they're optional.
  • Don’t omit optional closing tags (e.g. </li> or </body>).
				
<!doctype html>
<html>
  <head>
    <itle>Page title</title>
  </head>
  <body>
    <img src="images/company-logo.png" alt="Company">
    <h1 class="hello-world">Hello, world!</h1>
  </body>
</html>

CSS and JavaScript includes

Per HTML5 spec, typically there is no need to specify a type when including CSS and JavaScript files as text/css and text/javascript are their respective defaults.

HTML5 spec links

				
<!-- External CSS -->
<link rel="stylesheet" href="code-guide.css">

<!-- In-document CSS -->
<style>
  /* ... */
</style>

<!-- JavaScript -->
<script src="code-guide.js"></script>

Practicality over purity

Strive to maintain HTML standards and semantics, but not at the expense of practicality. Use the least amount of markup with the fewest intricacies whenever possible.

Attribute order

HTML attributes should come in this particular order for easier reading of code.

  • class
  • id, name
  • data-*
  • src, for, type, href, value
  • title, alt
  • role, aria-*

Classes make for great reusable components, so they come first. Ids are more specific and should be used sparingly (e.g., for in-page bookmarks), so they come second.

				
<a class="..." id="..." data-toggle="modal" href="#">
  Example link
</a>

<input class="form-control" type="text">

<img src="..." alt="...">

Boolean attributes

A boolean attribute is one that needs no declared value. XHTML required you to declare a value, but HTML5 has no such requirement.

For further reading, consult the WhatWG section on boolean attributes:

The presence of a boolean attribute on an element represents the true value, and the absence of the attribute represents the false value.

If you must include the attribute's value, and you don't need to, follow this WhatWG guideline:

If the attribute is present, its value must either be the empty string or [...] the attribute's canonical name, with no leading or trailing whitespace.

In short, don't add a value.

				
<input type="text" disabled>

<input type="checkbox" value="1" checked>

<select>
  <option value="1" selected>1</option>
</select>

Reducing markup

Whenever possible, avoid superfluous parent elements when writing HTML. Many times this requires iteration and refactoring, but produces less HTML. Take the following example:

				
<!-- Not so great -->
<span class="avatar">
  <img src="...">
</span>

<!-- Better -->
<img class="avatar" src="...">

JavaScript generated markup

Writing markup in a JavaScript file makes the content harder to find, harder to edit, and less performant. Avoid it whenever possible.

CSS

Syntax

  • Use soft tabs with two spaces—they're the only way to guarantee code renders the same in any environment.
  • When grouping selectors, keep individual selectors to a single line.
  • Include one space before the opening brace of declaration blocks for legibility.
  • Place closing braces of declaration blocks on a new line.
  • Include one space after : for each declaration.
  • Each declaration should appear on its own line for more accurate error reporting.
  • End all declarations with a semi-colon. The last declaration's is optional, but your code is more error prone without it.
  • Comma-separated property values should include a space after each comma (e.g., box-shadow).
  • Don't include spaces after commas within rgb(), rgba(), hsl(), hsla(), or rect() values. This helps differentiate multiple color values (comma, no space) from multiple property values (comma with space).
  • Don't prefix property values or color parameters with a leading zero (e.g., .5 instead of 0.5 and -.5px instead of -0.5px).
  • Lowercase all hex values, e.g., #fff. Lowercase letters are much easier to discern when scanning a document as they tend to have more unique shapes.
  • Use shorthand hex values where available, e.g., #fff instead of #ffffff.
  • Quote attribute values in selectors, e.g., input[type="text"]. They’re only optional in some cases, and it’s a good practice for consistency.
  • Avoid specifying units for zero values, e.g., margin: 0; instead of margin: 0px;.

Questions on the terms used here? See the syntax section of the Cascading Style Sheets article on Wikipedia.

				
/* Bad CSS */
.selector, .selector-secondary, .selector[type=text] {
  padding:15px;
  margin:0px 0px 15px;
  background-color:rgba(0, 0, 0, 0.5);
  box-shadow:0px 1px 2px #CCC,inset 0 1px 0 #FFFFFF
}

/* Good CSS */
.selector,
.selector-secondary,
.selector[type="text"] {
  padding: 15px;
  margin-bottom: 15px;
  background-color: rgba(0,0,0,.5);
  box-shadow: 0 1px 2px #ccc, inset 0 1px 0 #fff;
}

Declaration order

Related property declarations should be grouped together following the order:

  1. Positioning
  2. Box model
  3. Typographic
  4. Visual
  5. Misc

Positioning comes first because it can remove an element from the normal flow of the document and override box model related styles. The box model comes next as it dictates a component's dimensions and placement.

Everything else takes place inside the component or without impacting the previous two sections, and thus they come last.

For a complete list of properties and their order, please see the Bootstrap property order for Stylelint.

				
.declaration-order {
  /* Positioning */
  position: absolute;
  top: 0;
  right: 0;
  bottom: 0;
  left: 0;
  z-index: 100;

  /* Box-model */
  display: block;
  float: right;
  width: 100px;
  height: 100px;

  /* Typography */
  font: normal 13px "Helvetica Neue", sans-serif;
  line-height: 1.5;
  color: #333;
  text-align: center;

  /* Visual */
  background-color: #f5f5f5;
  border: 1px solid #e5e5e5;
  border-radius: 3px;

  /* Misc */
  opacity: 1;
}

Don't use @import

Compared to <link>s, @import is slower, adds extra page requests, and can cause other unforeseen problems. Avoid them and instead opt for an alternate approach:

  • Use multiple <link> elements
  • Compile your CSS with a preprocessor like Sass or Less into a single file
  • Concatenate your CSS files with features provided in Rails, Jekyll, and other environments

For more information, read this article by Steve Souders.

				
<!-- Use link elements -->
<link rel="stylesheet" href="core.css">

<!-- Avoid @imports -->
<style>
  @import url("more.css");
</style>

Media query placement

Place media queries as close to their relevant rule sets whenever possible. Don't bundle them all in a separate stylesheet or at the end of the document. Doing so only makes it easier for folks to miss them in the future. Here's a typical setup.

				
.element { ... }
.element-avatar { ... }
.element-selected { ... }

@media (min-width: 480px) {
  .element { ...}
  .element-avatar { ... }
  .element-selected { ... }
}

Prefixed properties

When using vendor prefixed properties, indent each property such that the declaration's value lines up vertically for easy multi-line editing.

In Textmate, use Text → Edit Each Line in Selection (⌃⌘A). In Sublime Text 2, use Selection → Add Previous Line (⌃⇧↑) and Selection → Add Next Line (⌃⇧↓).

				
/* Prefixed properties */
.selector {
  -webkit-box-shadow: 0 1px 2px rgba(0,0,0,.15);
          box-shadow: 0 1px 2px rgba(0,0,0,.15);
}

Single declarations

In instances where a rule set includes only one declaration, consider removing line breaks for readability and faster editing. Any rule set with multiple declarations should be split to separate lines.

The key factor here is error detection—e.g., a CSS validator stating you have a syntax error on Line 183. With a single declaration, there's no missing it. With multiple declarations, separate lines is a must for your sanity.

				
/* Single declarations on one line */
.span1 { width: 60px; }
.span2 { width: 140px; }
.span3 { width: 220px; }

/* Multiple declarations, one per line */
.sprite {
  display: inline-block;
  width: 16px;
  height: 15px;
  background-image: url("../img/sprite.png");
}
.icon           { background-position: 0 0; }
.icon-home      { background-position: 0 -20px; }
.icon-account   { background-position: 0 -40px; }

Shorthand notation

Limit shorthand declaration usage to instances where you must explicitly set all available values. Frequently overused shorthand properties include:

  • padding
  • margin
  • font
  • background
  • border
  • border-radius

Usually we don't need to set all the values a shorthand property represents. For example, HTML headings only set top and bottom margin, so when necessary, only override those two values. A `0` value implies an override of either a browser default or previously specified value.

Excessive use of shorthand properties leads to sloppier code with unnecessary overrides and unintended side effects.

The Mozilla Developer Network has a great article on shorthand properties for those unfamiliar with notation and behavior.

				
/* Bad example */
.element {
  margin: 0 0 10px;
  background: red;
  background: url("image.jpg");
  border-radius: 3px 3px 0 0;
}

/* Good example */
.element {
  margin-bottom: 10px;
  background-color: red;
  background-image: url("image.jpg");
  border-top-left-radius: 3px;
  border-top-right-radius: 3px;
}

Nesting in Less and Sass

Avoid unnecessary nesting. Just because you can nest, doesn't mean you always should. Consider nesting only if you must scope styles to a parent and if there are multiple elements to be nested.

Additional reading:

				
// Without nesting
.table > thead > tr > th { … }
.table > thead > tr > td { … }

// With nesting
.table > thead > tr {
  > th { … }
  > td { … }
}

Operators in Less and Sass

For improved readability, wrap all math operations in parentheses with a single space between values, variables, and operators.

				
// Bad example
.element {
  margin: 10px 0 @variable*2 10px;
}

// Good example
.element {
  margin: 10px 0 (@variable * 2) 10px;
}

How to use BEM

The element name describes its purpose ("What is this?" — item, text, etc.), not its state ("What type, or what does it look like?" — red, big, etc.).

The structure of an element's full name is block-name__element-name. The element name is separated from the block name with a double underscore (__).

For further more Information please read this.

Elements can be nested inside each other.

You can have any number of nesting levels.

				
// Bad example, The structure of the full element name follows the pattern
// `block-name__element-name`
<form class="search-form">
	<div class="search-form__content">
		<input class="search-form__content__input">

		<button class="search-form__content__button">Search</button>
	</div>
</form>

// Good example, The structure of the full element name doesn't follow the pattern
// `block-name__element-name`
<form class="search-form">
    <div class="search-form__content">
        <input class="search-form__input">

        <button class="search-form__button">Search</button>
    </div>
</form>

Comments

Code is written and maintained by people. Ensure your code is descriptive, well commented, and approachable by others. Great code comments convey context or purpose. Do not simply reiterate a component or class name.

Be sure to write in complete sentences for larger comments and succinct phrases for general notes.

				
/* Bad example */
/* Modal header */
.modal-header {
  ...
}

/* Good example */
/* Wrapping element for .modal-title and .modal-close */
.modal-header {
  ...
}

Class names

  • Keep classes lowercase and use dashes (not underscores or camelCase). Dashes serve as natural breaks in related class (e.g., .btn and .btn-danger).
  • Avoid excessive and arbitrary shorthand notation. .btn is useful for button, but .s doesn't mean anything.
  • Keep classes as short and succinct as possible.
  • Use meaningful names; use structural or purposeful names over presentational.
  • Prefix classes based on the closest parent or base class.
  • Use .js-* classes to denote behavior (as opposed to style), but keep these classes out of your CSS.

It's also useful to apply many of these same rules when creating Sass and Less variable names.

				
/* Bad example */
.t { ... }
.red { ... }
.header { ... }

/* Good example */
.tweet { ... }
.important { ... }
.tweet-header { ... }
.tweetText { ... }

Selectors

  • Use classes over generic element tag for optimum rendering performance.
  • Avoid using several attribute selectors (e.g., [class^="..."]) on commonly occuring components. Browser performance is known to be impacted by these.
  • Keep selectors short and strive to limit the number of elements in each selector to three.
  • Scope classes to the closest parent only when necessary (e.g., when not using prefixed classes).

Additional reading:

				
/* Bad example */
span { ... }
.page-container #stream .stream-item .tweet .tweet-header .username { ... }
.avatar { ... }

/* Good example */
.avatar { ... }
.tweet-header .username { ... }
.tweet .avatar { ... }

Organization

  • Organize sections of code by component.
  • Develop a consistent commenting hierarchy.
  • Use consistent white space to your advantage when separating sections of code for scanning larger documents.
  • When using multiple CSS files, break them down by component instead of page. Pages can be rearranged and components moved.
				
/*
 * Component section heading
 */

.element { ... }


/*
 * Component section heading
 *
 * Sometimes you need to include optional context for the entire component. Do that up here if it's important enough.
 */

.element { ... }

/* Contextual sub-component or modifer */
.element-heading { ... }

Editor preferences

Set your editor to the following settings to avoid common code inconsistencies and dirty diffs:

  • Use soft-tabs set to two spaces.
  • Trim trailing white space on save.
  • Set encoding to UTF-8.
  • Add new line at end of files.

Consider documenting and applying these preferences to your project's .editorconfig file. For an example, see the one in Bootstrap. Learn more about EditorConfig.

TYPO3

Infos

  • Use only Core-Extensions or write one for Master with TYPO3-CG. Except of:
    • Mask, Mask-Export for Development.
    • "helhum/dotenv-connector": "^1.0.0",
    • "helhum/config-loader": "^0.9",
    • "helhum/typo3-console": "^5.0",
    • "helhum/env-ts": "^0.3.0",
    • "ichhabrecht/hide-used-content": "^0.2.0",
    • "georgringer/news": "^7.0",
    • "helhum/typoscript-rendering": "^2.2",
    • "reelworx/rx-shariff": "^12.1",
    • "apache-solr-for-typo3/solr": "^9.0",
    • "straschek-io/responsive-images": "^1.0",
    • "ichhabrecht/content-defender": "^3.0",
    • "georgringer/eventnews": "^3.0",
    Development:
    • "typo3/cms-tstemplate": "^9.5",
    • "typo3-ter/mask": "^4.1",
    • "ichhabrecht/mask-export": "^2.2",
    • "friendsofphp/php-cs-fixer": "dev-master",
    • "friendsoftypo3/extension-builder": "^9.10",
    • "ichhabrecht/filefill": "^2.0",
    • "sgalinski/lfeditor": "^5.1"
  • Use strictly fluid-Templates in TYPO3.
  • Do not use VHS-Extension and write your own ViewHelpers.
  • Official Coding Guidelines TYPO3

JavaScript

Variable names

Use camelCase for identifier names (variables and functions).

All names start with a letter.

				
firstName = "John";
lastName = "Doe";

price = 19.90;
tax = 0.20;

fullPrice = price + (price * tax);

Naming Conventions

Always use the same naming convention for all your code. For example:

  • Variable and function names written as camelCase
  • Global variables written in UPPERCASE (We don't, but it's quite common)
  • Constants (like PI) written in UPPERCASE

Spaces Around Operators

Always put spaces around operators ( = + - * / ), and after commas:

				
var x = y + z;
var values = ["Volvo", "Saab", "Fiat"];

Statement Rules

Always end a simple statement with a semicolon.

 

General rules for complex (compound) statements:

  • Put the opening bracket at the end of the first line.
  • Use one space before the opening bracket.
  • Put the closing bracket on a new line, without leading spaces.
  • Do not end a complex statement with a semicolon.

Simple

				
var values = ["Volvo", "Saab", "Fiat"];

var person = {
  firstName: "John",
  lastName: "Doe",
  age: 50,
  eyeColor: "blue"
};

Functions

				
function toCelsius(fahrenheit) {
  return (5 / 9) * (fahrenheit - 32);
}

Loops

				
for (i = 0; i < 5; i++) {
  x += i;
}

Conditionals

				
if (time < 20) {
  greeting = "Good day";
} else {
  greeting = "Good evening";
}

Object Rules

Place the opening bracket on the same line as the object name.

  • Use colon plus one space between each property and its value.
  • Use quotes around string values, not around numeric values.
  • Do not add a comma after the last property-value pair.
  • Place the closing bracket on a new line, without leading spaces.
  • Always end an object definition with a semicolon.
				
var person = {
  firstName: "John",
  lastName: "Doe",
  age: 50,
  eyeColor: "blue"
};

Compressed

				
var person = {firstName:"John", lastName:"Doe", age:50, eyeColor:"blue"};

Bitbucket

Branching strategy

				
Development of __features__:
1. Branch `feature/0000-xxx` from `master`
2. Pull request `feature/0000-my-feature` against `develop`
3. Pull request `develop` against `master` __OR__
Pull request `feature/0000-my-feature` against `master` (in case of simultaneous development of different features)

Development of __bugfixes__ while developing __features__
1. Stay in branch `feature/0000-my-feature` and commit bugfixes
2. Pull request `feature/0000-my-feature` against `develop`
3. Pull request `develop` against `master` __OR__
Pull request `feature/0000-my-feature` against `master` ()in case of simultaneous development of different features)

Development of __bugfixes__ for direct merge onto `master`
1. Branch `hotfix/0000-my-hotfix` from `master`
2. Pull request `hotfix/0000-my-hotfix` against `master`
3. Pull request `hotfix/0000-my-hotfix` against `develop`

`develop` and `master` are protected branches.
Unwanted changes in develop __MUST__ be reverted.

Branch names

				
Branch names are leant against git flow naming conventions (https://www.google.de/search?q=git+flow).
Branch names should be descriptive as possible and MUST NOT contain umlauts or other special characters.

Examples for valid branch names (XXXX = ticket number):

feature/XXXX-revise-header-logo
hotfix/XXXX-workaround-horizontal-scrolling
release/XXXX-startpage-refit

##### Examples for invalid branch names:

fix
rte-ändern
fix-something
bugfix/headerbereich-zu-gross

##### It is imaginable that a convention for branch names can derive from ticket titles:

hotfix/2657-Bestaetigung-Newsletter-entsprechend-DSGVO
feature/2437-redirect-einrichten
hotfix/2497-EZB-Fehlerhafte-EN-URL-auf-DE-Seite

Commit messages

				
Commit messages are leant against TYPO3's Commit Message rules (https://docs.typo3.org/typo3cms/ContributionWorkflowGuide/Appendix/GeneralTopics/CommitMessage.html)
and this excellent page: https://chris.beams.io/posts/git-commit/.

> 1. Separate subject from body with a blank line
> 2. Limit the subject line to 50 characters
> 3. Capitalize the subject line
> 4. Do not end the subject line with a period
> 5. Use the imperative mood in the subject line
> 6. Wrap the body at 72 characters
> 7. Use the body to explain what and why vs. how

##### Good examples:

[FEATURE] #2489 Change initial view for libconnect
[BUGFIX] #2490 Remove encoded HTML output in displayNew template
[BUGFIX] #2494 #2496 Change EN localization for "intersection light" labels
[FEATURE] #2498 Decrease font size of title groups in EZB list
[FEATURE] #2670 Change wording of title text for external RTE links
[FEATURE] #2657 Add intro text to newsletter opt-in mail, change further wording
[FEATURE] #2500 Harmonize print styles for publisso (where possible)
[BUGFIX] #2496 Refactor condition for showing "yellow-red" titles in EZB list

##### Bad examples:

Erneute Änderung E-Mail senderName.value
[FEATURE] CKEditor Preset into PageTSconfig.ts
[HOTFIX] Fluid Template
CKEditor

Code Style

				
The file `.editorconfig` (https://editorconfig.org/) contains basic formatting specifications.
Please install it into your IDE.

TYPO3 installation

				
The project uses PHP 7.2

#### First install
composer install

Example .env

				
# Use 'Development' to avoid TYPO3 caching and verbose error output
# Use 'Production' for maximum performance and no error output
TYPO3_CONTEXT='Development/MO'

# Set arbitrary TYPO3_CONF_VARS values, following the convention: TYPO3__<section>[__<sub-section>]__property
# Credentials
TYPO3__DB__Connections__Default__dbname='db'
TYPO3__DB__Connections__Default__host='db'
TYPO3__DB__Connections__Default__password='db'
TYPO3__DB__Connections__Default__user='db'

## Site name
TYPO3__SYS__sitename='KUNDE (Development/MO)'

# Host specifics
## graphicsmagick path
TYPO3__GFX__processor_path='/usr/bin/'
TYPO3__GFX__processor_path_lzw='/usr/bin/'

# mails
#TYPO3__MAIL__transport='smtp'
#TYPO3__MAIL__transport_smtp_server='http://KUNDE.de.ddev.local:8025'

## realurl/ hostnames
# Secrets
TYPO3__SYS__encryptionKey='doesnotmatteronlocaldev'
TYPO3__BE__installToolPassword='$argon2i$v=19$m=16384,t=16,p=2$ZEVkSjdELjJsNG9obzU5NQ$slTjugeu0IWaJTcFndIh2vjozHB9DAZwHquvH9zHkFE'
TYPO3__SYS__trustedHostsPattern='KUNDE.de.ddev.local'

# optional values
TYPO3__BE__adminOnly='0'
TYPO3__BE__debug='0'

# A set of TYPO3 framework extensions (delivered within typo3/cms), which should be marked as active
# This configuration value is only evaluated during deployment, *NOT* during runtime!
# Set this value if you (for some reason) want different extensions active on different systems
# TYPO3_ACTIVE_FRAMEWORK_EXTENSIONS='belog,beuser,context_help,fluid_styled_content,extra_page_cm_options,felogin,filelist,impexp,info,info_pagetsconfig,lowlevel,perm,reports,rsaauth,rtehtmlarea,scheduler,setup,tstemplate,viewpage'

ENV__GLOBALS__ADM_PANEL='1'
ENV__GLOBALS__COMPRESS='0'
ENV__GLOBALS__CONCATENATE='0'
# ENV__GLOBALS__PIWIK_SITE_ID=2