search

Netcentric / aem-htl-style-guide

A style guide for the HTML Template Language (HTL), the templating language use by the Adobe Experience Manager (AEM).
MIT License
138 stars 50 forks source link

Reason for: 4.7 Always place block statements after the normal HTML attributes #25

Closed karollewandowski closed 5 years ago

karollewandowski commented 5 years ago

Hi guys, I'm working on AEM IntelliJ Plugin which supports HTL and got issue report about variables resolving. In such code: unresolved references variables are unresolved because in the plugin I assume that (according to HTL specification) identifiers scope for data-sly-use, data-sly-test, data-sly-set and data-sly-unwrap is specified as:

Scope: The identifier set by the * block element is global to the script and can be used anywhere after its declaration.

For me, the "after its declaration" phrase means that usage before the declaration is disallowed. Maybe I'm wrong with interpretation.

My question is: what is the reason for adding rule 4.7 to the style guide? In my opinion, code is hard to read when declarations are specified after actual usages and I would even add rule exactly opposite to the current 4.7 - to put HTL blocks always before any other attributes. Is there any technical reason for the current state or it was introduced for better code organization and putting standard attributes before HTL blocks was a random decision or a matter of taste? Maybe it's worth to change it to make code cleaner and follow HTL spec?

kwin commented 5 years ago

I guess the reason for rule 4.7 was just a matter of taste, and together with rule 4.2 such a usage before declaration is unlikely but not impossible. I tend to agree that it would most probably make more sense to put the attributes data-sly-... before any other attributes (also because things like data-sly-test are so important that they should be placed as first attribute to not get overlooked). So from my side it would be fine to change the rule 4.7 accordingly but I would like to hear other opinions as well.

Just out of curiosity: Is the "usage before declaration" pattern a real issue in any HTL compiler or does the Sling HTL implementation just work fine with it (although the HTL spec does not mandate that order)?

karollewandowski commented 5 years ago

Thanks for the quick reply, it sounds promising.

Just out of curiosity: Is the "usage before declaration" pattern a real issue in any HTL compiler or does the Sling HTL implementation just work fine with it (although the HTL spec does not mandate that order)?

It works fine in Sling, I'm not sure about other compilers (I heard only of npm engine besides Sling).

henrykuijpers commented 5 years ago

I guess the reason is that you want your file to look as "plain HTML" as possible. Therefore, it is convenient to put the data-sly-* attributes last. They are not shown in the actual HTML output, thus are less important when trying to read the HTML document.

kwin commented 5 years ago

thus are less important when trying to read the HTML document.

Well, I tend to disagree. Just think about data-sly-test. I would argue that this attribute is more important than regular HTML attributes because it may prevent the whole element from being rendered in the first place.

karollewandowski commented 5 years ago

I would strongly disagree. Standard attributes determine look and content, while HTL blocks determine look, content and most importantly document structure. I think people are more interested in what is eg. data-sly-repeat's products list data source or how many times element will be rendered, rather than it has product-item CSS class. HTL blocks affects document more significantly than HTML attributes.