Structure Based Editing (KSBasE)

[[image:attach:ksbase_logo_draft.png]]

== Project Overview ==

Related Theses:

* Michael Matzen, //A Generic Framework for Structure-Based Editing of Graphical Models in Eclipse//, March 2010 ([[pdf>>url:http://rtsys.informatik.uni-kiel.de/%7Ebiblio/downloads/theses/mim-dt.pdf||shape="rect"]])

9

* Hauke Fuhrmann, //On the Pragmatics of Graphical Modeling//, Disputation: 2011-05-05 ([[pdf>>url:http://eldiss.uni-kiel.de/macau/receive/dissertation_diss_00007185||shape="rect"]])

10

11

The KSBasE **//[Kay-space]// **project enables developers to add structure based features to an EMF-based editor. The term //structure based// refers to the fact that defined features are based on the editors EMF meta-model.

== Java Projects ==

The following Java projects belong to this project:

16

17

* de.cau.cs.kieler.ksbase - Base classes of KSBasE feature, including extension points

18

* de.cau.cs.kieler.ksbase.ui - UI contributions, e.g. a preference page (found under Preferences->KIELER->KSBasE)

19

* de.cau.cs.kieler.ksbase.feature - Feature file with the latest KSBasE-Editor

20

21

=== Example Projects[[url:http://trac.rtsys.informatik.uni-kiel.de/trac/kieler/wiki/Projects/KSBasE#ExampleProjects||shape="rect" title="Link to this section" class="anchor"]] ===

22

23

* de.cau.cs.kieler.synccharts.ksbase - Synccharts example project

24

* de.cau.cs.kieler.keg.ksbase - Graph editor example project

25

* de.cau.cs.kieler.kaom.ksbase.ptolemy - Dataflow example project

== Requirements ==

* Eclipse Indigo

* Eclipse Modeling Tools (EMF, GMF, XTend)

== Install ==

* The KSBasE project is now available in the KIELER RCP ([[http:~~/~~/rtsys.informatik.uni-kiel.de/~~~~kieler/files/nightly/>>url:http://rtsys.informatik.uni-kiel.de/%7Ekieler/files/nightly/||shape="rect" class="ext-link"]]) and the KIELER update site ([[http:~~/~~/rtsys.informatik.uni-kiel.de/~~~~kieler/updatesite/nightly/>>url:http://rtsys.informatik.uni-kiel.de/%7Ekieler/updatesite/nightly/||shape="rect" class="ext-link"]]).

35

* Or simply check out the KSBasE projects and add it to your workspace.

36

* If you want to use the KSBasE UI / Viewmanagement project, you will also need the [[KIML>>url:http://rtsys.informatik.uni-kiel.de/confluence/pages/viewpage.action?pageId=328078||shape="rect"]] and the [[Viewmanagement>>url:http://rtsys.informatik.uni-kiel.de/confluence/pages/viewpage.action?pageId=328103||shape="rect"]] projects. Be sure to check out all sub projects too.

37

38

== KSBasE Extension Libraries ==

39

40

* We provide a set of libraries to support the creation of transformations:

41

* [[Projects/KSBasE/UserDialogs>>url:http://rtsys.informatik.uni-kiel.de/confluence/display/KIELER/UserDialogs||shape="rect"]]

== How it works ==

=== Creating structure based features using extensions ===

46

47

Currently KSBasE supports Xtend1 transformations as well as Java transformations (i.e. Xtend2).

48

49

**It is recommend to create a new plug-in project for adding structure based editing features to your editor! **

50

To add fancy new features to a diagram editor you can use the eclipse extension point mechanism:

51

52

* First thing you might want to do is: Write the transformation files (see the examples below).

53

* Now to be able to use the extensions you need to add the **de.cau.cs.kieler.ksbase** project to your project dependencies (in the plugin.xml)

54

* If you are using a model file which is located in another project, you have to add this project to the dependencies, too.

55

* Last but not least: to select a diagram editor, you have to add the diagram project of the target editor to the dependencies (look for a project called //youreditor.diagram //)

56

* You can now create extensions by opening the tab 'Extensions' and click the 'Add' button.

57

* Select **de.cau.cs.kieler.ksbase.configuration** from the extension points list.

58

* Now add a configuration by right clicking the new entry and selecting 'New' -> 'configuration':

59

60

[[image:attach:ksbaseConfiguration.png]]

61

62

* When you open the new entry, you will see the details page. Please set all properties and note the tool tip informations.

63

* You also have to add some more elements to the configuration. To do this click on 'configuration' and select 'New' ->

64

** 'package' this is the ecore package used by the diagram you want to do transformations on. There may be more than one of this.

65

** 'XTendTransformationFile' The Xtend1 transformation file holding your transformation methods.

66

** 'Xtend2TransformationClass' This may be any java class holding your transformation methods. This includes classes generated by Xtend2. There should be either an XTendTransformationFile or at least one Xtend2TransformationClass present in your extension point.

67

* To specify the transformations you have to use the 'transformation' sub entry which should already be present. If that is not the case add it by using the new dialog.

68

* Again, you will have to set all the properties in the detail page. Please note that the property 'transformation' needs to be the **exact name** of the method in the transformation file you selected in the configuration element.

69

* If you want to add icons to your commands, be sure to copy them to the current project.

70

* If the transformation is only valid for a subset of the parameters, e.g. a root element may not have a successor, you can insert additional validations in the //validation// attribute, you can enter multiple methods by separating them with commas. Note that those transformations **need to return a boolean value** that is used by the KSBasE framework to disable or hide the corresponding UI contributions.

71

* Last but not least, you have to configure where the transformations should appear in your editor. You do this by setting the respective boolean field in the transformation subentry. I.e. if you set 'popup' to true the transformation button will be visible in the context menu.

72

* If the 'separator' property to true the will be a separator added before the menu entries of this transformation.

73

* It is also possible to manually add menu entries using the eclipse extension point mechnism. If you do this add the respective command id to the 'customMenuEntry' property.

74

75

[[image:attach:ksbaseTransformation.png]]

76

77

=== Creating transformations ===

78

79

We are now creating some nice and simple features for the [[Thin Kieler SyncCharts Editor>>url:http://rtsys.informatik.uni-kiel.de/confluence/pages/viewpage.action?pageId=328081||shape="rect"]]:

80

81

The first step for extending an editor is to create the model2model transformations. For the KSBasE features, those transformations are defined using Xtend.

82

To create the transformations, we are using a new package called //de.cau.cs.kieler.synccharts.transformations// and create a file called //feature.ext//.

83

Attention: You can use any package name, but the package **must be included in the build path** or else the Xtend code completion will not work.

84

Now we can start creating the transformation file. For now we will only create 2 transformations:

85

86

* Add a new state to an existing

87

* Flip the source and target of a transition

88

89

(If you'd like to see all transformations currently defined for the Synccharts Editor, you can have a look at the [[repository file>>url:http://rtsys.informatik.uni-kiel.de/fisheye/browse/kieler/plugins/de.cau.cs.kieler.synccharts.ksbase/transformations/feature.ext||shape="rect"]])

90

91

The implementation of these transformations is easy:

92

93

94

import synccharts; //First import the synccharts metamodel

95

96

//Connects two states

97

Void connectStates(State source, State target):

98

let transition = new Transition: //Create new transition

99

transition.setSourceState(source) -> //Set source

100

transition.setTargetState(target) -> //and target state

101

setSelection(transition) //Select the transition.

102

;

103

104

//Adds a successor to the given state

105

Void addSuccessorState(State source):

106

let target = new State: //Create a new target state

107

connectStates(source, target) -> //Call the connectStates extension

108

source.parentRegion.innerStates.add(target) -> //Add the new state

109

setSelection(target) //Select the new state

110

;

111

112

//Creates a default SyncChart

113

Void createDefault(Region rootRegion):

114

let state = new State: //Create a new root state

115

let innerState = new State: //Create a new inner state

116

let region = new Region: //Create a new region for the root state

117

state.setLabel("SyncChart") -> //Set name of the state

118

state.regions.add(region) -> //Add region to the state

119

innerState.setLabel("Initial") -> //Set label of the inner state

120

innerState.setIsInitial(true) -> //The state type to initial

121

region.innerStates.add(innerState) -> //Add inner state

122

rootRegion.innerStates.add(state) -> //Add root state

123

setSelection(innerState) //Select inner state

;

A few hints on creating Xtend in-place model-to-model transformations:

128

129

* You always have to use //Void// as return value, since everything else will define non in-place transformations

130

* You can define local variables using the //let// keyword (no other type assignments are allowed!)

131

* Because Xtend is a declarative language, consecutive commands are separated using the //->// operator

== FAQ ==

* **The syntax highlighting and code completion does not work when editing the .ext file!**

136

** Did you forgot to add the 'Xtend nature' to your project? Right click on the project and select 'Configure -> Add Xpand/XTend Nature'

137

* **I've added the Xtend nature, but the code completion is not working!**

138

** Did you put the Xtend file in a non-source folder? Either right click the folder that contains the Xtend file and select 'Build path -> Use as source folder, or copy the file to a folder which already is a source folder.

139

* **Ok, now the code completion works, but Xtend does not recognize my meta model**

140

** You have to add the project that contains the meta model ecore file to your project dependencies and you need to import the meta model by using the import statement with the exact name of the root element of your model (e.g. //import synccharts;// with synccharts.ecore )

141

** Please remember that it's not possible to import meta models by their namespace URI !

Wiki source code of Structure Based Editing (KSBasE)

Navigation

Quick Links