AEM IDE Documentation

Getting Started

The AEM IDE is an IntelliJ Platform plugin supporting the development of Adobe Experience Manager applications. It provides advanced coding assistance for components and .content.xml files.

Supported IDEs

AEM IDE is compatible with all IntelliJ Platform-based IDEs supporting at least XML language. Any features related to HTML or Java languages require their support in your IDE. In case of lack of these languages support, related functionalities will be unavailable. The currently supported IDEs are:

  • IntelliJ IDEA Ultimate — 2019.3+
  • IntelliJ IDEA Community — 2019.3+ FREE
  • IntelliJ IDEA Educational — 2019.3+
  • WebStorm — 2019.3+
  • Android Studio — build 193.0+ FREE
  • PhpStorm — 2019.3+
  • PyCharm Professional — 2019.3+
  • PyCharm Community — 2019.3+ FREE
  • PyCharm Educational — 2019.3+
  • RubyMine — 2019.3+
  • DataGrip — 2019.3+
  • GoLand — 2019.3+
  • AppCode — 2019.3+
  • Rider — 2019.3+
  • CLion — 2019.3+
  • MPS — 2019.3+
  • DataSpell — 2021.3 (eap)+

Installation

  1. Go to Settings or Preferences | Plugins. Select Marketplace tab and search for “AEM IDE”:
Preferences | Plugins | Marketplace
  1. Click the Install button.
  2. When installation is finished, click the Restart IDE button.

Activation

After AEM IDE is installed, it is disabled until you register it. To register the plugin go to Help | Register… and select “AEM IDE” in the Plugins section. You have 2 options: evaluating a trial and activating a license .

Evaluate a trial

To evaluate the trial select Start trial option and click the Start Trial button:

Evaluate a trial

Activate a license

If you have a valid plugin license purchased, select Activate AEM IDE option and choose one of 3 activation ways:

  • JetBrains account - if you purchased the plugin using your JetBrains account
  • Activation code - if you have the activation code
  • License server - if your organization manages licenses with Floating License Server
Activate a license

JCR roots

After a project is opened for the first time, AEM IDE should detect its JCR roots folders:

JCR Roots

In case your project has non-standard structure and JCR roots could not be detected, then you can mark folders as JCR roots manually:

AEM Version

AEM IDE features are AEM version aware. E.g., HTL data-sly-set block is available from HTL 1.4, and AEM IDE will report its usage as invalid in lower HTL versions. To set the actual AEM (and other AEM components) version and get the best code assistance experience, go to Settings or Preferences | Languages & Frameworks | AEM:

AEM Version

Troubleshoot

In case of any problems regarding the installation and configuration don’t bother to contact us.

HTL/Sightly Support

HTL Syntax Highlighting

AEM IDE offers clean and beautiful HTL files highlighting consistent with IntelliJ Platform languages highlighting. It highlights all HTL expressions and block statements (data-sly-* attributes), making them easy to distinguish from standard HTML content and attributes:

HTL Highlighting

Customize Colors

If the provided HTL files highlighting doesn’t suit your needs, it’s easy to customize colors to your requirements or taste. To customize colors, go to Settings or Preferences | Editor | Color Scheme | HTL/Sightly:

HTL Colors Page

HTL Code Completion

All completions provided by the AEM IDE are HTL version-aware. It means that if some feature is available from the newer HTL version than used in your project, then it won’t be completed. For example, consider the data-sly-set block statement available from HTL 1.4. If your project uses HTL 1.3 or lower, you won’t see it in the completion popup. AEM IDE supports completion for the following contexts:

  • Block statements - Beyond completing block statement attribute names, AEM IDE also automatically completes other parts of the selected statement like the expression part or suggests a variable names for data-sly-use, data-sly-list, and other statements assigned to variables.
  • Use object types - When the caret is in data-sly-use attribute value, AEM IDE completes all Sling Models, Use API Java implementors, HTL templates, and resources.
  • Local variables - AEM IDE completes all local variables available in the current caret position.
  • Script bindings/Global objects - AEM IDE completes all standard AEM script bindings, also known as global objects. If you have a custom script binding defined in your project, and you want it to be completed, you have to register it in Settings or Preferences | Languages & Frameworks | AEM in Custom HTL scripting variables section.
  • Objects properties - AEM IDE completes Java objects members available for the script. It lists public fields, methods, and properties (exposed via getters). It provides members from the entire inheritance chain, even resolving complex generic types.
  • Complex expressions properties - AEM IDE can complete properties even for complex expressions. For example, if the expression may return results of multiple different types having a common supertype, then only common properties will be completed. Example: (o.bigDecimalValue || 0).<caret> - only Number properties will be completed, because both BigDecimal and Integer inherit from Number.
  • Predefined properties - AEM IDE completes the predefined set of JCR nodes properties when completion is invoked on Map or its inheritors.
  • Implicit list objects and properties - If the caret is in the scope of list variables, then the implicit list variable (e.g., productList for data-sly-list.product) and its properties (e.g., productList.index) will be completed.
  • Expression options - AEM IDE provides completion for HTL expressions options. The options list is dependent on the context it is invoked for. E.g., begin, step, and end options will be completed only in data-sly-list/repeat block statement in HTL 1.4.
  • Display contexts - AEM IDE completes all display contexts protecting against XSS.
  • HTL templates - When HTL templates variable is completed and the caret is inside of data-sly-call statement, all template parameters will be inserted automatically.
  • Template parameters - HTL template parameters can be completed when invoked in expression options list.
  • Sling resource types and paths - AEM IDE completes Sling resource types and paths. Completed resource types are /apps or /libs relative and AEM IDE will insert them only when necessary.

HTL Code Inspections

Similarly to completions, all HTL inspections implemented in AEM IDE are HTL version-aware. If some HTL feature is available from the newer HTL version than used in your project, then the inspection will provide an accurate report for the project HTL version. For example, if uri display context will be specified explicitly in <form action="${'/test/action' @ context='uri'}">...</form>, it will be reported as redundant for HTL 1.4, but not reported when HTL 1.3 or lower is used. AEM IDE implements the following code inspections:

  • Case-insensitive reference - HTL global objects and block variables can be referenced in a case-insensitive manner as a result of case-insensitive HTML attributes (e.g., data-sly-test.myVar can be referenced as MYVAR). It is not recommended to reference variables with case-insensitive names as it decreases readability.
  • Identifier shadows global object - HTL specification allows defining variables with the same names as global objects (properties, currentPage, wcmmode, etc.). However, shadowing global objects decreases code readability and can lead to bugs.
  • Incorrect parameter hint type - Parameter value in data-sly-template block is a template parameter hint and must be a simple string. It is often mistaken as the default parameter value, but its actual purpose is to explain to developer what should be the value of parameter.
  • Redundant attribute on data-sly-template host element - The host element of data-sly-template is never shown in the rendered content, so data-sly-attribute, data-sly-element or any HTML attributes added to the element will not affect the rendered output and are redundant.
  • Redundant display context - HTL protects against XSS risks out of the box by setting the default context option implicitly depending on the actual context. Therefore, explicit setting default context option is unnecessary in some cases and AEM IDE will report them as redundant.
  • Redundant expression - Expression in data-sly-template definition is not evaluated and does not have any effect.
  • Shadowed template - If there are multiple data-sly-template blocks with the same identifier in a file, then only the last one is effective. All preceding data-sly-template blocks are shadowed by the last one with the same identifier.
  • Unnecessary unwrapping - The <sly> element is automatically unwrapped if it does not contain data-sly-unwrap block evaluated to false.
  • Use of getter method name instead of property access syntax - Property access syntax is more concise and easier to write and read, so object.property is preferred over object.getProperty.
  • Variable used before declaration - Variable used before declaring attribute is unnatural to read. It is easier to read variable usages after declaration. Variable used before the declaration is also not compliant with HTL specification even if it works in Sling HTL implementation.
  • Wrong HTL string quotes - HTL string quotes must differ from the outer attribute quotes, e.g., <div data-sly-set.test="${properties.text || "Default"}"></div> will fail to compile because the same quote character wraps attribute value and is used in expression.
  • Wrong HTL block statement identifier - HTL specification strictly defines what data-sly-* attributes identifiers are required, optional or restricted.
  • Unresolved reference - AEM IDE detects and highlights all unresolved variables and properties.
  • Disallowed backslash in HTML attribute - The data-sly-use attribute value cannot contain backslash character.
  • Disallowed data-sly-attribute values - The data-sly-attribute block statement cannot be used with XSS-vulnerable attributes like style or on* (e.g., onclick).
  • Negative numbers not supported - Negative numbers are supported from HTL 1.4 version.
  • Disallowed spaces in a path - AEM IDE reports accidental spaces inserted in paths.
  • Unknown data-sly-* attribute - Any unknown or unsupported in the current project HTL version blocks statements are reported with precise information.
  • The data-sly-template block in disallowed block - The data-sly-template block cannot be placed under data-sly-test, data-sly-test, or data-sly-test.
  • Incorrect block on data-sly-template - The data-sly-template block cannot be combined with data-sly-unwrap block.
  • Incorrect display context - AEM IDE will report any issues related to the display context expression option. In case a wrong context value is provided, e.g., as a result of a typo, you will get the suggestion with the closest matching value.
  • Nested data-sly-template - HTL doesn’t allow to have nested data-sly-template blocks.
  • Unsupported keyword - Any keywords unsupported in the current project HTL version will be reported with the reason.

Most of the above inspections provide quick fixes allowing to fix the issue with a single click. In case an issue occurs multiple times in a file, it is possible to fix them all at once:

HTL References

AEM IDE implements references support allowing to navigate, search and refactor the following code symbols:

  • Java packages and classes
  • Java classes members
  • HTL block variables
  • HTL implicit list variables
  • HTL templates and parameters
  • resource types and paths

Go to declaration

To go to symbol declaration, use ⌘+Click / Ctrl+Click on the symbol or use Navigate | Go to Declaration or Usages action.

Search usages

References implementation allows searching usages of code symbols from other languages in HTL files. To find usage of a code symbol, put caret on the symbol and use ⌥+F7 / Alt+F7 or use Edit | Find Usages | Find Usages action.

HTL Refactoring

Refactoring support allows quick renaming of code symbols with automatic updates of all symbol usages in a file or project. To rename a symbol put caret on the symbol and use Shift+F6 or use Refactor | Rename action.

HTL Quick Documentation

AEM IDE provides support for displaying quick docs for all symbols available in HTL expressions. To see a doc, move the mouse pointer over symbol (requires enabling Settings or Preferences | Editor | Code Editing | Quick Documentation | Show quick documentation on hover), or put carer on the symbol and use Ctrl+J.

FileVault Content Files Support

FileVault Syntax Highlighting

AEM IDE offers clean and FileVault Content files highlighting consistent with IntelliJ Platform languages highlighting. It highlights arrays, types, dates, numbers, boolean values, etc., making it easier to find values you are interested in:

FileVault Content File Highlighting

Customize Colors

If the provided FileVault Content files highlighting doesn’t suit your needs, it’s easy to customize colors to your requirements or taste. To customize colors, go to Settings or Preferences | Editor | Color Scheme | FileVault:

FileVault Colors Page

FileVault Code Completion

AEM IDE provides completions in FileVault content files in the following contexts:

  • Sling resource types and paths - Completed resource types are /apps or /libs relative and AEM IDE will insert them only when necessary.
  • Property Types - AEM IDE completes property types in XML attribute values.

FileVault Code Inspections

AEM IDE implements the following code inspections:

  • Missing primary type - Every node in the FileVault Content file must define jcr:primaryType, and in case it’s missing, AEM IDE will report it.
  • Missing name value - The Name property value cannot be empty.
  • Incorrect property type - JCR properties values are typed. The FileVault Content files can define properties types explicitly, and in case of a typo or usage of non-existing type AEM IDE will report an error.
  • Forbidden character in property value - FileVault properties values cannot contain unescaped & and < characters, and AEM IDE will report their usage.
  • Invalid escape sequence - FileVault DocView implementation strictly defines allowed escape sequences, and any unknown escapes will be reported.
  • Invalid typed values - AEM IDE reports all incorrect typed values such as invalid numbers, boolean values, etc.
  • Generated property - AEM IDE reports FileVault properties considered as “junk” properties (mostly dynamically generated on running AEM instance) introducing unnecessary noise in FileVault content files.
  • Ignored property - AEM IDE reports FileVault properties ignored during loading data into JCR, e.g., jcr:created.
  • Missing namespace declaration - Missing namespace declaration may break parsing FileVault Content file while importing content to the content repository.
  • Invalid namespace mapping - JCR stores mapping of namespace prefixes to the URLs. Namespaces definitions in FileVault Content files must be the same as what is stored in JCR. Otherwise, the content import will fail. AEM IDE reports incorrect namespace mappings and allows to fix them automatically.
  • Unused namespace declaration - AEM IDE reports unused namespaces that can be removed.
  • Redundant property type - FileVault DocView implementation defines default property types for jcr:primaryType and jcr:mixinTypes (Name), and properties without explicit type definition (String). AEM IDE reports redundant types definitions making the content file less verbose and cleaner.

Most of the above inspections provide quick fixes allowing to fix the issue with a single click. In case an issue occurs multiple times in a file, it is possible to fix them all at once:

FileVault References

AEM IDE implements references support allowing to navigate, search and refactor Sling resource types and paths.

Go to declaration

To go to symbol declaration, use ⌘+Click / Ctrl+Click on the symbol or use Navigate | Go to Declaration or Usages action.

Search usages

References implementation allows searching usages of code symbols from other languages in FileVault content files. To find usage of a code symbol, put caret on the symbol and use ⌥+F7 / Alt+F7 or use Edit | Find Usages | Find Usages action.

FileVault Refactoring

Refactoring support allows quick renaming of code symbols with automatic updates of all symbol usages in a file or project. To rename a symbol put caret on the symbol and use Shift+F6 or use Refactor | Rename action.

FileVault Code Folding

Code folding allows folding code parts that can be presented in a cleaner way making reading the code faster. Default code folding for FileVault files can be configured in Settings or Preferences | Editor | General | Code Folding | FileVault:

FileVault Code Folding Settings

To fold code parts in editor use ⌘+- / Ctrl+NumPad -. To unfold code parts in editor use ⌘++ / Ctrl+NumPad +. Actual code can be previewed by moving mouse cursor over the folded code part.

XML entities

AEM IDE allows folding XML entities making the content files containing HTML content much easier to read and understand:

FileVault XML Entities Folding

Types folding

AEM IDE allows folding explicit properties types reducing the noise in files:

FileVault Types Folding

FileVault Inlay Hints

FileVault DocView implementation assigns jcr:primaryTypeand jcr:mixinTypes properties with the Name type. Also, properties without explicit type definition are assigned with String type by default. AEM IDE allows enabling inlay types hints for those types.

Enabling inlay types hint can be done in Setting or Preferences | Editor | Inlay Hints | FileVault:

FileVault Types Inlay Hints