VSIDE is the new Eidosmedia Administration/Development tool. It is an extension of Visual Studio Code which uses the EDAPI server to retrieve information from the back-end.

VSIDE is equipped with a wizard which also allows to create a REACT panel extension project in order to use the new Eidosmedia Component Library to create extensions with a more standard user interface and user experience.

As administration tool VSIDE covers the most important administration action available today through the Eidosmedia Eclipse plugin.
Below a list of the most important administrative feature available in VSIDE:

As developer tool VSIDE help the user to create Prime/Swing extensions panels based to the EM shared framework.
The VSIDE wizard also allow to create a REACT panel extension project in order to use the new Eidosmedia Component Library to create more standard user interface and user experience.

To install VSIDE, extension of Visual Studio Code using the EDAPI server to retrieve information from the back-end, the following requirements must be met:

Usually all the standard Visual Studio Code extensions are located in the public marketplace and are searchable directly from the extension panel inside the VSCode framework as depicted in the screenshot below.

For proprietary extensions it is also possible to install them using directly the extension files which are files with extension ".VSIX". In this case, inside the extension panel you will find a menu where you can select the vsix file, as shown in the screenshot.

Select the vsix (https://artifactory.eidosmedia.sh/artifactory/generic-public/vside/eidosmedia-vside-1.0.20.vsix) file from your local drive and click on the "Install" button.

Note that the process will take a while. If everything works fine, you will have the extension installed in your vscode extension panel.

In order to use the new react EmComponent library you need to link the @eidosmedia namespace to our npm-registry. To to this you need to login to the Eidosmedia npm Artifactory repository.

Open a console and type:

when asked, Username is your Eidosmedia domain username but password is the JFrog Api Key, you can find it on https://artifactory.eidosmedia.sh/ui/admin/artifactory/user_profile

In order to use VSIDE as an administration tool, you need at least one EDAPI repository to work. This tutorial will help you to create a configuration file and subsequently connect to the first repository.

The first run of Visual Studio with VSIDE installed will be very similar to the image below.

The EomDbView icon on the left side toolbar lets you open the panel where you see the tree of the configured EomDb repositories. The tree button in the VSCode Welcome page lets you start interacting with the extension.

Let’s start with the first step which allows you to create a first configuration file by using the extension wizard.

VSIDE provides a wizard that allows you to quickly create a repository configuration file. The wizard lets you go through 5 steps.

If you want, you can change some properties of the configuration and save it anew. You can also have different configuration files for different repositories and you must tell VSIDE that you want to use the last one you have created.

To load the configuration file you must simply click the "Load Configuration" button:

and select the file you have just saved.

By clicking "Open", you will set the configuration file and you will have the confirmation of the correct loading with a message in the Status bar like this below.

Now, clicking on the "EomDb view" button you should see the panel with a row listing with your repository(ies).

To know how to connect to the repository, see the "Administration Tool" section.

The configuration file is written in JSON format and it is an array of the repository object. Find an example here below.

For each repository object the following parameters are defined:

You can have multiple files for each repository or you can configure more repositories in one file, here is an example of a configuration with 4 repositories:

If you need to load a different configuration file with respect to the current one, you can use the two commands inside the browser view.

By clicking on the three horizontal dots "…​" button, the same buttons you have seen in the welcome page when VSCode starts will be displayed.

Click on the "Load Repository Configuration" button to switch file.

For a better user experience when using VSIDE inside Visual Studio we suggest to use the following settings

Once you have configured at least one back-end connection (as described here), you need to explicitly open a connection to the selected repository. To connect, click on the icon on the right of the connection name as shown in the image below

If everything is properly configured and the repository is reachable, you will see the icon on the left of the connection name turn green.

Once you are connected, you can navigate the EomDb like any other filesystem

The tree structure of the EomDb does not include only the folder/files coming from the EomDb but also "special" folders that give you access to:

The IDE part of the VSIDE provides you with a "controlled" environment where you can build some Méthode extensions. In details, VISDE, through the use of the native EM Shared Framework, allows you to build an extension panel which can run in both Prime and Swing with the same code.

VSIDE lets you develop your extensions directly inside Visual Studio Code without having to go back and forth to Prime or Swing for the testing activity, which would be a very time consuming task.

Currently VSIDE supports the creation of two types of panel: the Object Panel and the Generic Panel.

Object Panel

The Object Panel is used to modify the object metadata. It works "connected" with a single object and you can have multiple Object panels based on the object type (you can have an object panel for images and another one for stories).

Generic Panel

The generic panel is a multipurpose extension panel and it can be used to any extension you want to add to Prime or Swing.

As you you will see in the next chapter, if you choose to use React, a NodeJS project will be created. NodeJS is becoming very popular in the web development as it brings along a lot of benefits:

We want to highlight the power of the re-usability you can have with the React-NodeJS combination. React will let you create and share a lot of UI components. Moreover, using the Eidosmedia React Library you can start building your own user interface without any external inclusion. NodeJS on the middleware side lets you create shared modules which are more easy to test and maintain (for instance an XML parser module or a web service connector module).

VSIDE comes along with a Wizard that will help you through the steps of the creation process. The screenshot below shows the main screen of the Wizard. The numbers on the screenshot will guide you through the various sections of the screen to be used to create your extension

1 - Project Type

As anticipated in the introduction paragraph, VSIDE lets you create two types of panel: Object Panel and Generic Panel. In the "Project Type" section of the screen, choose the type of panel you want to create. Note that the generated code will change according to the chosen type of panel.

2 - Project Name

Type here a name to identify your project.

3 - Panel ID

Here you must enter the unique name (ID) of the panel. This id will be internally used by Prime and Swing in order to load the panel in the user interface. Since, as you will see later on, a project can have multiple panels, having a unique ID will bring along several benefits:

it lets you share the UI Components and NodeJS modules developed for one panel in all other panels it lets you have only one project for all your extensions (one repository, one deploy, etc.) it lets you have a clearly defined project so that multiple developers can work together at the same code

4 - Project Path

Enter here the path where the project will be saved.

5 - Has React Support

This option allows you to enable the react support into your project. React needs a complex development environment to be set up, by enabling this option, VSIDE will create it for you, therefore it is recommended to flag it.

6 - Has EmComponent Library Support

If you choose to have the React Support enabled (see previous step), you can also enable the inclusion of the Em React Library which lets you have a ready-to-use components that have the unique capability to follow the UI/UX of the client where the panel will run. Note that in Prime the UI will be office-like, while in Swing it will be more web oriented.

7 - WebService BaseRoot

This is a parameter used in case Prime should call external web services, it lets Prime know how to easily access them (for further information, please see the documentation of the EM Shared Panels here).

8 - Template File Name

Specify here the name of the HTML template file which will then be used to implement the panel.

9 - EomDb Connection \ 10 - Eomdb Object Path

The power of the IDE of VSIDE is that you can develop your panels directly inside the Visual Studio Code without having to go to Prime or Swing.

By enabling this feature, choosing the connection to be used, VSIDE emulates the same environment of Prime or Swing. This emulation not only starts a UI/UX but it is completed by a real back-end connection in order to let you use all the APIs that extract information from the EomDb objects.

Through these options, you will provide a back-end connection and a real EomDb object you can use as a "pilot" in your development.

For example, if you provide a path of your "pilot" report, VSIDE will emulate the same scenario you would have having the report loaded in Prime or Swing and the panel opened alongside the editor.

Once you have inserted all the requested data, as per the guidelines above, you can click on the "Create Project" button in the bottom right corner of the Wizard screen.

VSIDE will start to download all the NPM modules; note that this process can take a while.

Once finished, the environment is ready and will look similar to the example screenshot below. The numbers on the screenshot will guide you through.

1 - Explorer Area

Here you can see the files created by VSIDE. The JS file related to your panel in this case is named "panel1.js.genericpanel" and the HTML file has been named "template.html".

2 - File structure

The file "panel1.js.genericpanel" contains the interface of the Eidosmedia Shared Framework. You can start implementing the methods of the interface according to the Em Shared Framework documentation (here).

3 - Toolbar

While your are editing the panel source code (*.genericpanel or *.objectpanel) you have the option to display a real time preview of the panel. The project created with the wizard will display a react component.

The preview of the panel you are implementing contains some tools that can improve your productivity while building the extension. The screenshot below shows the preview of a generic panel; the numbers on the screenshot will guide you to use the available tools.

1 - Switch button to choose the UI

By using the Eidosmedia React Component library, the UI/UX will be always aligned with the application where the panel is currently running. During the development phase, you can easily switch between applications (Swing or Prime) by using the switch button shown in the image above. The UI will change according to the currently selected application.

2 - Available documentation

Through this button you access the documentation (namely the Storybook) of the EM React Component where you can find the list of all the available components and a lot of suggestions about the best approach for the UI/UX building.

3 - Debugger

The preview is hosted by a Visual Studio Code web view which is essentially a Chrome panel (sand-boxed). Clicking on this button you access the debugger which allows you to see the console messages and to put some breakpoints to debug your code.

4 - Auto Refresh command

The panel will be automatically updated every time you modify your code. Sometimes (mostly at the beginning of the project) this activity could be time consuming. To overcome this, you can disable the auto-update feature (and manual refresh your panel only when needed) by clicking on this button. To enable it anew, click again on the button.

5 - Offline\Online status

The OFFLINE\ONLINE message tells you if the "panel emulation" is connected with the back-end and has some valid objects to work with.

You can specify the connection\object to be used whie using the panel wizard. You can also specify or change this configuration later through the package.json file.

The package.json is the project file of every nodejs project. VSIDE has a custom section in this file used to configure some project settings including the back-end connection configuration. See the "VSIDE "package.json" Custom Properties" for more details.

In order to create a preview inside Visual Studio Code you need to have some "custom" properties inside the package.json file. These properties are the same that you usually must configure to run the panels in Prime.

Usually these properties are written by the Wizard itself during the panel creation. However, if you want, you can change some of them during the development phase. Find below an example of package.json file and its structure.

package.json file

The parameters present in the package.json file are:

VSIDE can import\export the database objects to save them into any version control system such as GIT, Subversion etc…​
VSIDE does not implement any direct function of versioning with any external program, it only gives you the possibility to "serialize" the object into the file system and viceversa.

To help the user minimize the UI gestures, the import/export functionality must be configured in the same configuration file used by VISDE to load the repository connection data (the procedure to configure the repositories and the connections is described here).

Below an example of a standard ".vside" file with one repository configured:

To enable the import/export function, you must add a new "export" property having a list of mappings which map an EomDb Folder and a file system folder, as shown below

The export property will map one or more directories of the EOMDB with as many directories on the file system. In the above example the folder "/Libraries/" of the EOMDB will be exported to\ imported from the "export1" folder of the local file system while the folder "/Temp/" of the EOMDB will be exported to\imported from the "export2" folder of the local file system.

Once the "export" property has been configured, two new buttons will be available inside the VSIDE UI: Import and Export, as you can see in the image below.

By clicking one of the buttons, the related operation will start.

After the execution of an Import or Export action, a report page will be generated and displayed. The report will give you the list of all the files imported or exported with the result of the relevant operation.

The columns of the report page will report the result of the single parts of the objects. Below the detailed description of each column:

Fld = Folder → In case of Export, it notifies if the folder was correctly created in the FS. In case of Import, the icon notifies if the folder was correctly created.

Prop = Properties → Only after the Export will notify if the file of the properties has been created and written successfully

Cont = Content → Only after an Export, it notifies if the file of the content was successfully created and written

UsrMeta = User Metadata → Only after an Export, it notifies if the file of the user metadata was successfully created and written

SysMeta = System Metadata→ Only after an Export, it notifies if the system metadata file was successfully created and written

Rls = Roles → Only after an Export, it notifies if the roles file has been successfully created and written

Save → Only after an Import, it notifies if the Eomdb correctly saved all the buffer in the EomDb.

VSIDE will leverage a specific EDAPI apis to serialize the object. For each object the following files will be created.

The Import\Export functions described here can also be performed by use of a command line, the "vside-cli", which exposes the import\export functions via the raw console with no need of the Visual Studio Code UI.

The application will exit with code "0" if everything is fine or "1" in case of error.