Code Demarcation standard for Magento Module Development

Magento core developers must comply with the Magento code demarcation standard.

This norm is recommended for third-party extension developers.

Some sections of the Magento code do not comply with the standard, but they are working to progressively improve this.

The norm has been established in the scope of our efforts to ensure the following:

Use RFC 2119 to interpret the “MUST,” “MUST NOT,” “REQUIRED,” “SHALL,” “SHALL NOT,” “SHOULD,” “SHOULD NOT,” “RECOMMENDED,” “MAY,” and “OPTIONAL” keywords.

For attribute names and values you must use meaningful unabbreviated lowercase words comprised of Latin characters concatenated with a hyphen (-)

Semantic representation may rely on ID attribute

• Forces engineers to think about reusable page components instead of unique singleton components.
• Reduces long-term maintenance efforts.

Acceptable PHTML template:

The following acceptable example is terse and uses an Accessible Rich Internet Applications (ARIA) approach.

Unacceptable combination of PHTML, JavaScript, and CSS files:

The following unacceptable example replaces a single PHTML file with a combination of a PHTML, JavaScript, and CSS files.

PHTML file:

JavaScript file:

CSS file:

You must follow the separation of presentation and content methodology

The following list will help you make a distinction between the actual meaning of a document, and how this meaning is presented to its readers:

The following list will help you make a distinction between the actual meaning of a document, and how this meaning is presented to its readers:

Content (Semantics) includes:

• logic
• information
• data
• model
• outline
• message

Presentation includes:

• aesthetic
• graphics
• design
• style
• visualization
• view

You must use semantic HTML markup only, and must not use presentation markup

Acceptable:

Unacceptable:

Visual representation must rely only on HTML class attributes, CSS pseudo-classes and pseudo-elements, HTML tags, and form element’s type attribute and form elements state attributes (example: disabled, checked).

As the first option, you are required to use HTML class attributes. In case this option is not applicable then it is recommended to use HTML tags and form element’s type attribute.

• Enforces clean, strict separation between visual and business logic layers.
• Allows frontend and backend teams to work independently.
• Allows changing look and feel without affecting business functionality, and vice versa.
• Enables frontend teams to clean up old styles quickly and easily when refactoring.

Acceptable CSS selectors:

Unacceptable CSS selectors:

You must not hard-code CSS styles in JavaScript files

Exception: CSS attributes where values must be calculated beyond the css-topics/LESS code.

• Simplifies change of the default look and feel by adding CSS classes to and removing them from elements.
• Improves style extensibility.
• Allows changing look and feel without affecting business functionality, and vice versa.
• Reduces long-term maintenance efforts by containing CSS styles in a single place.

Acceptable JavaScript widget file:

Unacceptable JavaScript file:

You must not use inline CSS styles inside HTML tags

• Improves style extensibility allowing engineers to overload styles easier by toggling classes
• Enforces clean, strict separation between visual presentation and markup.
• Enables frontend teams quickly and easily clean up old styles.

Acceptable PHTML template:

Unacceptable PHTML template:

Business logic must rely on only the form, form element name attributes, or data attributes

• Enforces clean, strict separation between visual and business logic layers.
• Allows frontend and backend teams to work independently.
• Allows changing business logic without affecting styling and vice versa.

Acceptable PHTML template:

Acceptable JavaScript file:

Unacceptable PHTML file:

Unacceptable JavaScript file:

You must assign HTML helper classes in JavaScript to modify presentation layer

HTML helper class names added in JavaScript REQUIRE underscore symbol (“_”) at the beginning and must be written in lowercase.

Acceptable:

Unacceptable:

You must not select DOM elements based on HTML structure

Allows frontend teams to modify markup and themes without affecting business logic.

Acceptable JavaScript file:

Unacceptable JavaScript file:

You must use jQuery templates to insert recurring markup into DOM structure

• Reinstates emphasis on jQuery templates. For more information, see JavaScript Coding Best Practices.
• Reduces long-term maintenance efforts by having markup code stored in one place.
• Simplifies frontend debugging efforts.

You must not hard-code inline CSS styles in PHP classes

• Reduces long-term maintenance efforts by having styles stored in one place.
• Simplifies debugging and reduces number of files to be modified
• Makes styles more extensible and easier to override when needed.

Acceptable PHP file:

Unacceptable PHP file:

You must not hard-code inline JavaScript in PHP classes

• Reduces long term maintenance by having frontend business logic stored in one place.
• Reduces the number of files to be modified.

Acceptable PHP file:

Acceptable PHTML file:

or

Acceptable PHTML file:

Unacceptable PHP file:

Unacceptable PHTML template:

You must not hard-code HTML markup (used in thetag) in PHP classes

• Reduces long-term maintenance efforts by having markup stored in one place.
• Reduces the number of files to be modified.

Acceptable PHP file:

Acceptable PHTML file:

Unacceptable PHP file:

Unacceptable PHTML file: