Skip to Content

This is part of a tutorial series on creating extension components for Design Studio.

Update!  Parts 1.9, 1.10c and 1.10d are obsolete as of Design Studio 1.6.  They will still work and we recommend that you go through the tutorial exactly as it is written here.   Please refer to the comments for more information.

Currently, there is no project wizard for creating Design Studio extensions.  Likewise, creating projects by hand from scratch is not recommended – due to complexity of configuration.  Yes, it is theoretically possible to create an Eclipse plugin project by hand, that attaches to the Design Studio extension point, but it is an order of magnitude more complex that what we’ll be doing here.  The normal, recommended workflow is to start with an existing project, clone it and modify the clone.  In this instalment, we’ll create our gauge project, using the clone method.  We will have to do some Eclipse Plugin housekeeping and some Design Studio Extension specific housekeeping in this instalment; but after this, you should be able to develop content.

Step 1.1 – Copy/Paste a project (e.g. com.sap.sample.coloredbox) and rename it.  Let’s call it “com.sap.sample.scngauge“.

/wp-content/uploads/2015/09/1_1_799473.png

/wp-content/uploads/2015/09/1_1_2_799475.png

/wp-content/uploads/2015/09/1_1_3_799477.png

Mea Culpa:  I spelled gauge incorrectly in that screenshot.  😉

Step 1.2 – In the new project, open the file  ../res/additional_properties_sheet/additional_properties_sheet.html in the editor and empty it.  At a later time, we’ll be creating a new Additional Properties Sheet (APS) page from scratch.

Step 1.3 – Open the file ../res/additional_properties_sheet/additional_properties_sheet.js in the editor and empty it.

Step 1.4 – You should be staring at an empty additional_properties_sheet.js Before we starting adding anything back to it, let’s take a moment to explain the method to the madness.  Behind the scenes, in the SDK framework, there is a Javascript class, called sap.designstudio.sdk.PropertyPage.  This class will contains a function called subclass().  This subclass function is your hook for modifying sap.designstudio.sdk.PropertyPage.  The constructor takes two input variables; a “class name” and an anonymous function.  Behind the scenes, the Design Studio will be monkey patching your code into an instance of the master class, but the dev team decided to try and increase the usability of the SDK and not force you to do it yourself. 

The “class name” variable can be anything you want.  By convention, the SDK samples follow the convention of using “<ComponentName>PropertyPage“, so that’s what we’ll use here and call our class “com.sap.sample.coloredbox.ColoredBoxPropertyPage“, but you are free to call it “Ralph” if that pleases you.

The anonymous function will be the subject of future discussion, but we’ll just leave it “blank” (i.e. function() {} ) for now.  If you don’t know what anonymous functions are, here is a good article on the subject.  Tl:dr; “Anonymous” functions are functions that you stick in place of variables; sort of a “here, execute this code” thing.

The file should look like:

sap.designstudio.sdk.PropertyPage.subclass(“com.sap.sample.scngauge.SCNGaugePropertyPage”,  function() {

});

Step 1.5 – Leave the component.css alone for now  😉  We’ll cover css usage in a later instalment.

Step 1.6 – Editing the manifest file is part of the Eclipse Plugin housekeeping that you must do.  In the manifest file (../META-INF/MANIFEST.MF), edit ID and Name.

ID =        com.sap.sample.scngauge

Name =  SCN Tutorial Gauge

Leave the version alone for now

/wp-content/uploads/2015/09/1_6_799511.png

Step 1.7 – Design Studio extensions can include new script commands.  Open the file ../contribution.ztl.  ZTL stands for Zen Template Language (Zen being the original development codename for Design Studio).  This file is where we’ll be defining our gauge components BIAL script functions in future instalments.  For now though, we won’t be defining any functions, but we’ll go over the basics of how it is structured.

Digression:

Suppose that we have an extension, named com.sap.sample.myextension, that this extension contains a component, called “MyComponent” and that MyComponent has a string property called “something“.  Suppose as well, that we’d like a getter function, in BIAL, allowing us to get the value of something in our scripts and that we’ll want to call this function getSomething().

class com.sap.sample.myextension.MyExtension extends Component {

  /* Comment. */

  String getSomething() {*

  return this.something;

  *}

}

The ZTL looks for a Java style class declaration for the component and matches it up with the proper component.

Comments within this “class” become viewable in the BIAL editor’s value help.

