Design Studio 1.6 – Your first SDK extension, write your own colored box

Use case

You’ve installed the SDK software, loaded and executed the sample SDK projects, looked at the coloredbox example and you’re looking for the next step starting point in getting going with coding your own extension.

One idea would be to rewrite the coloredbox example yourself from scratch to understand what the minimum effort and knowledge required would be to replicate the simplest example.

In this blog we will do exactly this. It is a rewrite because we are going to move the logic to the main Java Script component file and then we can replace the box with other shapes like a circle or line.

Background

Writing your first Design Studio extension has been covered very well by David Stoker in his blog “Your first extension”. However, David’s blog is a 28-part blog so I figured it might be worth writing something a bit simpler to help more people get out the starting blocks. So the idea here is to be in a position to start writing your own simple extensions by the end of reading this blog.

That said, it means we will skip a lot of the background and you should refer back to the Developers Guide and David’s blogs for deeper insights and reasons why things work the way they do.

What the result should look like after completing these steps

Replicate the coloredbox extension:

Replace the coloredbox with a coloredcircle:

Summary of the steps we are going to follow

1. Copy the coloredbox sample project to a new extension name – “helloworld”
2. Clear the content of the new “helloworld” project files and change the internal ID’s and title
3. Execute the blank project so that Design Studio opens with the new “helloworld” blank component
4. Add the Java Script code to draw a colored box and re-execute the project. The component appears as a colored box when dragged onto the Design Studio canvas – voilà!
5. Change the Java Script code to draw other shapes like circles or lines and re-execute. The new shape appears on the canvas – voilà! voilà!

Step-by-step guide

1.  The assumption is that you have installed the SDK software and already imported the coloredbox sample project so that we can copy it as our starting point. It’s a bit ironic as we want to rewrite the coloredbox extension but it is standard practice to start all extensions by copying the simplest sample project which happens to be the coloredbox extension.

