ninja-logo (1).png

This blog is the second one of a series of blog which we like to call “Becoming a Ninja Web IDE Developer”.

Link to the first blog can be found here

Prerequisites

  • SAP Web IDE instance – either trial or production (you can get one here: SAP HANA Cloud Platform )
  • Knowledge in UI5/JavaScript development
  • Modern web browser (chrome/firefox etc.)

Introduction

Other than Fiori/UI5 development WebIDE also allow developer to extend their WebIDE by developing a WebIDE plugin.

In this blog we will show how you can create a wizard template that will generate a new WebIDE plugin that will be located on the right side pane of the WebIDE.

The right pane plugin

The right pane extension is the most popular WebIDE plugin. If you will open WebIDE you will immediately notice that WebIDE already delivered with out of the box right pane plugins, such plugins are:

  • API Reference – provide documentation on different UI5 control that are being used by developers
  • GIT client – provide a UI to easily integrate with GIT source control
  • Search – search & replace capabilities
  • and more

/wp-content/uploads/2016/04/1_927823.png

After reading and implementing this blog you will be able to add a new icon to the right pane side of the WebIDE so when you will click on it you will see a the UI that you developed.

In this blog we will not focus on the UI implementation (it will be done on the next blog post) but we will only focus on building a template that will allow you to generate such right pane plugin in 3 clicks of a button.

The template wizard

Template wizard allow developer to generate apps and component easily. The most common scenario is to generate a new master-detail app which connected to an oData source from your backend system. each template contain steps like: name of the project, datasource, pages and more details which are required in order to generate the app.

We will use the same wizard for generate a new right pane plugin. Our wizard steps will be very simple and the result will be a new right pane plugin.

2 - template wizard.png

Few points about WebIDE plugins

  • WebIDE plugins are known also as WebIDE extensions
  • WebIDE plugins allow developers to customize their WebIDE tool.
  • WebIDE plugins are developed inside the WebIDE itself and can be run from within the WebIDE
  • After development of the plugins is done the developer can publish his/her plugin and share it with other developers (will not be covered in this blog but will be covered later)
  • WebIDE plugin can be enabled/disabled by the user at any time
  • WebIDE plugin can consume API’s which exposed by other plugins. Such API’s can be:
    • File system API’s – to access files in your repository
    • Document API
    • Events – listening to events that are published by other plugins (for example: an event that will be triggered when the user push his/her code to GIT or when a file has been changed or deleted and more)
  • WebIDE plugin must be written in JavaScript and can leverage 3-party libraries.
  • The best practice is to build the UI using the UI5 framework although it is not forced by the WebIDE
  • WebIDE itself is built from plugin those plugins are called core plugins and it was built like this in order to provide a way to extend it according to the developer requirements and needs.
  • When you want to test the WebIDE you can run your plugin from within the WebIDE and then WebIDE will open a new WebIDE instance with this plugin injected.

Plugin vs. Templates

The goal of this blog is to build a template wizard that will allow us to generate a new plugin. However what we are going to build is also a plugin because we want to extend the wizard part of WebIDE and the only way to extend it is by creating a plugin. So what we will do is to create a plugin that will generate our right pane plugin 🙂 .

/wp-content/uploads/2016/04/architecture_927913.png

As you can see from the picture above one plugin can implement multiple templates so you are not required to create a dedicated plugin each time that you want to add a new template to your wizard you can do it all in one plugin.

In this blog we will create the Template Wizard Plugin and also the Template1 (which will be the right pane in our case) and if we would like to add a new template in the future (for example generate an editor plugin etc.) we will be able to reuse the Template Wizard Plugin and create another template on top of it.

Let’s get started!

Creating the Template Wizard Plugin

