viewX-vscode

A Visual Studio Code extension that allows graph based visualization of a code/model written in a DSL created using textX meta-language.

This extension contains 3 main parts:

• VS Code extension (Typescript)
• Interpreter of viewX model and custom DSL concrete model, generators of model preview and viewX project template structure (Python)
• Graph preview logic and socket server for interaction between extension and graph, each using Cytoscape.js and Socket.io libraries respectively (Javascript)

Quick start:

1) Prerequisites:

• Install Python 3.x version by following the instructions
• Make sure that Python has been added to the HOME environment variable by running the following commands:

    python -V
    pip -V

• Install Python virtualenv module using pip:

    pip install virtualenv

2) Install viewX extension

• Install viewX extension from the VS Code Extension Marketplace
• Restart Visual Studio Code editor

3) Setup viewX python virtual environment:

a) Script:

• Go to the directory where VS Code extensions are installed (e.g. '~\Documents\.vscode\extensions')
• Open viewX extension directory and from 'setup_scripts' directory run a 'viewX_setup' script appropriate for your operating system. Parameters needed for the script are -path (path for the environment to be created) and -name (name of the virtual environment). Optionaly you can define -reqFile (path to the requirements file), by default the python_requirements.txt file is been used from extension's root folder. Examples:
  • Windows (Powershell):

      .\viewX_setup.ps1 -path "some\parent\folder" -name "env_name" [-reqFile "path\to\requirements\file"]
  

  • Windows (Command Prompt):

      Coming soon...
  

  • Linux / Mac OS:

      Coming soon...
  

b) Manually:

• Create Python virtual environment

• Create viewXVEnv environment variable and set Python virtual environment's root path as it's value

• Copy python_requirements.txt file to the created Python virtual environment

• Install Python dependencies by running following command in a console:

  • Windows (Powershell):

      $Env:viewXVEnv/Scripts/pip install -r $Env:viewXVEnv/python_requirements.txt
  

  • Windows (Command Prompt):

      %viewXVEnv%/Scripts/pip install -r %viewXVEnv%/python_requirements.txt
  

  • Linux / Mac OS:

      $viewXVEnv/Scripts/pip install -r $viewXVEnv/python_requirements.txt
  

... and you're ready to go! :)

Basic usage flow:

1. When extension is installed and loaded, press ctrl+alt+v i keyboard shortcut to initialize viewX project. If workspace is loaded, you can right-click on some folder from the tree view and select viewX: Initialize Project command. This way the selected folder will be used as destination for your viewX project and only the project name will be prompted.
2. Insert project path (if keyboard shortcuts are used) and then project name. It will create the folder structure and initialize valid viewX project template which include configuration file, DSL example in textX, 2 DSL model examples and 1 viewX model example. This will help a user to have a better understanding of how viewX project should look like and to:
   • Write a custom DSL using textX
   • Develop models in his own custom DSL
   • Define a way of visualizing his models using viewX
3. Visualize your model in a graph-like preview based on the defined visualization rules by pressing press ctrl+alt+v p keyboard shortcut or by rigth clicking the active document and selecting the viewX: Preview model on side panel command from the context menu. It will appear only on documents that match the filter defined in vxconfig.json file in loaded workspace.
4. You can make basic interactions with the graph on the preview (navigation, panning, zooming, selection, moving nodes etc.). Saved changes to the currently previewed concrete model are immediately applied to the graph (if the model is valid after saving).

Extension in use:

Let's say we want to visualize a Martin Fowler's state machine example similarly to the way it is visualized in this textX demo (about the details of this model and textX metamodel please watch the demo video).

This is where viewX extension comes in play. There are 2 extreme ways we can go to accomplish this:

• Use viewX DSL only to describe graph structure and apply valid Cytoscape.js styling within viewX model style section (example: vx_examples/state_machine/dot_like_css.vx)
• Use viewX DSL to define both the structure and the styling of the graph (example: vx_examples/state_machine/dot_like.vx)

Using any of these two extreme examples result in a graph to be displayed in the same way:

Depending on the complexity of the textX model and the user's preferences, one can define viewX model in a way anywhere between these two examples.

Dependencies:

• This extension is intended to provide useful features during development using textX framework, so it heavily depends on textX. TextX is a meta-language which allows user to create his own DSL language defined by textX grammar rules. For more information about textX please check documentation or GitHub repository.

• Since textX is implemented in Python, it is also used to perform user's DSL concrete model and viewX vizualization interpretation as well as generation of preview script. You can find more information on Python homepage.

• Preview is a regular .html script which uses Cytoscape.js Javascript library for graph vizualization. For more details about this library please visit Cytoscape.js homepage.

• To enable communication between extension and graph preview file, and vice versa, a Socket.io Javascript library is used. This library is used for creating a socket based server listening on a port and distributing commands between graph preview browser clients and extension itself. More on this library and how it can be used can be found here Socket.io homepage.

License:

Author: Daniel Kupčo

Licensed under the MIT License.