Lavoisier Editor Plugin (for IntelliJ IDEA)

Setup

  1. How to install
  2. How to uninstall

Editing

  1. How to start a new Lavoisier project
  2. How to edit your application
  3. How to create a new XML template

Debugging

  1. How to run a data view
  2. How to debug a data view
  3. How to test the rendering of a data view

Configure debugging

  1. How to configure debugging
  2. How to set the the range of subtrees under root node
  3. How to set the maximum number of nodes

Visual help

  1. How to enable visual help
  2. How to visualize the structure of your application
  3. How to get contextual visual help

Miscellaneous

  1. How to just start the Lavoisier server (without testing a data view)
  2. How to update execution environment
  3. How to import a legacy project
  4. How to show various information about this plugin

Setup

How to install
  • Download and install IntelliJ IDEA by JetBrains (both Ultimate and Community editions are supported).
  • Download Lavoisier Editor Plugin
  • Start JetBrains IDEA and install Lavoisier Editor Plugin: Configure | Plugins | Install plugin from disk... | Restart

When you will create your first Lavoisier project, this plugin will automatically download and install the Lavoisier framework, in order to enable the debugging feature and more...

Note: the very first time you will use this plugin, a second restart will be needed in order to take into account the newly installed files.

How to uninstall
  • Click on menu item: Configure | Plugins | search for "LavoisierEditorPlugin" | Uninstall

When IDEA has finished restarting, all the files previously installed by this plugin will be cleaned up from your system.

Editing

How to start a new Lavoisier project
  • Create a new Lavoisier Application: Create New Project | Lavoisier Application
  • Create a new Lavoisier File: Right-click on directory "etc/app/views/" | New | Lavoisier File

You are now ready to create your first data view (see below)!

How to edit your application
  • Use auto-completion (using [Ctrl + Space] and [Enter]) to enter the following text (do not copy-paste it!): 
    <view name="hello">
    <argument name="name">World</argument>
    <connector type="StringConnector">
        <parameter name="content" eval="concat('Hello ',$name,'!')"/>
    </connector>
    <serializer type="EncapsulateSerializer"/>
</view>
  • Entering [Ctrl + Q] when your cursor is on a plugin name will display a contextual help on this plugin.
  • To run your first "Hello World" application, right-click on element <view>, then click on...
    • Run this view, and look at the result in the "Run" tab.
    • Browse this view with arguments | <enter your name> | OK | Yes, and look at the result in your web browser.
    • See chapter How to run a data view for other options...

Note: To learn how to create a data view by assembling plugins, refer to this documentation.

How to create a new XML template
  • Since XML templates are processors, you first need to add the <processors/> if it is not already present in you processing chain.
  • If the input XML data has no namespace, then ignore this bullet and jump to next one. Else, its namespace must be associated to a prefix (using notation xmlns:myprefix="mynamespace"), in order to allow this prefix for being used by the generated skeleton. Please note the prefix to namespace association is not allowed in the template, it must be done on one of its ancestor elements (<views>, <view> or <processors>).
  • Create the skeleton of your XML template:
    • to insert it at first position, click on the <processors/> tag. The intention button (intention logo) should appear next to it. Clicking on this button opens a popup menu with item Add <element> as child. Click on this menu item to generate the XML template skeleton.
    • to insert it next to an already existing template, click on the related template (i.e. on tag <element/>, <elements/>, <element-ignore/> or <element-create-as-parent/>). The intention button (intention logo) should appear next to it. Clicking on this button opens a popup menu with item Add <element> as sibling. Click on this menu item to generate the XML template skeleton.
  • Modify the generated XML template skeleton by decorating it with new attributes and elements. You should use the auto-completion feature for this.
  • You can visualize the data structure by enabling Visual Help on the generated XML template skeleton.

Note: To learn how to modify the generated XML template skeleton to make it transform your data according to your needs, refer to chapters XML Template Language and XML Templates Examples.

Debugging

How to run a data view
  • Right-click on node <view>.
  • Click on one of the following options:
    • Run this view (or Run this view with arguments...) if you want to dump the entire output generated by this view.
    • Run this view within range [N..M] (or Run this view within range [N..M] with arguments...) if you want to dump only a subset of the output generated by this view. To learn how to modify the default values of "N" and "M" for the options [...] within range [N..M], refer to chapter How to set the the range of subtrees under root node.
How to debug a data view