We will start by creating a new empty plugin in WebIDE.

  • To create a new empty plugin please go File > New > Project from Template to open the template wizard.
  • Switch to the Plugin Development category and select the Empty Plugin tile and then click Next.

     4 - empty plugin selection.png

  • Give a name to your empty plugin of WebIDEPlugins and click Next
  • Next give a name and description to your plugin.
    • Name: templatewizardplugins
    • Description: Templates wizard plugin
  • Make sure that the include sample implementation code is unchecked and click on Next and then click on Finish

    6 - plugin name and description.png

  • After clicking on finish a new WebIDE plugin project will be generated under your workspace

    7 - new empty plugin project.png

  • This project is an empty project and contains only the skeleton of a WebIDE plugin next we will enhance it by creating a new template under it
  • The most important file in plugin project is the plugin.json file. This file contains all the plugin customizations like:
    • Which service this plugin requires from other plugins
    • Which services this plugin expose to other plugins
    • Which templates exist under this plugin
    • Which events this plugin subscribed to
    • The plugin name, description
    • And more…
  • Please notice that currently our plugin is empty it is not require anything and not expose anything
  • This plugin responsible to add a new template that will allow the user to generate a right pane plugin easily. In order to do it we will need to require some services from other WebIDE plugins and use them in our plugin. In order to do it please do the following:
    • open the plugin.json
    • under the requires block please require the following services:
      • filesystem.documentProvider
      • plugindevelopment
      • setting.project

               at the end of this step your plugin.json requires block should look like the following:
            31 - requires block.png

    • go to template:templates block and add the following line (just under the templateType key)
      “supportedProjectTypes” : [“sap.watt.uitools.ide.plugin”],

      at the end of this step your plugin.json template:templates block should look like to following:

      32 - template templates block.png

 

The Template


Create a new template

In this section we will finally do some coding. This section is the most complicated one because here we will actually do all the work in order to generate a right pane plugin.

  • Select the project that was generated on previous step (WebIDEPlugins)
  • Right click on it and Select New > More… 

          8 - new template.png

  • In the dialog select Template and click on Next

          9 - select template dialog.png

  • In the next step enter the following details:
    • Name: Right Pane
    • Description: Template for generating right pane plugin
    • Type: Project
    • Category: make sure Use existing is selected and change the category to Plugin Development so your template will be saved under the plugin development category. If you want you can also introduce your own category like: Custom Plugins or My Plugins etc. but for this demo we will use an existing one
  • Click on Next

     10 - template details.png

  • Next we will need to specify our template steps. Because we are now creating a template wizard we need to predefine the wizard steps for it. By default WebIDE will create the 2 steps for you:
    • Select a Template step – request the user to select the template (if you remember one plugin can contain multiple templates…)
    • Project Basic Info step – request the user to fill in the project name
  • Next we will need to create only one additional step to create this step simply click on the Add Step button

    11 - add step.png

  • Next we will need to specify the step type that we wish to create. WebIDE will allows you to select from different predefined steps we will select the templateCustomizationStep one because we want to create custom wizard step and not an existing one.

    12 - template customization step.png

  • Click on Next and then click on Finish.
  • WebIDE will generate a new folder under the WebIDEPlugins project folder with the name of rightpane let’s explain what exactly was created under this folder:
    • resources – a folder that will contain your plugin code this folder will contain only one file currently that we don’t really need. This folder is actually the template source code every folder and file that will be exist under this folder will be generated by our template so at the end this folder should contain the code of our right pane plugin because this is the plugin that we want to generate.
      by default WebIDE will create a file with the name sample.js.tmpl (we will understand what is tmpl in the next section) this file is just a sample file that WebIDE create so the plugin will be executable, later we will delete it but don’t delete it yet…
    • model.json – this file contains our template metadata model. This model describe our template steps, the fields and the type of the fields.
    • resources.zip – a zip file of our resources folder
    • rightpane.js – this file contains our template business logic. such business logic can be what we want to do before the template is being generated, what we want to do after the template is being generated and some custom validations that we want to apply.
  • After finishing this step we can actually run our plugin. Naturally, if we will try to use the template wizard to generate the plugin it will not be the right pane plugin that we want to generate. It will be an app that contains only one file (sample.js) with some sample code inside it. That is because the wizard result will be the resources that exist under the resources folder and in the current stage our resources folder contains only one file.

First execution of the plugin

In order to execute and test that everything that we did works as expected please do the following:

  • Select the plugin.json file (which exist under the WebIDEPlugins folder)
  • Right click on this file select Run > Run plugin project and a new WebIDE instance will be opened for you. Please notice that the new instance will be opened in a new tab, this new tab title will be Debug Mode and if you will go to the WebIDE in this tab you will see a label with the text debug mode (located on the top right and in red color).  This WebIDE instance contains the plugin that we just executed.

    14 - first run.png

    15 - run in debug mode.png

  • To test that the template is really there go to the new WebIDE instance and click on File > New  > Project from Template
  • Change the category to the category of our template (Plugin Development) and then you will be able to an additional tile with the name Right Pane

    16 - new tile .png

  • If you will click on Next and finish a new project will be generated into your workspace but a really simple one that will contain only a single file of sample.js with some text that you specified in the wizard. This is not what we want of course our goal is to generate a new right pane plugin so the only thing that left is to write the relevant code for the right pane plugin implementation.
  • Next, please close the new WebIDE instance (the one that in DEBUG MODE)

Few words about the template engine (.tmpl files)

2 sections above we explained about the resources folder content which was created by WebIDE. By default (for empty plugins) WebIDE create a new file with the name of sample.js.tmpl now we need to understand what exactly is this .tmpl file.

.tmpl files are files which contain the code that we want to generate the .tmpl at the end indicate that these files are not regular JS/HTML/CSS files but these are template files that their content can be changed in runtime when WebIDE generates the code.

This capability is required because templates are generic by nature. When you generate a new project from template you need to fill in some details which are required by the template that you are using. So your template will contain a placeholders (marked by  {{}} ) and the content of those placeholders will be changed according to the input that was entered by the user in the wizard steps.

For example: a master detail template will require from you to specify the oDATA service that you want to use, the fields that you want to show in the master section and the fields that you want to show in the detail section.

To illustrate this please open on the sample.js.tmpl file and review the code under it.

17 - sample tmpl file.png

please notice that it contains a line of var projectName = “{{projectName}}” so in runtime WebIDE will replace the content that you have specified under project name with the {{projectName}}.

The last question that needs to be answered how we can control which values will be injected in runtime. The answer is from the model.json file. In runtime WebIDE reads the content which exists under this file and replace the placeholder value with the value of the model. It’s very important to understand how to write such models and which attribute we can use.

WebIDE leverage an open source called handlebars.js provides semantic templates. If you want to learn more about what it is and how it works you can read in here: Handlebars.js: Minimal Templating on Steroids

Coding the right pane plugin

Like we explain above each plugin contains its own resources, a model file (model.json) and a plugin configuration file (plugin.json) in this section we will create all the relevant resources for our right pane plugin.