The ZTL parser also searches within the class for function declarations (they have the format <Returntype> <FunctionName()> and monkeypatches the new function into the ZTL library for this component type.

You might notice the “{* <JavaScript> *}” syntax.  The curly-brace/star combination is the escape sequence for nesting Javascript code into the function.

/wp-content/uploads/2015/09/1_7_799512.png

For now, simply declare the “class”, but don’t add any BIAL functions.

class com.sap.sample.scngauge.SCNGauge extends Component {

}

Step 1.8 – Right click on ../res/icon.png and select Delete.

/wp-content/uploads/2015/09/1_8_1_799518.png

Download the attached file, gauge.png.  Copy it into your ../res folder.  Right click on the project and select Refresh.

/wp-content/uploads/2015/09/1_8_2_799519.png

There should now be one file in the ../res folder, gauge.png.

/wp-content/uploads/2015/09/1_8_3_799526.png

Step 1.9 – (Update!  Still works but is deprecated.  See comments) We need to add our JavaScript bootstrapping infrastructure.  Design Studio’s SDK framework monkey patches the runtime, client-side Javascript code the same way that it does with the additional properties sheet.  The only real difference it that it is sap.designstudio.sdk.Component that will be subclassed this time.  ../res/js/component.js is where we’ll be putting our client side Javascript code in.  This file will be the core of any nontrivial extension.  For starters, it should just have a subclass declaration, with a name and an empty anonymous function as parameters.

sap.designstudio.sdk.Component.subclass(“com.sap.sample.scngauge.SCNGauge”, function() {

});

Before we continue, we want to a small edit to our component.js file.  Itis an acknowledgment that during the usage of this code, the scope may not always consistent.  this may refer to the component, but we can’t always be certain.  We do know that this is the component at bootstrap time.  So we add the line “var that = this;”.  Now, we can refer to that and know that it is the component, even if this is not anymore.  Our component.js should now look like this:

sap.designstudio.sdk.Component.subclass(“com.sap.sample.scngauge.SCNGauge”, function() {

  var that = this;

});

Step 1.10 – Last, but certainly not least (some of the other steps were prerequisites), we start working on the the extension and component metadata.  To do this, we’ll need to edit ../contribution.xml.  You can use the Eclipse XML editor’s design mode if you want, but we’ll be using the Source tab and hand editing the xml.

Step 1.10a – Define the main, Extension metadata; the attributes of the sdkExtension element.

eula= We won’t bother with an EULA, as it is outside the scope of this tutorial series..  You can leave this attribute blank, remove it or write whatever you want.

id= It is very, very, VERY important that the id here matches the ID defined in the MANIFEST.MF file.  You can copy and paste.  If the two Ids don’t match, your extension won’t work.  Note – If you extension won’t load, this attribute (and title, below) should be the first place you check when troubleshooting.

title= The same issue with ID is also present with title/name.  The title attribute in contribution.xml must be an exact match to the Name property in MANIFEST.MF, or the extension won’t load properly.  Again, you can copy and paste.

In contribution.xml, edit id and title

vendor= and version= can also be copied over from MANIFEST.MF.

Xml namespace information can simply be left as is.

Step 1.10b – Our extension will have a single component, called “SCNGauge”.  We will define the metadata for this component as attributes in a component element.

databound=”false”  Setting this attribute to true, bunds the component to a data source and we don’t want to do this just yet.

group= can be left blank for now.  We’ll add a group later.  If no groups have been defined, the component will land in a group called Custom Components.

handlerType=”div”  There are multiple options.

    •   Use “datasource” if the component that you are building is a custom data source.  Since this project is a visual component and not a datasource, we won’t use this option.
    •   Use “sapui5” if the component is going to be using the SAP UI5 library.  I’m a big fan of UI5, as it allows you to quickly build complex user interfaces.  In this project, we’ll be running a closer to the metal, so we won’t be using UI5.  Note – as of 1.5,we only support the commons (desktop) version of UI5 in SDK extensions and not yet m (Mobile).
    •   Use “cvom” if it is a chart that uses the CVOM (Lumira Visualizations). This feature will be available in 1.6.
    •   Use “div” for anything else.  This provides you with a div container in the app and you can do anything you want inside it.  Since we will be building our gauge with the D3 library, we will use div.

icon=”res/gauge.png”  This is the image file that we added in step 1.8.

id=”SCNGauge”

newInstancePrefix=”SCNGAUGE_INSTANCE”  If you don’t want the component aliases of your gauges in Design Studio apps to be SCNGAUGE_1, SCNGAUGE_2, etc. and prefer them to be called <somethingelse>_1, <somethingelse>_2, etc., you can define that here.  If you leave this property in, but blank, your component aliases will be _1, _2, etc.  Let’s add a value, such as “SCNGAUGE_INSTANCE”.  (You can also remove it entirely and its alias will be SCNGAUGE_1, SCNGAUGE_2, etc.)

propertySheetPath=”res/additional_properties_sheet/additional_properties_sheet.html”, presuming that is what you called in in step 1.2.

title=”Gauge” This is the title that the designer will see in the pallette.

tooltip=”” You can leave this blank, or write a novel.  If this was anything other than a tutorial, we’d be sure to enter a helpful clause or sentence.

visible=”true”  We certainly don’t want our gauge being invisible.

Step 1.10c – (Update!  Still works but is deprecated.  See comments) Insert an stdInclude element, before the jsInclude element.  This element allows you to tell the DS SDK that it needs to include a standard library.  You don’t need to add a stdInclude element for Jquery.  JQuery is always included.  Likewise, if sapui5 is the handler type, the ui5 library is also automatically included.  Note that if you want to use D3, you should include it via stdInclude.  You might be tempted to include it via jsInclude (see 1.9d, below), in order to get the latest and greatest version of D3.  You’d regret doing this, as D3 does not play nice with Require.js.  The D3 copy included in the DS SDK has been modified to play nice with Require.js.

Javascript was not originally meant to be a normal programming language, but was always intended to be self contained scripting for web pages.  As such, it does not include any include/import mechanism of pulling in libraries on its own and requires the web browser to handle library imports (via the HTML script element).  Require.js brings the classic “include/import”, common to most programming languages.

Step 1.10d – (Update!  Still works but is deprecated.  See comments) Leave the jsInclude and cssInclude elements as is.  You will only need to change their values if your JavaScript file is not component.js or your CSS file is not component.css.  If you wish to import another library – that is not part of the DS SDK Framework, then you can add one (or more) additional jsInclude element(s).

Step 1.10e – Remove the property elements.  We’ll be adding properties in later instalments, but for now, we’ll only use default properties.

Step 1.10f – Look in the initialization element, at its defaultValue child elements.  WIDTH and HEIGHT are default properties, inherited from the master component template.  You can leave them as is, or change their values.  Delete any other defaultValue elements, if there are any.

Step 1.10g – If you are in source mode (at the bottom of the editor, the Source tab is selected), your component.xml should now look like the following:

<?xml version=”1.0″ encoding=”UTF-8″?>

<sdkExtension

  eula=””

  id=”com.sap.sample.scngauge”

  title=”SCN Tutorial Gauge”

  vendor=”SAP”

  version=”15.1″

  xmlns=”http://www.sap.com/bi/zen/sdk

  xmlns:xsi=”http://www.w3.org/2001/XMLSchema-instance

  xsi:schemaLocation=”http://www.sap.com/bi/zen/sdk http://www.sap.com/bi/zen/sdk “>

  <license>license</license>

  <component

  databound=”false”

  group=””

  handlerType=”div”

  icon=”res/gauge.png”

  id=”SCNGauge”

  newInstancePrefix=”SCNGAUGE_INSTANCE”

  propertySheetPath=”res/additional_properties_sheet/additional_properties_sheet.html”

  title=”Gauge”

  tooltip=””

  visible=”true”>

    <stdInclude kind=”d3″/>

    <jsInclude>res/js/component.js</jsInclude>

  <cssInclude>res/css/component.css</cssInclude>

  <initialization>

  <defaultValue property=”WIDTH”>100</defaultValue>

  <defaultValue property=”HEIGHT”>100</defaultValue>

  </initialization>

  </component>

</sdkExtension>

If you are in design mode, it should look like the following:

/wp-content/uploads/2015/09/1_10_799562.png

Step 1.11 – Now you are ready to test your project.  Right click on the project.  Select Run As -> Eclipse Application.  Design studio should now be launched, so that you can debug the component.

/wp-content/uploads/2015/09/1_11_799564.png

Step 1.12 – When Design Studio starts up, create a new application.  Name your app SCNGAUGETEST and click on Finish.  It should be noted here that your normal workspace is not being used, but rather a workspace associated with Eclipse.  This means that you won’t be able to see apps that you created when you started Design Studio normally and apps created within debug sessions (i.e. you started Design Studio from Eclipse) won’t be visible when you start Design Studio the normal way.

/wp-content/uploads/2015/09/1_12_799568.png

Step 1.13 – Look in the Custom Components group of the palette (remember, we did not define a groups or assign the component to any specific groups yet).  Here you will find a green arc, with the label Gauge.

/wp-content/uploads/2015/09/1_13_799569.png

Step 1.14 – Drag the new Gauge component into the canvass and have a look at it in the properties sheet.  Here you should see all of the default properties that your component has (and that most of the default properties are bindable).

/wp-content/uploads/2015/09/1_14_799574.png

Step 1.15 – Run the app.  Your component won’t be visible, as it is just an empty div, but it should be error free.  Now your are ready to start filling in the blanks and building an actual component.

The completed extension (as of part 1) is available as a Github repository.

Next Instalment: Part 2a – Your first Steps with D3

To report this post you need to login first.

7 Comments

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

  1. Mike Howles

    David,

    I gotta say that I know this took a lot of effort to write out, so THANK YOU, and I’m going to send people to this series of tutorials first and if they still do not get it, they cannot be helped!!  🙂

    This is a terrific walkthrough with explanation along the way of the “why” are we doing each step that has to otherwise be inferred from the minimal (by intent, I understand) SAP Help developer guide.

    I wish I’d had this 2 years back!

    (0) 
  2. Vincent Dechandon

    Hello David.

    The idea of such blog is great, really.

    I have a question tho.

    In this blog post, Reiner is talking about an experimental feature that allows DS to take extension directly from a .jar file (that is the extension in itself), instead of creating a deployable package with Eclipse. I haven’t tested the feature but it was said as experimental, is this something planned to be stable soon?

    I might seems to be something light but it could actually remove hindrances faced from automated package building as it relies on unofficial Maven plug-in, custom Ant scripts, … for example.

    Br,

    Vincent

    (0) 
  3. Sandy Assum

    I double-checked everything I did to make sure I followed the steps exactly.  When I try to run the Eclipse Application, DS starts up but I do not have the option to create a new application.

    I get these messages in Eclipse.  I do not know how to debug to find what the issue is.  Any help would be appreciated.  This might not be anything but I installed Eclipse Mars but when DS starts up it is in Eclipse Luna.

    !MESSAGE Could not bind a reference of component com.sap.ip.bi.base.application.DeclaredServiceActivator. The reference is: Reference[name = IActivatorBase, interface = com.sap.ip.bi.base.bundle.IActivatorBase, policy = dynamic, cardinality = 0..n, target = null, bind = addRICActivator, unbind = removeRICActivator]

    !MESSAGE Unable to create class ‘org.eclipse.ui.internal.e4.compatibility.CompatibilityView’ from bundle ‘442’

    Thanks.

    Sandy

    (0) 
      1. Pete Letkeman

        i’m running into the same problem that you ran into Sandy, however I’m running Luna for both development and DS.

        Here are the exact messages:

        • !MESSAGE Unable to load class ‘org.eclipse.ui.internal.ide.application.addons.ModelCleanupAddon’ from bundle ‘906’
        • !MESSAGE Failed to create temporary folder
        • !MESSAGE Exception while dispatching event org.osgi.service.event.Event [topic=org/eclipse/e4/ui/model/ui/Context/context/SET] to handler org.eclipse.e4.ui.services.internal.events.UIEventHandler@554d040d
        • !MESSAGE Unable to create class ‘org.eclipse.ui.internal.e4.compatibility.CompatibilityView’ from bundle ‘917’
        • !MESSAGE Unable to resolve plug-in “platform:/plugin/org.eclipse.mylyn.tasks.ui/icons/eview16/task-list.gif”.

        Development Eclipse Environment:

        Version: Luna Service Release 2 (4.4.2)

        Build id: 20150219-0600

        DS Eclipse Environment:

        Version: 4.4.2.v20150204-1700

        Build id: M20150204-1700

        Windows 10 x64 bit

        DS: 15.1.2

        Were you able to find a fix for this?

        Pete

        (0) 
  4. David Stocker Post author

    Regarding the “deprecated” update.  In Design Studio 1.6, we introduced a more modern alternative to cssINclude, stdInclude and jsInclude (see parts 1,10c and 1.10d).  This new requireJS element is something of a “one element to rule them all”.  As this instalment was written on 1.5, the method listed was current when it was written.

    It is important to note that we did not delete the old way of doing it.  We deprecated it.  This means that it is still ok to use the “old” way and we recommend following it through the tutorial to lessen your confusion.  I wanted to finish the functionality of the gauge before revisiting the include statements and this is how this tutorial proceeds.  Part 13 of this tutorial series details the migration to requireJS.

    (0) 

Leave a Reply