PlantUmlServer/docs/contribution/front-end.md

Front-end Contribution

Web UI

The Web UI uses vanilla javascript.

As online editor Microsoft's Monaco Editor. The documentation can be found here. You may recognize the editor since it's the code editor from VS Code.

The main entry file are index.jsp, previewer.jsp and error.jsp.

The code structure is mainly divided into components and js:

• components are for example a modal or dialog. Anything that include things directly seen and rendered on the page.
• js contains more the things that do not have a direct influence on the UI. For example the PlantUML language features or the methods for cross-browser/cross-tab communication.

PlantUML Language Features

At the moment there is no defined PlantUML language. Feel free to create one! But until then the syntax highlighting form apex is used. IMHO it works quite well.

All PlantUML language features are bundled into a seperate file plantuml-language.min.js. Therefore anything under js/language should be independent!

Code Completion

What do you need to do to create a new code completion feature:

1. create a new JS file under js/language/completion - let's say xxx.js
2. create a new registerXxxCompletion method
   It may help you if you look into the documentation or at the provided sample code to understand more about monaco.languages.registerCompletionItemProvider.

   PlantUmlLanguageFeatures.prototype.registerEmojiCompletion = function() {
     monaco.languages.registerCompletionItemProvider(PlantUmlLanguageFeatures.languageSelector, {
       provideCompletionItems: async (model, position) => {
         // ...
         return { suggestions };
       }
     });
   };
   

3. add your new method inside the language initialization inside js/language/language.js

   const PlantUmlLanguageFeatures = function(initialize = true) {
     if (initialize) {
       // initialize all validation and code completion methods
       this.addStartEndValidationListeners();
       this.registerThemeCompletion();
       this.registerIconCompletion();
       this.registerEmojiCompletion();
   +   this.registerXxxCompletion();
     }
   };
   

Code Validation

What do you need to do to create a new code validation feature:

1. create a new JS file under js/language/validation/listeners - let's say zzz-validation.js
2. register your validation methods to the designated event listener
   The validation event order is: before → code → line → after
   You may look at js/language/validation/listeners/start-end-validation.js to get an idea how to register a new listener.
3. add your new method inside the language initialization inside js/language/language.js

   const PlantUmlLanguageFeatures = function(initialize = true) {
     if (initialize) {
       // initialize all validation and code completion methods
       this.addStartEndValidationListeners();
   +   this.addZzzValidationListeners();
       this.registerThemeCompletion();
       this.registerIconCompletion();
       this.registerEmojiCompletion();
     }
   };
   

Tipps

• pom.xml: set withoutCSSJSCompress to true to deactivate the minification
• use mvn fizzed-watcher:run to watch changes and automatically update the bundled plantuml.min.{css,js} and plantuml-language.min.js files
• if the browser get the error ReferenceError: require is not defined or something similar related to the webjars, try mvn clean install to get things straight