In this section it’s very important to create the folder and files with the same name as they are created in the blog. Also it’s important to keep the folder structure otherwise our plugin will not work.

  • Create all the relevant folders under the template resources folder. To create a folder under the resources folder simply select the resources folder > right click > New > Folder
    18 - create new folder under resources.png
  • Enter the first folder name that we need to create (the name is command) in the dialog and click OK
    19 - first folder.png
  • Repeat the same steps and create the following folder: css,i18n,img,service,view
    • css – will contain all the custom style sheet of your plugin
    • i18n – localization file (will not be covered in this blog post but the idea is the same like any UI5 app)
    • img – will hold the images resources. In our case it will contain only one file which is the right pane icon of our plugin
    • service – the plugin service. The service is the main entry point of the plugin runtime. The service can consume services from other plugins and can expose services to other plugins (expose of services will not be covered in this blog)
    • view – The MVC (model view controller) of our plugin. It’s always recommended to develop according to UI5 best practices also if we are developing a plugin. This file will contain our view and controller files.
  • Next we will create all the relevant files for our plugin. The first file that we will create is the command file that will be located under the command folder. To create the command file please do the following:
    • Select the command folder
    • Right click > New > File
    • Under file name write Toggle.js.tmpl (this is a template file. We know it by the .tmpl at the end)
      21 - toggle file .png
  • Repeat the same steps above and create the following files
    • style.css under the css folder
    • i18n.properties.tmpl under the i18n folder
    • plugin.png under the img folder (please download the plugin.png from this blog post and import it to the folder)
    • Pane.js.tmpl under the service folder
    • Pane.json.tmpl under the service folder
    • Pane.controller.js.tmpl under the view folder
    • Pane.view.js.tmpl under the view folder
    • plugin.json.tmpl under the resources folder
  • After creating all the resources your plugin resources folder should look like the following:

    22 - plugin project structure.png

  • Next we will write the code inside each one of the files. We recommend to you to write the code on your own and not just copy and paste it, that’s because we want you to be a Ninja and in order to be one you must write the code on your own 🙂
    • model.json – This file contains the UI config of the template wizard.
      The source code  can be found here: https://jsfiddle.net/ranhsd/3trc7xdd/
      after this step you can run the plugin again (like we did above) but this time you will see different user interface in the second step. The user interface will be different because we change the model.json file. A quick look on the model.json file will show that it contains the configuration of the plugin UI (CheckBox, TextField etc..)
    • plugin.json.tmpl – this file contains all the plugin configuration. It contains which services are required for our plugin and which services our plugin expose to other plugins. Moreover it contains the configuration of the toggle command that the plugin will react to (the toggle command is the command that open/close the right pane).
      The source code can be found here: https://jsfiddle.net/ranhsd/33rmyhpb/
    • rightpane.js – this file contains all the code that will be executed before the plugin is being generated and after the plugin generated. The source code can be found here: https://jsfiddle.net/ranhsd/0zpna5br/
    • toggle.js.tmpl – this file will contain the code of the toggle command. This command responsible to open/close the right pane. The source code can be found here: https://jsfiddle.net/ranhsd/qn080tpa/
    • style.css – the style sheet of our plugin. Currently it contains only one class because our plugin is empty. The source code can be found here: https://jsfiddle.net/ranhsd/wzhbr87n/
    • i18n.properties.tmpl – the localization file that will contain all the custom texts that will be displayed in our template wizard. Because localization of template wizard will not be cover on this blog you can just copy and paste the code. The source code can be found here: https://jsfiddle.net/ranhsd/qwdm77dz/
    • Pane.js.tmpl – This file will contain the code of the plugin service. This service is the main entry point of our plugin and it will contain methods that will be executed by the WebIDE framework in runtime. The most important methods here are configure there we will include our plugin style sheets and getContent there we will initiate the plugin UI. Notice that in this method we check if the user checked the MVC option in the wizard step and if it was checked by  the user we will initiate a new View and Controller . The source code can be found here:
      https://jsfiddle.net/ranhsd/j6xw2321/
    • Pane.json.tmpl – This file contains the configuration of our service. Configuration of plugin service in WebIDE is done in via JSON files. The most important thing to understand is the extends key because in order to create a service for a right pane plugin our service must extend from sap.watt.common.service.ui.Part which is the the interface for all the UI WebIDE extensions. The source code can be found here: https://jsfiddle.net/ranhsd/wkhktzds/
    • Pane.controller.js.tmpl – This file contains the code of the UI5 controller.
      This file will be generated only if the user checked the Include Model View Controller Code in the wizard step.  The source code can be found here: https://jsfiddle.net/ranhsd/L17yj2c4/
    • Pane.view.js.tmpl – This file contain the code of the UI5 view. Because the focus of this blog is not on the plugin UI but on the template wizard our plugin will contain only a button with “Hello World” text.
      This file will be generated only if the user checked the Include Model View Controller Code in the wizard step.  The source code can be found here: https://jsfiddle.net/ranhsd/4y8ghh0u/

That’s all the code that we need for our right pane plugin template. The last things that left now is to test it.

Test our template

In order to check that everything work as expected please do the following:

  1. Select the plugin.json file which located under the WebIDEPlugins folder
  2. Right click Run > Run Plugin Project. A new Web IDE instance will be opened in new tab
  3. Go to the new Web IDE instance and go to File > New > Project From Template to open Web IDE template wizard
  4. Change to Plugin Development category and select Right Pane tile from there. Then click on Next
  5. Give some name to the project like: myFirstRightPane and click on Next
  6. Give a name to your plugin rightpaneplugin, a short description , and under command write Toggle. Also make sure that Include Model View Controller Code is checked

    33 - test results 1.png

  7. Click Finish and you will see a new project with the name myFirstRightPane under your workspace. This project contains your right pane plugin.
    34 - test results 2.png
  8. Close the Web IDE tab (where you generate the right pane plugin) and return to the other Web IDE instance (the one that not run in debug mode)
  9. Right click on Workspace and then click on Refresh in order to refresh your Workspace.
    35 - test results 3.png
  10. Notice that a new project of myFirstRightPane added there expand this folder and select the plugin.json file
  11. Right click Run > Run Plugin Project. A new Web IDE instance will be opened
  12. The new Web IDE instance will contain an additional icon on the right pane

    36 - test results 5.png

  13. Click on this icon the right pane that we just generated will be open and you will see a button with Hello World text


          37 - test results 6.png

a video on how to test your plugin:

All the source code for part #2 can can be found under the following GIT repository: GitHub – ranhsd/WebIDEPlugins: Repository contains different WebIDE plugins so you can clone it into your Web IDE instance and run it.

That’s it 🙂


To report this post you need to login first.

Be the first to leave a comment

You must be Logged on to comment or reply to a post.

Leave a Reply