Mjml: Intellij tooling support

[lookfirst]

Filed: https://youtrack.jetbrains.com/issue/IDEA-151641

[arnaudbreton]

Hey @lookfirst, thanks or opening that request at IntelliJ, hope we'll land there soon!
Any idea on how could we help to push this request there?

[ngarnier]

hey @lookfirst, is this still a thing?

I don't think the IntelliJ team will develop such a plugin and we don't have much experience with it. Would you be interested in leading this project?

[lookfirst]

Shrug. Nah. I'll close.

[g0ddish]

I might be willing to take a crack at this on the weekend, don't close it just yet! I use intellij tools for everything :) a good starting point 1 and 2

[ngarnier]

Nice, thanks a lot @g0ddish! Let us know how it goes / if you need help.

[ngarnier]

Hey @g0ddish, just checking in on this 🤓 . Did you have the opportunity to take a shot at IntelliJ plugins?

[ngarnier]

Hey guys,

We'd love to have an IntelliJ plugin and would be happy to feature and share it with the community if anyone wants to help. However, we won't be able to develop and maintain one ourselves so I'm closing.

[martixy]

This is sad. I don't imagine it'll be a terribly complex plugin anyway. However my contact with mjml is pretty tangential in the current project, so its unlikely I'll ever get around to it, but you never know. I'll keep this issue in mind.

[IchordeDionysos]

What should be supported by this plugin?
What exactly are the other plugins for Atom and Sublime doing?

I don't know if I could make it, as I never really worked with IntelliJ plugins, but maybe in my semester break I find time to play around a bit here and then it would be great to have a clear roadmap.

And how are the code editor plugins build on top of mjml?
Do they use the linters already used by mjml :o

[IchordeDionysos]

Just syntax highlighting would be somehow useless...
To get syntax highlighting one could register *.mjml as HTML file like this:
Go to settings/preferences -> Editors -> File Types -> Search for and select HTML in "Recognized File Types" -> Click the plus button on the left of the "Registered Patterns" box -> Enter *.mjml in the box and click "OK"

Like this, you get basic HTML highlighting.
The only problem which still exists is that all mjml tags are marked as unknown.
But even for that, I have a resolution in mind:

When adding a namespace declaration IntelliJ will recognize all elements of the namespace declaration and won't warn anymore.

So question to the mjml guys:
Does such a namespace declaration exist and would it be possible to create one, otherwise?
And would it be a problem for the parser if the <mjml> had a xmlns attribute on it?
@ngarnier

[ngarnier]

Hey @IchordeDionysos, awesome if you can help, thanks a lot!

I think the best is to look at the VSCode plugin, which is a community package but embarks the most features. From the package doc:

• Live preview for MJML files. Preview updates as you type. Preview based on html-preview-vscode.
• Inline errors (squiggle underlines). Linter based on atom-linter-mjml.
• Export HTML file from MJML.
• Copy the result HTML to clipboard.
• Take a screenshot of the rendered MJML document.
• Send email with Mailjet
• Code snippets for MJML. Based on mjml-syntax.
• Fetch official templates. Based on mjml-app.
• Beautify MJML code.

[irkanu]

+1

[sgodart]

+1

[the1979]

+1

[GarryFlemings]

Hey @IchordeDionysos, nothing against @ngarnier, but if that's a formidable list (and I feel it is! _Sorry ngarnier!_), a big part of me says, "First, do the simplest thing that could possibly work!" A smaller part of me says, "Figure out what one part of the whole gives the best benefit (either to users or to exposing the full amount of effort or to whatever else might be most important) and do that."

My theory: If you get any one part of that released, you might well attract some help. (I'd be willing, but I'm concerned my skills are too light. Working with someone else, I might be able to contribute more value in work than the required mentoring costs.)

