concrete 0.2.0

data/doc/concrete_users_guide.txt

@@ -0,0 +1,223 @@
+= Concrete Users Guide =
+
+_Concrete_ is a generic model editor which can be configured for different
+domain specific languages (DSLs). When you use it, you use it for a predefined DSL.
+The DSL describes what the model may look like, both from a content and a visual point of view.
+See the Developers Guide if you want to setup your own DSL.
+
+This document describes the usage of the editor, independant of any specific DSL.
+
+
+== Models ==
+
+Models consist of +elements+ which may have attributes, references to other elements and may contain other elements. 
+
++Attributes+ can take one or more primitive values. Currently
+primitive values are of type +String+, +Integer+, +Float+, +Boolean+, or custom defined +Enum+ datatypes. +Enum+ types have
+a name and consist of a set of string literals, each of which is a valid instance of the type.
+
++References+ point to one or more other elements. References can not point to or take primitive values.
+
++Containment+ relationships are references with the difference that the contained element is part of the parent element,
+whereas the referenced element normally is not (there may be exceptions). When the parent element is deleted, the contained
+elements are also deleted. When the parent element is collapsed the contained elements are hidden.
+ 
+Attributes, reference and containmend relationships are called _features_ of an element. Features have names, 
+although they may not be visible.
+
+Attributes and references contain _values_ whereas containment relationships contain _elements_.
+
+
+== Navigation and Selection ==
+
+=== Selecting Elements/Values ===
+
+For all editing commands described below, at least one element or attribute/reference value needs to be selected. 
+Selection can be done with the arrow keys (+Left+, +Right+, +Up+, +Down+), with +Tab+ and +Shift-Tab+ or with the mouse.
+
+Selection with the mouse is straightforward, just click the element.
+
+Using the key +Tab+ and +Shift-Tab+, the next/previous element/value can be selected with respect to the logical order
+(instead of the graphical order on the screen). If an element has other elements or values inside, +Tab+ will select 
+the first child, and so on.
+
+In contrast to the tab keys, the arrow keys select with respect to the graphical position on the screen.
+Press one of +Left+, +Right+, +Up+, +Down+, to move the selection in the respective direction.
+When an element has other elements or values inside, the next selected element may be one of these elements.
+In order to know if the next selected element is inside or outside of the current element, you need to be aware of 
+the current _cursor_ position. The _cursor_ is a little dot on the border of the selected element/value.
+If the cursor is on the left border and you press +Right+, the next selected element will be inside of the
+current element (given that it has child elements). Otherwise, if you press +Left+, the next selected element
+will be outside, left of the current element (given that there are elements on the left). The same is true for the
+other directions, of course. If the next element would be outside but there are no elements in this direction, the 
+parent element will be selected.
+
+Hold +Shift+ down shift while moving the selection with any of the methods described above to extend to selection (_multi select_).
+
+=== Navigating References ===
+
+When you move the mouse over a valid reference value while prssing +Ctrl+, the reference target will be highlighted.
+However, you might not see the target if it is outside of the visible area on the screen.
+
+You can click the left mouse button on a valid reference value while pressing +Ctrl+ to select the reference target.
+This will automatically scroll to make the target visible.
+
+References can also be followed by pressing +Alt-Right+ while a valid reference value is selected. This will select
+the target element and scroll to make it visible. By pressing +Alt-Left+ you can go back the references in reverse order.
+
+=== Folding ===
+
+Elements with containment relationships can be collapsed using +Ctrl-Left+. This will hide the containment relationships
+including the contained elements. In order to expand the element again, press +Ctrl-Right+.
+
+You can collapse and expand elements recursively using +Ctrl-Shift-Left+ and +Ctrl-Shift-Right+. This will also
+collapse/expand child elements.
+
+In addition to this, empty features may collapse depending on the DSL configuration. This happens when you leave
+the currently selected element (i.e. select another element which is not a child). You can show all hidden featurs
+be pressing +Shift-Return+. This command also expands the current element.
+
+All collapsing commands also work with multiple elements selected.
+
+Depending on the DSL, folding may also be triggered by clicking on the fold button (e.g. a plus or minus sign).
+
+
+== Editing ==
+
+=== Edit Mode ===
+
+Whenever you want to actually edit text (e.g. to edit an attribute value or choose an element's type) you need to be in _edit mode_.
+The easiest way to enter edit mode is by just typing text while an element/value is selected. More explicitly you may also
+click the element or value while it is already selected or press +F2+ or +Ctrl-Space+.
+
+You can leave edit mode and cancel your edit by pressing +Esc+ or click the mouse somewhere outside of the current edit box.
+
+In order to leaave edit mode and actually use your changes, press +Return+, +Tab+ or +Shift-Tab+.
+If an error is detected with your input (e.g. because you entered letters for an Integer value), 
+you can not successfully leave edit mode. In this case, either correct your input or cancel edit mode.
+
+If a set of completion options is available for the current element/value, a dropdown box will be shown in edit mode
+when you start typing. You can bring up the dropdown box without typing by pressing one of the arrow keys.
+
+
+=== Creating Elements ===
+
+Elements can be created on toplevel or as children in a containment relationship. If in either place, there are no 
+other elements yet, an empty placeholder element will be shown.
+In this case, select the placeholder, enter edit mode and type the name of the element class to be created.
+Once in edit mode, a dropdown box appears showing possible completion options.
+
+If an element should be added to a set of existing elements, select one of the existing ones and press +Return+.
+This will insert a placeholder after the selected element and immediately enter edit mode.
+
+When an element is created, all features are shown although they are empty. Depending on the configuration of the
+editor, empty features may be hidden when you select a different element which is not a child. In oder to 
+show the hidden features again, press +Shift-Return+.
+
+=== Changing the Element Type ===
+
+When you enter edit mode while an element is selected, the element's type can be changed. When the type changes,
+feature values will be preserved for features which also exist in the new type.
+
+=== Deleting Elements ===
+
+Elements can be deleted by pressing +Del+. This also works if multiple elements are selected.
+
+=== Editing Attribute Values ===
+
+In a newly created element, no attribute values exist. You can create an attribute value by entering edit mode on 
+an empty value placeholder. As with elements, pressing +Return+ on a value will insert another value, pressing +Del+ removes the value.
+In case the attribute to be edited is hidden, press +Shift-Return+ to show it.
+
+=== Editing Reference Values ===
+
+Reference values can be edited in the same way as attribute values. The content of a reference value is the identifier
+of the referenced element. Use the dropdown box in edit mode to choose one of the possible target elements.
+Note, that only elements with an identifier can be referenced.
+
+=== Copy and Paste ===
+
+Both element and values can be cut, copied and pasted with +Ctrl-X+, +Ctrl-C+ and +Ctrl-V+ respectively. This also works
+with multiples elements selected. Note however, that you can not paste an attribute or reference value where an element
+is expected and vice versa.
+
+
+== Hover Information ==
+
+Some information is show only when moving the mouse over a model element or value. Make sure to focus the editor first, 
+otherwise the hovers will not appear.
+
+
+=== Errors ===
+
+The DSL defines constraints on possible models. For example, for some attributes only a single value might be
+allowed, whereas for other attributes you may provide more than one value. 
+If a constraint is violated for an element or feature, the element/feature will be marked as erroneous.
+Move the mouse over such an element in order to show the error message in a popup window.
+
+
+=== Model Information ===
+
+Depending on the concrete syntax, the feature names might be hidden. When moving the mouse over a model value, the name of the
+feature that value belongs to will be shown. Also for references, the full identifier will be shown.
+
+
+== Workbench ==
+
+Some editors might use the "workbench" functionality which comes with _Concrete_. The workbench features:
+
+* a module index view
+* a module editor view 
+* following references across modules
+* finding elements based on a index ("open element")
+* search/replace functionality
+* switchable layouts via the preferences dialog
+
+Using the workbench should be pretty much self-explanatory. Some of the commands can be invoked using hotkeys which are described
+in the command reference below.
+
+
+== Command Reference ==
+
+.Keyboard
+[frame="topbot",grid="none"]
+|=======================
+| Left, Right, Up, Down | move selection
+| Tab, Shift-Tab | move selection in sequential order, select first child if available, stop editing when in edit mode
+| Shift-Left, Shift-Right, Shift-Up, Shift-Down | extend selection (multi select)
+| Ctrl-A | select all
+| Return | insert new element/value after current element/value, stop editing when in edit mode
+| Del | delete selected element/value(s)
+| start typing, F2, Ctrl-Space | edit selected element/value (enter edit mode)
+| Esc | stop editing when in edit mode
+| Ctrl-C | copy selection to clipboard
+| Ctrl-X | cut selection to clipboard
+| Ctrl-V | insert from clipboard after selected element/value
+| Ctrl-Left | collapse element
+| Ctrl-Shift-Left | collapse element and all child elements 
+| Ctrl-Right | expand element
+| Ctrl-Shift-Right | expand element and all child elements
+| Shift-Return | show hidden features (auto-hide features will hide again when selection leaves the element)
+| Alt-Right | select reference target (jump to reference target) if a reference is selected
+| Alt-Left | jump back references in reverse order
+|=======================
+
+.Mouse
+[frame="topbot",grid="none"]
+|=======================
+| Left Click | move selection, stop editing when in edit mode
+| Shift-Left Click | extend selection (multi select)
+| Left click already selected element/value | edit selected element/value (enter edit mode)
+| Hover over element/value | show errors if present
+| Ctrl-Hover over reference | highlight reference target
+| Ctrl-Left Click | select reference target (jump to reference target)
+|=======================
+
+.Workbench Commands
+[frame="topbot",grid="none"]
+|=======================
+| Ctrl-Shift-S | save model
+| Ctrl-Shift-F | open search/replace dialog
+| Ctrl-Shift-E | open "open element" dialog
+|=======================
+

data/example/formula_editor/example_data/example1.json

@@ -0,0 +1,11 @@
+[{"_class": "Sqrt", "expr": 
+  {"_class": "Fraction", "expr1": 
+    {"_class": "Mult", "expr1": 
+      {"_class": "Value", "value": "33"}, "expr2": 
+      {"_class": "Sqrt", "expr": 
+        {"_class": "Fraction", "expr1": 
+          {"_class": "Value", "value": "5"}, "expr2": 
+          {"_class": "Plus", "expr1": 
+            {"_class": "Value", "value": "100"}, "expr2": 
+            {"_class": "Value", "value": "7"}}}}}, "expr2": 
+    {"_class": "Value", "value": "6"}}}]

data/example/formula_editor/formula_editor.html

@@ -0,0 +1,83 @@
+<html>
+	<head>
+		<link rel="stylesheet" href="../themes/cobalt.css" type="text/css" />		
+		<link rel="stylesheet" href="style.css" type="text/css" />
+		<script src="../../redist/prototype.js" type="text/javascript"></script>
+		<script src="../../redist/scriptaculous/scriptaculous.js" type="text/javascript"></script>
+		<script src="../../concrete/concrete.js" type="text/javascript"></script>
+	</head>
+	<body>
+		<div id="templates1" style="display: none">
+			<div class="ct_element ctc_Fraction" style="display: inline-block">
+				<div class="ct_containment ctn_expr1" style="text-align: center; border-bottom: 1px solid white"><span style="display: inline-block; padding: 3px"><span class="ct_slot"></span></span></div>
+				<div class="ct_containment ctn_expr2" style="text-align: center"><span style="display: inline-block; padding: 3px"><span class="ct_slot"></span></span></div>
+			</div>			
+			<div class="ct_element ctc_Sqrt" style="display: inline-block">
+				<div>
+					<div class="ct_containment ctn_expr" style=""><span style="display: inline-block; padding: 3px"><span class="ct_slot"></span></span></div>
+				</div>
+			</div>			
+			<div class="ct_element ctc_Mult" style="display: inline-block">
+				(<span class="ct_containment ctn_expr1" style="vertical-align: middle"><span class="ct_slot"></span></span>
+				<span class="ct_handle" style="vertical-align: middle">*</span>
+				<span class="ct_containment ctn_expr2" style="vertical-align: middle"><span class="ct_slot"></span></span>)
+			</div>
+			<div class="ct_element ctc_Plus" style="display: inline-block">
+				(<span class="ct_containment ctn_expr1" style="vertical-align: middle"><span class="ct_slot"></span></span>
+				<span class="ct_handle" style="vertical-align: middle">+</span>
+				<span class="ct_containment ctn_expr2" style="vertical-align: middle"><span class="ct_slot"></span></span>)
+			</div>
+			<span class="ct_element ctc_Value">
+				<span class="ct_handle">v</span>
+				(<span class="ct_attribute ctn_value"><span class="ct_slot"></span></span>)
+			</span>		
+			<span class="ct_element ctc_Neg">
+				<span class="ct_handle"></span>
+				-(<span class="ct_containment ctn_expr"><span class="ct_slot"></span></span>)
+			</span>		
+		</div>
+		<div id="metamodel1" style="display: none">
+[{"_class": "Datatype", "name": "String"}, 
+{"_class": "Class", "name": "Expression", "abstract": true}, 
+{"_class": "Class", "name": "Sqrt", "superTypes": "Expression", "features": 
+  {"_class": "Feature", "name": "expr", "kind": "containment", "lowerLimit": 1, "upperLimit": 1, "type": "Expression"}}, 
+{"_class": "Class", "name": "Fraction", "superTypes": "Expression", "features": [
+  {"_class": "Feature", "name": "expr1", "kind": "containment", "lowerLimit": 1, "upperLimit": 1, "type": "Expression"}, 
+  {"_class": "Feature", "name": "expr2", "kind": "containment", "lowerLimit": 1, "upperLimit": 1, "type": "Expression"}]}, 
+{"_class": "Class", "name": "Mult", "superTypes": "Expression", "features": [
+  {"_class": "Feature", "name": "expr1", "kind": "containment", "lowerLimit": 1, "upperLimit": 1, "type": "Expression"}, 
+  {"_class": "Feature", "name": "expr2", "kind": "containment", "lowerLimit": 1, "upperLimit": 1, "type": "Expression"}]}, 
+{"_class": "Class", "name": "Plus", "superTypes": "Expression", "features": [
+  {"_class": "Feature", "name": "expr1", "kind": "containment", "lowerLimit": 1, "upperLimit": 1, "type": "Expression"}, 
+  {"_class": "Feature", "name": "expr2", "kind": "containment", "lowerLimit": 1, "upperLimit": 1, "type": "Expression"}]}, 
+{"_class": "Class", "name": "Neg", "superTypes": "Expression", "features": 
+  {"_class": "Feature", "name": "expr", "kind": "containment", "lowerLimit": 1, "upperLimit": 1, "type": "Expression"}}, 
+{"_class": "Class", "name": "Value", "superTypes": "Expression", "features": 
+  {"_class": "Feature", "name": "value", "kind": "attribute", "lowerLimit": 1, "upperLimit": 1, "type": "String"}}]
+		</div>
+		<div class="ct_editor" id="editor1">
+		</div>
+		<br/>
+		<textarea id="clipboard1" style="background-color: white; color: black; border: 1px solid grey" cols="80" rows="10" wrap="off"></textarea>
+		</div>
+		<script type="text/javascript" language="javascript" charset="utf-8">
+			// <![CDATA[
+			var tp = new Concrete.TemplateProvider($("templates1"));
+			var mp = new Concrete.MetamodelProvider($("metamodel1").textContent.evalJSON());
+			var ip = new Concrete.QualifiedNameBasedIdentifierProvider("name");
+			var cb = new Concrete.Clipboard($("clipboard1"));
+			var ed = new Concrete.Editor($("editor1"), tp, mp, ip, {clipboard: cb});
+			
+			Event.observe(window, 'click', function(event) {
+				ed.handleEvent(event)	
+			});
+			Event.observe(window, 'keydown', function(event) {
+				ed.handleEvent(event)
+			});
+			Event.observe(window, 'mousemove', function(event) {
+				ed.handleEvent(event);
+			});
+			// ]]>
+		</script>
+	</body>
+</html>

data/example/formula_editor/style.css

@@ -0,0 +1,31 @@
+
+/* Metamodel Specific Styles
+ *****************************************************************************/
+
+/* overwrite indentation of contained elements (default) */
+
+.ct_containment {
+	padding: 0;
+}
+
+.ct_containment .ct_element {
+	margin: 0;
+}
+
+.ct_containment > .ct_slot > .ct_inline_editor {
+	margin: 0;	
+}
+
+/* use images for the square root */
+
+div.ctc_Sqrt {
+	padding-left: 19px; background: url(sqrt_vert.png) no-repeat left bottom;
+}
+
+div.ctc_Sqrt.ct_selected {
+	padding-left: 19px; background: url(sqrt_vert.png) no-repeat left bottom #001120;
+}
+
+div.ctc_Sqrt > div {
+	background: url(sqrt_horz.png) no-repeat right top;
+}

data/example/metamodel_editor/edit.rb

@@ -0,0 +1,54 @@
+require 'webrick'
+
+#
+# Simple ajax interaction with Concrete editor
+#
+# Adapt the path to the browser (Firefox or Chrome) below.
+# Startup the browser before you run this script, otherwise it might hang.
+#
+Browser = "firefox"
+Port = 1234
+
+class ConcreteServer
+	
+	def initialize(file)
+		@file = file
+		@server = WEBrick::HTTPServer.new(:Port => Port)
+		@server.mount_proc("/") do |req, res|
+			handleRequest(req, res)
+		end
+	end
+	
+	def start
+		@server.start do |sock|
+			@server.run(sock)
+		end
+	end
+	
+	private
+
+	def handleRequest(req, res)
+		if req.path == "/"
+			res.body = File.read("metamodel_editor.html").sub("<!-- json model here -->", File.read(@file))
+		elsif req.path == "/save"
+			File.open(@file, "w") {|f| f.write(req.body)}
+		elsif req.path == "/exit"
+			@server.shutdown
+    elsif req.path == "/favicon.ico"
+      # ignore
+		else
+			res.body = File.read("../.."+req.path)
+		end
+	end	
+		
+end
+
+if (ARGV.size == 0)
+	puts "Usage: edit.rb <json file>"
+	exit
+end
+
+# if the browser is not yet running the following line might block
+system "#{Browser} http://localhost:#{Port}/"
+ConcreteServer.new(ARGV[0]).start
+

data/example/metamodel_editor/example_data/formula_metamodel.json

@@ -0,0 +1,18 @@
+[{"_class": "Datatype", "name": "String"}, 
+{"_class": "Class", "name": "Expression", "abstract": true}, 
+{"_class": "Class", "name": "Sqrt", "superTypes": "Expression", "features": 
+  {"_class": "Feature", "name": "expr", "kind": "containment", "lowerLimit": 1, "upperLimit": 1, "type": "Expression"}}, 
+{"_class": "Class", "name": "Fraction", "superTypes": "Expression", "features": [
+  {"_class": "Feature", "name": "expr1", "kind": "containment", "lowerLimit": 1, "upperLimit": 1, "type": "Expression"}, 
+  {"_class": "Feature", "name": "expr2", "kind": "containment", "lowerLimit": 1, "upperLimit": 1, "type": "Expression"}]}, 
+{"_class": "Class", "name": "Mult", "superTypes": "Expression", "features": [
+  {"_class": "Feature", "name": "expr1", "kind": "containment", "lowerLimit": 1, "upperLimit": 1, "type": "Expression"}, 
+  {"_class": "Feature", "name": "expr2", "kind": "containment", "lowerLimit": 1, "upperLimit": 1, "type": "Expression"}]}, 
+{"_class": "Class", "name": "Plus", "superTypes": "Expression", "features": [
+  {"_class": "Feature", "name": "expr1", "kind": "containment", "lowerLimit": 1, "upperLimit": 1, "type": "Expression"}, 
+  {"_class": "Feature", "name": "expr2", "kind": "containment", "lowerLimit": 1, "upperLimit": 1, "type": "Expression"}]}, 
+{"_class": "Class", "name": "Neg", "superTypes": "Expression", "features": 
+  {"_class": "Feature", "name": "expr", "kind": "containment", "lowerLimit": 1, "upperLimit": 1, "type": "Expression"}}, 
+{"_class": "Class", "name": "Value", "superTypes": "Expression", "features": 
+  {"_class": "Feature", "name": "value", "kind": "attribute", "lowerLimit": 1, "upperLimit": 1, "type": "String"}}]
+

data/example/metamodel_editor/example_data/meta_metamodel.json

@@ -0,0 +1,22 @@
+[
+  {"_class": "Datatype", "name": "String"},
+  {"_class": "Datatype", "name": "Integer"},
+  {"_class": "Datatype", "name": "Boolean"},
+  {"_class": "Enum", "name": "FeatureKindType", "literals": ["attribute", "reference", "containment"]},
+  {"_class": "Class", "name": "Classifier", "abstract": true, "features": {"_class": "Feature", "name": "name", "kind": "attribute", "lowerLimit": 1, "upperLimit": 1, "type": "String"}},
+  {"_class": "Class", "name": "Datatype", "superTypes": "Classifier"},
+  {"_class": "Class", "name": "Enum", "superTypes": "Datatype", "features": {"_class": "Feature", "name": "literals", "kind": "attribute", "lowerLimit": 1, "upperLimit": -1, "type": "String"}},
+  {"_class": "Class", "name": "Class", "superTypes": "Classifier", "features": [
+    {"_class": "Feature", "name": "superTypes", "kind": "reference", "upperLimit": -1, "type": "Class"},
+    {"_class": "Feature", "name": "features", "kind": "containment", "upperLimit": -1, "type": "Feature"},
+    {"_class": "Feature", "name": "abstract", "kind": "attribute", "upperLimit": 1, "type": "Boolean"}
+  ]},
+  {"_class": "Class", "name": "Feature", "features": [
+    {"_class": "Feature", "name": "name", "kind": "attribute", "lowerLimit": 1, "upperLimit": 1, "type": "String"},
+    {"_class": "Feature", "name": "kind", "kind": "attribute", "lowerLimit": 1, "upperLimit": 1, "type": "FeatureKindType"},
+    {"_class": "Feature", "name": "lowerLimit", "kind": "attribute", "upperLimit": 1, "type": "Integer"},
+    {"_class": "Feature", "name": "upperLimit", "kind": "attribute", "upperLimit": 1, "type": "Integer"},
+    {"_class": "Feature", "name": "type", "kind": "reference", "lowerLimit": 1, "upperLimit": 1, "type": "Classifier"}
+  ]}
+]
+