ISML Linter

ISML Linter is a tool for examining if your project's templates follow a specified set of rules defined by your dev team. The available rules can be roughly grouped into:

• Styles that are defined by your team;
• Syntactic errors related to <is* > tags;
• Coding conventions recommended by Salesforce;
• Git conflicts that may accidentally be left unresolved;

Please feel free to make suggestions and help make this linter better. :) The set of currently available rules can be found below.

ISML Linter is also available as a VSCode extension, give it a try!

Installation

Prerequisite: Node.js (>=10.0.0).

Simply run in your project's root directory:

$ npm install isml-linter --save-dev

and add the following to package.json:

"scripts": {
    "init:isml":  "./node_modules/.bin/isml-linter --init",
    "lint:isml":  "./node_modules/.bin/isml-linter",
    "build:isml": "./node_modules/.bin/isml-linter --build",
    "fix:isml":   "./node_modules/.bin/isml-linter --autofix"
}

Here's what each script does:

• init:isml creates a config file;
• lint:isml simply lists the broken rules in the console;
• build:isml raises an error if there is any broken rule, thus can be used in your build process;
• fix:isml applies fixes for the enabled rules;

Configuration

After adding the above scripts to package.json, run the following command to generate a config file containing all available rules:

npm run init:isml

Alternatively, you can manually create a configuration file, make sure it is in the project root directory and has one of the following names: ismllinter.config.js, .ismllintrc.js or .ismllinter.json.

You can disable any rule by removing it from the config file. You may also find these configuration options useful:

| Config | Description | | ------------------- |:-----------------------------------------| | rootDir | The root directory under which the linter will run. Defaults to the directory where the package.json file is | | disableHtml5 | Disallows HTML5-defined unclosed tags, such as input, img and meta. Default: false | | ignoreUnparseable | Does not raise an error if an unparsable template is found. Default: false. Please check "Parse Modes - Tree" section below | | ignore | If a template path contains (as a substring) any string defined here, that template will be ignored by the linter | | indent | [Deprecated] Please check indent docs. Indentation size. Default: 4 | | linebreakStyle | unix or windows. Default: unix | | eslintConfig | Path to a eslint configuration file, to be applied within <isscript> tags. Default: .eslintrc.json | | enableCache | [Deprecated] Please check cache docs. Default: false | | autoFix | Applies fixes for enabled rules. Default: false | | printPartialResults | Limits issues or rule occurrences listed in the console to up to 30 items. Useful to get overall picture in case of many errors. Default: false | | verbose | Provides additional details of the linting process in the console. Default: false | | disableTreeParse | Enables only rules that do not depend on building an ISML tree. Check below when this might be useful. Default: false | | rules | Defines which rules to check. See available rules below |

Note: If you explicitly set "ignoreUnparseable" config to true, unparsable templates may contain errors that will not be detected by ISML Linter.

Example configuration:

{
    "rootDir": "./cartridges",
    "ignore": [
        "this_directory_is_to_be_ignored"
        "Email.isml"
    ],
    "rules" : {
        "no-br" : {}, 
        "enforce-require" : {}
    }
}

Note that according to the above configurations, the following templates would be ignored by ISML Linter:

• registerEmail.isml
• some/path/welcomeEmail.isml
• this_directory_is_to_be_ignored/producttile.isml
• some/path/this_directory_is_to_be_ignored/confirmationpage.isml

Parse Modes

Tree (disableTreeParse : false)

This is the default, and most powerful mode. It analyses the template and tries to build an "ISML DOM" tree to then apply the enabled rules. It is required that the template is parsable.

For example, if a template contains a snippet like the following, IT IS NOT considered a parsable template:

<isif condition="${aCondition}">
    <div class="info">
</isif>
        Some content
<isif condition="${aCondition}">
    </div>
</isif>

since the linter is not able to make an association between the opening and the corresponding closing <div> elements. This is the only known limitation for this parse mode. One possible solution to turn such templates into parsable is to replace that snippet by:

<isif condition="${aCondition}">
    <div class="info">
        <isinclude template="myTemplate" />
    </div>
<iselse/>
    <isinclude template="myTemplate" />
</isif>

There are other possible, potentially more "best practice" approaches, but it goes beyond the scope of this article.

And, to avoid possible doubts, here is an extra piece of information: it is allowed to have ISML tags within HTML tags, such as:

<div <isif ...> </isif> />

Line by Line (disableTreeParse : true)

This is a more robust, less powerful mode. It only has a few set of rules available and is indicated for cases where there are many, many lint errors and you want fix them gradually. It is also recommended in cases you don't want to force templates to be parsable (see previous section). This mode is ideally temporary, as it cannot take advantages of even some simple rules, such as indentation checking.

Command Line Interface

Please check CLI docs.

Git Hooks (Optional)

To prevent new errors to be introduced in next pushes, we recommend using some git hook npm package, such as husky or ghooks. The following example works for ghook:

"config": {
    "ghooks": {
      "pre-push": "npm run build:isml"
    }
}

API

Check the API docs.

Available Rules

Please check the Generic Configurations for Rules page.

| Rule | Description | | ------------------------------------------------------------------------------------ |:-----------------------------------------| | :exclamation: no-br | [Deprecated] Disallows <br/> tags. Enable this rule if you prefer to use CSS to handle vertical spacing | | no-git-conflict | Disallows unresolved Git conflicts | | no-import-package | Disallows importPackage() function. It is recommended by Salesforce to use require() instead | | :exclamation: no-isscript | [Deprecated] Disallows <isscript/> tag in template. Enable this rule if you prefer logic to be kept in a separate .ds/.js file | | :wrench: no-trailing-spaces | Disallows trailing blank spaces | | :wrench: no-space-only-lines | Disallows lines that contain only blank spaces, i.e., unnecessarily indented | | no-inline-style | Disallows use of style HTML attribute. Enable this rule if you prefer style to be fully handled via CSS | | :wrench: no-tabs | Disallows use of tabs | | enforce-isprint | [KNOWN BUG] Enforces every ${string} to be wrapped by an <isprint/> tag | | enforce-require | Disallows direct calls to a DigitalScript class, such as in:var PaymentMgr = dw.order.PaymentMgr;For this case, it is recommended to use instead:var PaymentMgr = require('dw/order/PaymentMgr'); | | lowercase-filename | Disallows template names to have uppercase characters | | max-lines | Limits the size of templates | | :small_orange_diamond: no-hardcode | Disallows hardcoded strings outside ISML expressions | | :wrench: :small_orange_diamond: indent | Sets indentation size | | :small_orange_diamond: no-require-in-loop | No require() calls from within a loop in the template | | :small_orange_diamond: no-embedded-isml | Disallows embedded isml tags, such as in <div <isif /> />, except for <isprint /> | | :small_orange_diamond: max-depth | Sets the maximum of nested elements in a template | | :small_orange_diamond: disallow-tags | Disallows tags specified at rule level | | :small_orange_diamond: one-element-per-line | One element per line | | :wrench: :small_orange_diamond: leading-iscontent | Ensures <iscontent> tag is the first element in the template if present | | :wrench: :small_orange_diamond: leading-iscache | Ensures <iscache> tag is among the first element in the template if present | | :small_orange_diamond: no-deprecated-attrs | Disallows deprecated attributes or attribute values | | :small_orange_diamond: contextual-attrs | Disallows presence of mutually exclusive attributes | | :small_orange_diamond: custom-tags | Checks if "util/modules" template is actually needed or if it is missing | | :wrench: :small_orange_diamond: eslint-to-isscript | Applies ESLint rules to <isscript> tag content | | :wrench: :small_orange_diamond: no-iselse-slash | Disallows self-closing <iselse> and <iselseif> tags | | :small_orange_diamond: empty-eof | Enforces a empty line at the end of the template | | :small_orange_diamond: align-isset | Aligns contiguous <isset> tags attributes' columns | | :small_orange_diamond: enforce-security | Enforces security measures | | :wrench: :small_orange_diamond: no-redundant-context | Prevents use of unnecessary contexts, such as dw.web.Resource | | :small_orange_diamond: strict-void-elements | Disallows closing tags for void elements, such as <input> and <img> |

You are more than welcome to contribute with us! Please check the contribute section.

Donations

This project was conceived by its author without any financial support, with the intention to help the community improving and speeding up any projects that involve ISML templates. If you think ISML Linter has helped you and your team, please consider making a donation, it will be much appreciated!

Iconography

:exclamation: Deprecated feature :boom: New feature :small_orange_diamond: Rules that require "disableTreeParse" configuration not to be true. :wrench: Auto-fix available