And maybe one part is pretty easy: "Live preview for MJML files. Preview updates as you type." Possible start of a design: Write an MJML component that adds a server (maybe Express). Use an IntelliJ "file watcher" to send the HTML output to that server each time the file changes. Tell the users what port the server by default answers to (say, 31416, which is math's pi, but I know someone else is using that so it could cause conflict for some) and tell users to point a browser on the same computer to https://127.0.0.1:31416.

Complete solution? Dunno. For instance, updating what the server will serve if requested might require the user to order a refresh; that's good and not great. If there's a way for the server to signal the browser that an update is available, the browser could call for it without user intervention. Or maybe have the browser poll the server each second (seems wasteful). Dunno how to try it. So much to try!

If you/we could do just that one part for version 1, I believe it'd be a big deal. All the rest is very important, too. Baby steps are most important, though. _(Are we okay again, ngarnier? :) )_

[GarryFlemings]

Related info on IntelliJ: https://intellij-support.jetbrains.com/hc/en-us/community/posts/360000238699-MJML-reformat-code

[IanEdington]

My current solution (for the people coming from google):

With this setup inspections, intentions, code highlighting, and folding, seem to work. There are some areas for improvement at the bottom.

Also, I've very willing to take suggestions and update this comment with better/other ways of setting up Intellij Idea or webstorm with MJML.

1. Make mjml an html File Type:
   Add *.mjml as a File Name Pattern to Editor > File Types under an html like file type. I chose Mustache since that's what we use as a templating language.

2. Register a language injection for css:

   • Editor > Language Injections
   • New XML tag injection
     
     
     
     • Name: mj-style
     
     
     • Language > ID: CSS
     
     
     • XML Tag > Local name: mj-style
     
     
     • everything else should be blank
     
     

3. register a bunch of custom html tags:

   • Editor > Inspections > Unknown HTML tag
   • under options make sure Custom HTML tags is checked

   • add the following to the text box (I'm probably missing some)

     mjml,mj-accordion,mj-accordion-element,mj-accordion-text,mj-accordion-title,mj-all,mj-attributes,mj-body,mj-breakpoint,mj-button,mj-carousel,mj-carousel-image,mj-class,mj-column,mj-divider,mj-font,mj-group,mj-head,mj-hero,mj-image,mj-include,mj-navbar,mj-navbar-link,mj-preview,mj-raw,mj-section,mj-social,mj-social-element,mj-spacer,mj-style,mj-table,mj-text,mj-title,mj-wrapper
     

Known issues:

• [ ] colour viewer doesn't work on mjml colour attributes
• [ ] mj-class doesn't register as a class for css inspections
• [ ] registering custom html tags pollutes HTML autocompletion for non mjml files (#1657)

[GarryFlemings]

Related info in https://intellij-support.jetbrains.com/hc/en-us/community/posts/360000238699/comments/360002321600. I have Live Edit and syntax highlighting for MJML working in WebStorm and PhpStorm.

If I get feedback, I'll put the updated result here.

EDIT: Updated URL.

[IanEdington]

~Hey @GarryFlemings unfortunately that URL 404's for me~

It's working now 🙏

[GarryFlemings]

I found the following sufficient to add MJML syntax highlighting in JetBrains WebStorm and PhpStorm (here, "IDEs") and to use Live Edit with MJML in the IDEs. Like Ian before me (just above), I'm "very willing to take suggestions and update this comment with better/other ways of setting up Intellij Idea or webstorm with MJML."

JetBrains supports many web pages (all helpful IMO) with "/help/webstorm/" in the URL. I've cited those here. In many cases, they also support a matching web page with "/help/phpstorm/" in the URL. PHP users may find it worth checking for the PhpStorm versions.

The notation [1] etc. refers to a URL listed at the end.

Configure the IDEs for Syntax Highlighting

1. Add *.mjml to HTML file extensions or the HTML template language of your choice [9]
   File > Settings > Editor > File Types > Recognized File Types: > HTML, clickAns > File Name Patterns: > + > *.mjml

2. Add MJML tag list (v4.6.3) [8]
   File > Settings > Editor > Inspections > HTML > Unknown HTML tag >
   mj-all,mj-accordion,mj-accordion-element,mj-accordion-text,mj-accordion-title,mj-attributes,mj-body,mj-breakpoint,mj-button,mj-carousel,mj-class,mj-column,mj-divider,mj-font,mj-group,mj-head,mj-hero,mj-image,mj-include,mj-navbar,mj-preview,mj-raw,mj-section,mj-spacer,mj-style,mj-table,mj-text,mj-title,mj-wrapper,mjml

3. Add MJML tag attribute list (v 4.6.3) [8]
   File > Settings > Editor > Inspections > HTML > Unknown HTML tag attribute >
   align,alt,background-color,background-height,background-position,background-repeat,background-size,background-url,background-width,base-url,borderborder-bottom,border-color,border-left,border-radius,border-right,border-style,border-top,border-width,cellpadding,cellspacing,color,container-background-color,css-class,direction,fluid-on-mobile,font-family,font-size,font-style,font-weight,full-width,hamburger,height,href,ico-align,ico-close,ico-font-family,ico-font-size,ico-line-height,ico-open,ico-padding,ico-padding-bottom,ico-padding-left,ico-padding-right,ico-padding-top,ico-text-decoration,ico-text-transform,icon-align,icon-height,icon-padding,icon-position,icon-size,icon-unwrapped-alt,icon-unwrapped-url,icon-width,icon-wrapped-alt,icon-wrapped-url,inline,inner-background-color,inner-border,inner-border-bottom,inner-bottom-left,inner-border-radius,inner-border-right,inner-border-top,inner-padding,left-icon,letter-spacing,line-height,mj-class,mode,name,padding,padding-bottom,padding-left,padding-right,padding-top,rel,right-icon,src,srcset,table-layout,target,tb-border,tb-border-radius,tb-hover-border-color,tb-selected-border-color,tb-width,text-align,text-decoration,text-padding,text-transform,thumbnails,thumbnails-src,title,usemap,vertical-align,width

Configure the IDEs for Live Edit [1]

1. Don’t use the Chrome Extension “JetBrains IDE Support” [12]

2020-10-18: This is a (temporary) point of confusion. [4] includes past instructions to install and enable this extension. [12] is a 2020-10-08 JetBrains Support post indicating this extension doesn't work reliably with recent versions of Chrome. Both my WebStorm and PhpStorm started working when I configured them to not use the extension.

There’s one configuration setting. It’s in the instructions below under “Activate and Configure Live Edit in JavaScript”.

In Chrome, I chose to disable the extension. [Optional]

1. Configure the IDE to interact with Node.js and NPM
   File > Settings > Languages & Frameworks > Node.js and NPM

2. Define an MJML scope [10]
   File > Settings > Appearance & Behavior > Scopes > +

3. Name: MJML files
4. Pattern: file:*.mjml (include “file:”)

5. Look for a comment like, "Scope contains 6 of total 312 files …" If MJML files are present in the identified directory, "0 of total 312 files …" is bad. Example in image in [7].

6. Among JetBrains plugins, activate Live Edit, JavaScript Debugger, Node.js, and File Watchers
   File > Settings > Plugins

7. Configure Listening Port
   File > Settings > Build, Execution, Deployment > Debugger > Built-in server > Port > 63342 (default)

8. I used 63343 in PhpStorm while using 63342 in WebStorm. Both IDEs can debug at the same time.

9. Activate and Configure Live Edit in JavaScript [2]
   File > Settings > Build, Execution, Deployment > Debugger > Live Edit

10. Update Node.js application on changes in: As desired. Default is 300 ms.
11. Update application in Chrome on changes in: As desired. Default is 300 ms.
    
    
    
    • Only HTML and CSS: Check [Optional]
    
    
12. Track changes in files compiled to JavaScript, HTML or CSS: Check
13. Highlight current element in browser on caret change: Check [Optional]
14. Restart if hotswap fails: Check. [Optional] Recommended [1].

15. Use JetBrains IDE Support extension for debugging and Live Edit: Un-check [12]

16. Configure browsers [3]
    File > Settings > Tools > Web Browsers

17. Top right window: Check desired browsers; uncheck undesired browsers.
18. Default Browser: First listed [Optional]

19. Show browser popup in the editor > For HTML files: Check

20. Create File Watcher [5]
    File > Settings > Tools > File Watchers > + > custom

21. Name: MJML
22. File type: Any [7]
23. Scope: MJML files [7] (same string as in scope configured above)
24. Program: C:\yourPathnode_modules.bin\mjml.cmd ([6] & [11] suggest mjml-cli; this worked for me)
25. Arguments: yourScript.mjml -o yourScript.html
    
    
    
    • [6] & [11] suggest $FileName$ -o $FileNameWithoutExtension$.html, which would affect only the *.mjml file that changed. My project has many include files (all *.mjml); this recompiles the root file when any *.mjml file changes. Your need may be different.
    
    
    • Perhaps yourScript.mjml --config.minify false -o yourScript.html. Or similar for $FileName$ etc. (Maybe too little value in minifying for these quick compilations.)
    
    
26. Output file paths to refresh: yourScript.html (maybe $FileNameWithoutExtension$.html)
27. Working directory and environment variables > Working directory: $FileDir$

28. Advanced options

    • Auto-save edited …: Check
    • Trigger the watcher on external changes: Check
    • Trigger the watcher regardless …: Check [Optional]
    • Create output file …: Uncheck [Optional]
    • Show console: Always
    • Output filters: ERROR: $FILE_PATH$[$LINE$, $COLUMN$]: $MESSAGE$ [Optional] [5]

29. Start a debug session [13, second link]
    Right-click on the HTML file in the IDE and select Debug.

I hope this helps someone. Regrets for remaining typos.

URLs

Kudos to Majid Sportback (starting [8]), AndrewRIGHT [10] and Karthikeyan Palaniswamy (starting [6]) for great questions and contributions. And to JetBrains folks Andriy Bazanov ([8] and other) and Elena Pogorelova ([6] and other) for great support of MJML in addition to JetBrains.

[1] https://www.jetbrains.com/help/webstorm/live-editing.html
[2] https://www.jetbrains.com/help/webstorm/debugging-javascript-in-chrome.html
[3] https://www.jetbrains.com/help/webstorm/configuring-browsers.html
[4] https://www.jetbrains.com/help/webstorm/using-jetbrains-chrome-extension.html#install_JB_Chrome_extension
[5] https://www.jetbrains.com/help/webstorm/using-file-watchers.html#showFileWatcherInfoInEditor
[6] https://intellij-support.jetbrains.com/hc/en-us/community/posts/115000117404/comments/115000144684
[7] https://intellij-support.jetbrains.com/hc/en-us/community/posts/360000238699/comments/360000056260
[8] https://intellij-support.jetbrains.com/hc/en-us/community/posts/360000238699/comments/360000051400
[9] https://intellij-support.jetbrains.com/hc/en-us/community/posts/360000238699/comments/360000056360
[10] https://intellij-support.jetbrains.com/hc/en-us/community/posts/360000238699/comments/360000384820
[11] https://intellij-support.jetbrains.com/hc/en-us/community/posts/360000238699/comments/360000056959
[12] https://intellij-support.jetbrains.com/hc/en-us/community/posts/360009763819/comments/360002287939
[13] https://stackoverflow.com/questions/14069520/why-does-webstorms-liveedit-not-work-in-chrome; the first comment points to https://confluence.jetbrains.com/display/WI/LiveEdit

Thanks

Ian Edington was kind enough to provide valuable inputs before publication.