isml-linter v5.43.9

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:

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.

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