Instead of running the full chain of plugins and templates of your data view, you can run the chain up to the selected plugin or template. This is similar to a debugger for an imperative language, except that the steps are plugins and templates rather than instructions.

  • Right-click on the last step that you want to execute with the chain of your data view. The step can be:
    • a plugin: <connector>, <serializer>, <validator>, <processor>
    • a template: <element>, <elements>, <element-ignore>, <element-create-as-parent>
  • Click on one of the following options:
    • Run up to this plugin (or Run up to this plugin with arguments...) if you want to dump the entire output generated by this sub-chain.
    • Run up to this plugin within range [N..M] (or Run up to this plugin within range [N..M] with arguments...") if you want to dump only a subset of the output generated by this sub-chain. To learn how to modify the default values of "N" and "M" for the options [...] within range [N..M], refer to chapter How to set the the range of subtrees under root node.
How to test the rendering of a data view

There are several options for testing the rendering of your data view. Choose the right one according to the context:

  • If you want to test your configuration of a given renderer plugin, then right-clik on the corresponding <renderer> tag and select option Browse or Render. For example, if the tested renderer is the <HTMLRenderer>, then you have the choice between:
    • selecting option Render (or Render with arguments...) to check the generated HTML code.
    • selection option Browse (or Browse with arguments...) to check how this generated HTML will display in your web browser.
  • If you want to test the default behavior of a renderer plugin that you have not configured, then right-click on node <view> and selection option Browse this view (or Browse this view with arguments...). This will open a dialog-box to choose a renderer among all those available in Lavoisier framework, including those that have not been configured for this view. Select the desired plugin, then click on button "OK".

Please note that the option Run this view (or Run this view with arguments...) does not offer the possibility to select a renderer plugin, this is only possible with the option Browse this view (or Browse this view with arguments...). The reason for this restriction is to avoid bothering you with this extra-step for the most frequent use-case for option Run this view.

Configure debugging

How to configure debugging

If you need to change the behavior of the debugger, you will have to edit IDEA Custom Properties: Help | Edit Custom Properties.... This opens a file named "idea.properties".

Both features described in this section allows for limiting the amount of data to be displayed in the "Run" tab, but they are complementary:

  • The within range feature allows for restricting the number of subtrees under the root element, in order to prevent the developer for losing time by browsing huge amount of data when she only needs to see a small part of it for debugging. However, the amount of displayed data will strongly depend on the structure of this data.
  • The limit feature allows for restricting the number of elements, in order to prevent the IDE from losing time while writing data on the display. However, the end of the displayed data may be inconsistent.

Both feature have drawbacks when used separately, that's why using them simultaneously is often the best choice.

How to set the the range of subtrees under root node

The properties lavoisier.data.partialview.window.offset and lavoisier.data.partialview.window.length allows for restricting the output of a given execution for the purpose of making debugging easier.

As a consequence, the later property (length) is often set to a small value (e.g. 3 or 10). This value corresponds to the number of subtrees to be displayed under the root element.

Setting this properties will enable the following options in the contextual menu:

  • Run this view within range [N..M] (or Run this view within range [N..M] with arguments...)
  • Run up to this plugin within range [N..M] (or Run up to this plugin within range [N..M] with arguments...)
  • Render within range [N..M] (or Render within range [N..M] with arguments...)

Example: 

lavoisier.data.partialview.window.offset=1
lavoisier.data.partialview.window.length=3
How to set the maximum number of nodes

The property lavoisier.data.partialview.limit allows for restricting the output of a given execution in order to avoid hanging the IDE while displaying huge amount of data.

As a consequence, its value must be small enough to protect your IDE, and high enough to avoid excessive filtering of your data (e.g. 256). This value corresponds to the maximum number of elements to be displayed. When this limit is reached, the following comment is appended to the document: 

<!— max number of nodes has been reached… —>

Unlike the previous properties, this property will impact every debugging option (e.g. Run this view, Run up to this plugin, ...).

This feature is disabled by default, and setting it will enable it.

Example: 

lavoisier.data.partialview.limit=256

Visual help

How to enable visual help
Open tool windows App Structure and App Overview:
  • either click on the tool window App Structure on left side, and on the tool window App Overview on the right side of IDEA.
  • or select menu item: View | Tool Windows | App Structure and View | Windows | App Overview
How to visualize the structure of your application

Open the tool window App Structure (see above), which displays a hierarchical representation of your application:

  1. The root level "Categories" corresponds to the entire application (i.e. all the XML files under directory etc/app/views/.
  2. The next level corresponds to a subset (or category) of data views. If no category label is defined, then the file name is used instead.
  3. The next level corresponds to a data view.
  4. The leafs of the tree correspond to the plugins and the XML templates of the processing chain.

Clicking on a node will automatically open the corresponding views file (if not already opened) and move the caret of the corresponding tag in this file.

Double-clicking on a node allows for collapsing/uncollapsing it.

Note: This tree will not be automatically updated, so you will have to refresh it manually when the modifications made in the code impact its structure (e.g. add or remove a plugin, an XML template or a data view). This can be done by right-clicking anywhere in the "App Structure" tool window, then clicking on the menu item Reload All Views.

Tip: Set this tool window to Split Mode in order to allow it to coexist with the Project tool window.

How to get contextual visual help

Open the tool window App Overview (see above), which displays a visual representation of the portion of code related to the node selected in the App Structure tree.

The displayed information can be:

  1. the full list of data views with information about their dependencies and cache, with detection of inconsistencies in cache configuration.
  2. a subset of data views, with information about their arguments (argument name, default values, is it required or optional?).
  3. an overview of a given data view: its arguments, the configuration of its plugins, the number of templates.
  4. the configuration of a given plugin (or set of plugins).
  5. a human-friendly representation of a given XML template (or set of XML templates).

Note: This tool window will not be automatically updated, so you will have to refresh it manually when you want it to reflect your last modifications. There are two ways to do this:

  • Selecting a different node, then going back to the previous node in the App Structure tool window will refresh the App Overview tool window.
  • A keyboard shortcut (Ctrl + Alt + R) will refresh both tool windows (App Structure and App Overview). If, on your host, this keyboard shortcut is already mapped to another action, then you will have to configure it through menu Settings... | Keymap (you can either remove the conflicting shortcut, or map the feature "App Overview Action" to a free keyboard shortcut of your choice).

Miscellaneous

How to just start the Lavoisier server (without testing a data view)

You can just start the Lavoisier server without asking IDEA to open any data view in your browser. This can be done through the menu item Tools | Lavoisier | Start Server, and you can stop this server through the menu item Tools | Lavoisier | Stop Server.

Once the server has been started at least one time, you can also start, restart and stop it with respectively the IDEA "run", "rerun", "stop" and "exit" buttons. Before clicking on button "run", ensure that "Start Lavoisier Server" is selected in the run configurations popup list.

The Lavoisier server will be automatically stopped when closing your IDEA project.

Simultaneously running several servers (one per opened project) is supported. Of course you will have to configure them with different HTTP ports.

How to update execution environment
  • Click on menu item: Tools | Lavoisier | Update Execution Environment
  • Click on button "OK" to confirm your decision to update the execution environment
  • Click on button "Restart now" (else some updated files may not be taken into account)
  • Click on button "Exit" (for this dialog-box, you can check box "Do not ask me again")

When IDEA has finished restarting, your execution environment should be up-to-date, including:

  • the Lavoisier framework
  • the files used by the IDEA plugin for many of its features (project and file templates, auto-completion, inline documentation, visual help)
How to import a legacy project
If your Lavoisier application was not created with the Lavoisier Editor Plugin for IntelliJ IDEA, it is still possible to enable all its features with your project:
  • Create a maven POM file if your project does not already has one. If you don't know how to do this, you can create a new Lavoisier project (see How to start a new Lavoisier project) and copy its POM file into your project directory.
  • Click on Import Project, and then select the POM file of your Lavoisier project. Click on button "Next" for each dialog-box, and on button "Finished" for the last dialog-box.
  • In order to enable the debugger, you need to add the etc/ directory of your Lavoisier project as a "library root". To do this:
    • Click on menu items: File | Project Structure... | Libraries
    • Click on button "+" to add a New Project Library
    • Select "Java" in the dropdown list
    • Select the path to the etc/ directory of your Lavoisier project.
    • Select "Classes", then click on button "OK"
    • Ensure that the words "library root" are written in color gray in the project tree, next to the etc/ directory of your Lavoisier project .
How to show various information about this plugin

You can get information about files by selecting the following menu items:

  • Tools | Lavoisier | Show files and directories location
  • Tools | Lavoisier | Show files installed

This information will be displayed in the Event Log.