This is recommended in the Design Studio SDK developers documentation which can be found at URL = “help.sap.com”, search for “Design Studio” and open the main landing page (https://help.sap.com/viewer/p/SAP_BUSINESSOBJECTS_DESIGN_STUDIO). Navigate to the development area at the bottom of the screen where you will find the SDK help documentation as well as a link where you can download the latest sample projects which contains the coloredbox example.

After importing, right-click and copy the coloredbox project. Paste it and rename it to your own extension name. I’ve called mine “com.sap.helloworld”. You can read the SDK developers guide for naming conventions. There is nothing special about the prefix “com.sap” that will prevent your extension from working if you change this to anything else.

At this point you should see the imported sample project “coloredbox” together with your copy of it.

Execute the following menu path: “Project>Clean”.

Running this will clear the error icon.

2.  Now we need to clear all the content from the new project

The process of clearing the copied project is explained in the Developers Guide. We are going to change it slightly in one or two points.

Once you open the project subdirectory you will see all the files we are about to clear or modify:

• Manifest – change the ID so it is exactly the same as the extension name and then add the additional information for version, name and vendor.
• Additional properties sheet (html) – clear all content
• Additional properties sheet (js) – clear the body of the file and change the header
• Components cascading style sheet (css) – clear all content
• Component Java Script (js) – change subclass name to extension name and clear body of the Java Script
• Contribution.xml – change extension ID and additional information as well as the component ID and title
• Contribution.ztl – clear all content

Manifest – change the ID so it is exactly the same as the extension name. You can also change the version, Name of the extension and Vendor.

Now let’s jump down to the “contribution.xml” file and make the following changes:

• Change the sdkExtension id to be exactly the same as the manifest. In my case “com.sap.helloworld”.
• Now change the title to be exactly the same as the Name in the manifest, in my case “My Diagram”
• Change the version to be exactly the same as the manifest, “1.0”
• Change the vendor

Now there is an important conceptual idea to understand which gets reflected in the code changes we make further. Within our extension is the component that is reflected in Design Studio. The components’ id is the one that is used to name the component in Design Studio e.g. when you drag-and-drop a panel it is named PANEL_1, PANEL_2 and so on. So when our component is used it will use the component id and title and not the extensions id and title. So change the id and title to your own names. The component id will be changed to upper-case in Design Studio so in my case it will be MYDIAGRAM_1, MYDIAGRAM_2 etc and for coding purposes we will use the case sensitive id.

So when referencing code for the extension we use “com.sap.helloworld” and when referencing code for the component we use “com.sap.helloworld.myDiagram”.

Now let’s go back and clear the additional properties sheet (html). This is where we differ with the Developers Guide step 8 and simply delete everything instead of making the name change.

Additional properties sheet (js) – clear the body of the code and modify the header. Notice that the subclass for the property page is registered as the fully qualified component id appended with “PropertyPage”. Point 9 in the guide.

Components cascading style sheet (css) – clear all content

Component Java Script (js) – change the header line as in the example below and the subclass name to your component name and clear body of the Java Script. This is the file that the SDK will look to initially for the init() function that will start the processing of code for the component.

Contribution.ztl – clear all content

3. Execute the blank project so that Design Studio opens with the new “helloworld” blank component. The menu path is right-click on the project, “Run as>1. Eclipse Application”.

Design Studio should be started. Close the welcome screen and you should see the two extension components in the “Custom components” pane.

4.  Add the Java Script code to draw a colored box and re-execute the project.

The first question I wanted to know, not being an HTML expert, is “How would we draw a rectangle in HTML if we were not using Design Studio or Java Script?”.  The answer to anything html related is found at www.w3schools.com. So we find the following result:

By embedding the SVG tag in the body of our html page with the properties for width and height we secure an area on the screen into which we can place an image. Next we embed the RECT html tag with the properties for a rectangle and … voilà!  We can replace the RECT tag with CIRCLE for a circle or LINE for a straight line etc.

Now we need to get this rectangle into our html page. The SVG tag is embedded within the DIV (division) html tag. In the example below the DIV tag contains two text elements, one with the header “H3” tag and one with the paragraph “P” tag. Each of these tags attract different css styles with certain default values which rendering the text accordingly.

However, we are not going to write the html directly. Design Studio is providing a platform where all the overheads for creating and executing an html page are taken care of and we only have to provide the content by way of Java Script functions. So we need to understand how Java Script is used to dynamically write the html we see above.

So at a conceptual level if we had a raw html file with a body section and one paragraph text tag P with an ID = “p1” (text = “Hello World!” in example below) we can embed a Java Script function within the SCRIPT tag to manipulate that text and change it to, say, “New Text!” in example below. In the same way we are going to write the Java Script function which dynamically draws the box.

When Design Studio initializes your component it creates one <div> tag on the html page for you which acts as your root element into which you can place the rest of your elements and it looks at your COMPONENT.JS file for the INIT() function to start executing Java Script code which will add those elements.

You access the root <div> tag using jQuery and the reserved word “THIS” which is a pointer to your component so the syntax is “this.$()”. If jQuery is new to you goto www.w3schools.com for further explanation.

So now lets add the Java Script code to the file COMPONENT.JS to draw the rectangle.

We’re adding a variable called “me” which points to our own component and defining an INIT() function as a wrapper into which we can place our code as Design Studio will execute the INIT() function the first time the component is rendered.

The next line of code defines a variable called “myDiv” which selects the first DIV tag in the html array as per the explanation above.

The next line of code uses a Java Script include library called “d3” to select and clear any previous elements that might have existed in our <div> tag. This is required when the component is moved and redrawn on the screen. The include library is not automatically added to our project so we will add it later.

Now we create the SVG tag and “.append” it to our <div> tag and assign it a variable name “theDiagram”.  So if you look back to the raw html we have now declared an area on the screen with a certain width and height into which we can place any SVG object. We will start with a “rect” rectangle but can place any SVG object into it.

The next line of code “.append” the “rect” tag to the SVG tag “theDiagram” with it’s appropriate attributes and concludes the Java Script code required to create the html to draw the rectangle. Now the box could be replaced by a circle, a line or any other diagram which is why we’ve given the SVG tag a variable of “theDiagram” and the actual shape the appropriate name, “myBox”.

Now, before we can execute the code we must add the “d3” include library to the project and adjust the contribution.xml file slightly. Goto the “contribution.xml” file and “ADD CHILD” “stdInclude” to the component. It automatically adds the “d3” include when you drill down.

Also add the “cssInclude” child to the components and point it to “res/css/component.js”. Do NOT name this component.css which would be your inclination.

Add jsInclude child to the component and point this to your component.js file.

Now execute the project and your component output in Design Studio should be a red colored box.

If you want the rectangle to have rounded corners and a black border then refer back to the w3school for the additional parameters which are “rx”, “ry” (radius of the corner), “stroke” and “stroke-width” settings for the border.

You can add these attributes to your box and re-execute.

5.  Change the Java Script code to draw other shapes like circles or lines and re-execute.

For a circle we go back to w3school for the SVG attributes

Then change the code to comment out the box and replace it with the circle. So effectively the rectangle is removed from the SVG diagram area and the circle is appended to it.