Your First Extension: Part 0 – Setting Up Eclipse
When an end user comes into contact with a Design Studio app or dashboard, it is all web content. Design Studio’s designer tool is another beast entirely. It is an Eclipse Rich Client Platform (RCP) application and leverages both Eclipse itself and the Eclipse Modeling Framework (EMF). Since our web content is going to need to live in Eclipse and in the EMF during design time, we’re going to need to supply some infrastructure to make this possible.
Eclipse is extendable. Furthermore, these Eclipse extensions (Plug-Ins) can themselves be extended if they offer up an extension point. Design Studio offers an extension point. Presuming that we’ve installed Eclipse (VERSION) and Design Studio and that they are both the same bit depth (32 and 32, or 64 and 64), we can now go about configuring Eclipse to develop Design Studio extensions.
When we’re developing our extension, were going to want to test it periodically and when we’re done, we’re going to want to create a deployable package. Therefore, we’re going to want to make sure that Eclipse knows about Design Studio and that Design Studio is a valid “thing with an extension point”. In Eclipse, this is known as a Target Platform.
Step 1 – In Eclipse, select Window -> Preferences
Step 2 – In the Preferences dialog, search for “target”. This will filter the available properties down to the Target Platform. Select Target Platform.
Step 3 – At this point, if you have never done any plugin development, then there will be no target platforms. Click on Add to create one.
Step 4 – Select “Nothing: Start with an empty target definition”.
Step 5 – We have an empty target definition. First, give it a name. Then click on the Add button, to define the actual target.
Step 6 – Since we want to use the existing Design Studio installation as the target platform, we’ll assign the directory where its executable resides as the target. Select Directory. Then navigate to Design Studio’s installation folder and select it.
Step 7 – You should see a long list of plugins in the preview pane. Select Finish.
You should now have a Target Platform defined and it should be the default. You are now ready to debug the Design Studio Extension projects that you work on.
Step 8 – Download and install the SDK samples. These are useful as a reference point in any project. If you ever find yourself asking “how do I do X”, then there is surely a sample that can help you.
As of Design Studio 1.5, the download location of the most recent version of the SDK samples is here:
Step 9 – When you are editing component properties and attributes, you’ll be doing it in XML; in the contribution.xml file.. There is a way to ensure that a particular type of XML file follows pattern. This is to conform to it’s schema definition, if there is one. The Design Studio SDK has a schema definition. If we inform Eclipse where this schema definition is, Eclipse can warn us when we’ve made an error in our contribution.xml syntax and it can even give us value help.
Navigate back to the Window -> Preferences dialog and this time, select XML -> XML Catalog, or search for XML catalog.
Step 10 – In the Add XML Catalog Element, select Add.
Step 11 – Navigate to wherever in the filesystem that you unpacked your samples and select SDK.xsd. Click on Finish and the sdk schema has been added to Eclipse.
Step 12 – Now we’re ready to import the sample SDK projects into our workspace. Select File -> Import. In the Import dialog, select General -> Existing Projects into Workspace.
Step 13 – Keep the default “Select root directory” radio button checked. Click on Browse. Navigate to the location of the projects in the filesystem (where sdk.xsd was). Select the project(s) that you wish to import.
Step 14 – Strictly speaking, Eclipse does not require you to copy the projects into the current workspace and can work with them in their original location. If you check “Copy Projects into Workspace”, Eclipse will copy the content into a newly created folder in the workspace. Doing this is good practice, as it keeps the projects together and makes them easier to port en-masse to newer versions of Eclipse or to other systems later.
Step 15 – Often, these imported projects contain metadata that was specific to the original project setup. You may see error messages and the extensions won’t be startable. To take care of this, you can command Eclipse to “clean” the metadata. With the project selected, select Project -> Clean.
Step 16 – Select Clean All Projects and then click on OK.
Step 17 – You are now ready to check and see if your setup is ready for development. Right click on the project in the Project Explorer. Select Run As -> Eclipse Application. This will start the currently active Target Platform (which should be Design Studio), with all currently open extensions installed. Keep in mind, that this instance of Design Studio will not use the same workspace as Design Studio started normally; so apps developed outside of the context of debugging components will not be visible here and the apps that you work on to test your components won’t be seen elsewhere.