Skip to content

Commit 389f458

Browse files
ericabouafericabouaf
committed
Some documentation
1 parent c9b903a commit 389f458

File tree

6 files changed

+178
-89
lines changed

6 files changed

+178
-89
lines changed

‎VERSION.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ Changeset:
1717

1818
* Wires enhancements
1919
* Adding labels for Wires
20-
* drawingMethod has been removed from the Wire options. Use the xtype instead.
20+
* the "drawingMethod" has been removed from the Wire options. Use the xtype instead.
2121

2222
* Containers enhancements
2323
* Bug fix: DDResize on containers redraw wires

‎guide.html‎

Lines changed: 89 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,8 @@ <h2>Chapters</h2>
9393
<a href="#visualLanguage"><span>Create your visual language</span></a>
9494

9595
<ul class="secondLevel">
96+
<li><a href="#xtypeConvention"><i>xtype</i> convention</a></li>
97+
<li><a href="#customizingWiresAndTerminals">Customizing Wires and Terminals</a></li>
9698
<li><a href="#visualLanguageDefinition">Visual Language Definition</a></li>
9799
<li><a href="#moduleDefinition">Module Definition</a></li>
98100
<li><a href="#BaseContainer">Using the basic Container</a></li>
@@ -432,18 +434,92 @@ <h3>1.4.3 Other plugins</h3>
432434

433435
<a name="visualLanguage"><h1>3 Create your visual language</h1></a>
434436

435-
<a name="visualLanguageDefinition"><h2>3.1 Visual Language Definition</h2></a>
436437

437-
<p>The visual language is defined in a JSON format :</p>
438+
<a name="xtypeConvention"><h2>3.1 <i>xtype</i> convention</h2></a>
439+
440+
<p>WireIt uses a convention to simplify extending widgets:<br />
441+
<b style="font-size: 120%;">wires, terminals and containers are instantiated from the class specified by the <i>xtype</i> property</b>.</p>
442+
443+
<p>It lets you create specialized widgets by creating a subclass and using it simply from your language definition.</p>
444+
445+
<p class="advanced">This choice was made to transport the definition using JSON.</p>
446+
447+
<a name="customizingWiresAndTerminals"><h2>3.2 Customizing Wires and Terminals</h2></a>
448+
449+
<p>Many options are available to customize Wires and Terminals, but the general pattern is simple: you create a subclass of the Wire named <i>WeirdWire</i>, you use it using the xtype property :</p>
438450

439451
<pre class="brush:js">
440-
var myLanguage = {
452+
Terminal.prototype.wireConfig = {"xtype":"WeirdWire", "weirdness": 7};
453+
</pre>
454+
455+
<p>The code above overrides the default Wire configuration for <b>all</b> terminals on the page.</p>
456+
457+
<p>If you want to use this configuration only on specified wires, you can make it default for "some" terminals. You need to subclass the terminal to set your new config as default. An exemple is actually included in the library.</p>
458+
459+
<p>For a concrete example, let's see how the TerminalOutput works :</p>
460+
461+
<pre class="brush:js">
462+
// use YUI2 class inheritance
463+
WireIt.util.TerminalOutput = function(parentEl, options, container) {
464+
WireIt.util.TerminalOutput.superclass.constructor.call(this,parentEl, options, container);
465+
};
466+
YAHOO.lang.extend(WireIt.util.TerminalOutput, WireIt.Terminal, {
467+
xtype: "WireIt.TerminalOutput",
441468

442-
// Set a unique name for the language
469+
// override some options
470+
direction: [0,1],
471+
fakeDirection: [0,-1],
472+
ddConfig: { type: "output", allowedTypes: ["input"] },
473+
alwaysSrc: true
474+
});</pre>
475+
476+
<p>Simple enough. What this says is: Create a TerminalOutput class which extends the Terminal widget, set the direction from top to bottom, and connect only to "input" terminals. The <i>alwaysSrc</i> option force this terminal as being the "source" terminal in the wire definition.</p>
477+
478+
479+
<p><b>How do we handle the wire creation ? What are the options ?</b></p>
480+
481+
<p>The idea is to create a Drag'n Drop proxy element (we do not move the original Terminal, but a copy of it).</p>
482+
483+
<p>When we start dragging the proxy element, a <i>fake</i> terminal is created within, which we can move around. A wire is added between those two terminals.</p>
484+
485+
<p>You can change the default wiring config using the <i>editingWireConfig</i> property :</p>
486+
487+
<pre class="brush:js">
488+
WeirdTerminal = function(parentEl, options, container) {
489+
WeirdTerminal.superclass.constructor.call(this,parentEl, options, container);
490+
};
491+
YAHOO.lang.extend(WeirdTerminal, WireIt.Terminal, {
492+
xtype: "WeirdTerminal",
493+
494+
wireConfig: {"xtype":"WeirdWire", "weirdness": 7},
495+
editingWireConfig: {"xtype":"WeirdWire", "weirdness": 13},
496+
direction: [1,1],
497+
fakeDirection: [-1,-1]
498+
499+
});
500+
</pre>
501+
502+
<p class="advanced">For a complete list of the properties, please refer to the API documentation for <a href="api/WireIt.Terminal.html">Terminal</a>, <a href="api/WireIt.Wire.html">Wire</a> or <a href="api/WireIt.Container.html">Container</a>.</p>
503+
504+
505+
<a name="visualLanguageDefinition"><h2>3.3 Visual Language Definition</h2></a>
506+
507+
<p>Your visual language is defined by a JSON object :</p>
508+
509+
<pre class="brush:js">
510+
var myLanguageDef = {
511+
512+
// Set a unique name for your language
443513
languageName: "myLanguage",
444514

515+
516+
// modules: list of module type definitions
445517
modules: [
446-
// List of module type definitions ...
518+
{
519+
name: "module1",
520+
container: {"xtype":"WireIt.InOutContainer", ...}
521+
},
522+
...
447523
]
448524
};
449525
</pre>
@@ -453,15 +529,15 @@ <h3>1.4.3 Other plugins</h3>
453529
<pre class="brush:js">
454530
YAHOO.util.Event.onDOMReady( function() {
455531
try {
456-
logicGates = new WireIt.WiringEditor(myLanguage);
532+
logicGates = new WireIt.WiringEditor(myLanguageDef);
457533
}catch(ex) {
458534
alert(ex);
459535
}
460536
});
461537
</pre>
462538

463539

464-
<a name="moduleDefinition"><h2>3.2 Module Definition</h2></a>
540+
<a name="moduleDefinition"><h2>3.4 Module Definition</h2></a>
465541

466542
<p>Here is the skeleton of a module definition :</p>
467543

@@ -490,7 +566,7 @@ <h3>1.4.3 Other plugins</h3>
490566
<p>Of course, you can use containers provided in WireIt (ImageContainer, FormContainer, InOutContainer), or a <a href="#containers">custom container</a>.</p>
491567

492568

493-
<a name="BaseContainer"><h2>3.3 Using the basic Container</h2></a>
569+
<a name="BaseContainer"><h2>3.5 Using the basic Container</h2></a>
494570

495571

496572
<p>Set "xtype": "WireIt.Container" (optional). The parameters are :</p>
@@ -519,7 +595,7 @@ <h3>1.4.3 Other plugins</h3>
519595
<p class="advanced">All other Container classes inherits from this base class, and therefore share the above options.</p>
520596

521597

522-
<a name="InOutContainer"><h2>3.4 Using InOutContainer</h2></a>
598+
<a name="InOutContainer"><h2>3.6 Using InOutContainer</h2></a>
523599

524600
<p>Set "xtype": "WireIt.InOutContainer". Additional parameters are :</p>
525601

@@ -542,7 +618,7 @@ <h3>1.4.3 Other plugins</h3>
542618
</pre>
543619

544620

545-
<a name="FormContainer"><h2>3.5 Using FormContainer</h2></a>
621+
<a name="FormContainer"><h2>3.7 Using FormContainer</h2></a>
546622

547623
<p>Set "xtype": "WireIt.FormContainer". Additional parameters are all those used in inputEx.Group. (see <a href="http://neyric.github.com/inputex/">inputEx</a>)</p>
548624

@@ -571,7 +647,7 @@ <h3>1.4.3 Other plugins</h3>
571647
</pre>
572648

573649

574-
<a name="ImageContainer"><h2>3.6 Using ImageContainer</h2></a>
650+
<a name="ImageContainer"><h2>3.8 Using ImageContainer</h2></a>
575651

576652
<p>Set "xtype": "WireIt.ImageContainer". Additional parameters are :</p>
577653

@@ -598,7 +674,7 @@ <h3>1.4.3 Other plugins</h3>
598674

599675

600676

601-
<a name="propertiesForm"><h2>3.7 Edit the "Properties" form</h2></a>
677+
<a name="propertiesForm"><h2>3.9 Edit the "Properties" form</h2></a>
602678

603679
<p>To add properties to the <i>Wirings</i>, we configure the <i>propertiesFields</i> property of the language definition.<br />
604680
This property defines the fields as they will appear in the "Properties" form on the right in the WiringEditor.</p>
@@ -635,7 +711,7 @@ <h3>1.4.3 Other plugins</h3>
635711

636712

637713

638-
<a name="stylingContainers"><h2>3.8 Styling containers</h2></a>
714+
<a name="stylingContainers"><h2>3.10 Styling containers</h2></a>
639715

640716
<p>The WiringEditor adds a CSS class for each module instance in your layer: <b>WiringEditor-module-<i>moduleName</i></b>.</p>
641717

‎index.html‎

Lines changed: 65 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -59,9 +59,9 @@
5959

6060
<p class="title">Documentation</p>
6161

62-
<ul>
62+
<ul class="star">
6363
<li><a href="guide.html">WireIt's Guide</a> - Getting started and advanced usage</li>
64-
<li><a href="api/index.html">API documentation</a> built with <a href="http://developer.yahoo.com/yui/yuidoc/">YUI Doc</a></li>
64+
<li><a href="api/index.html">API documentation</a></li>
6565
</ul>
6666

6767
<p>You can also get some help on the <a href="http://groups.google.com/group/wireit/">forum</a>.</p>
@@ -74,16 +74,42 @@
7474
<li><a href="http://developer.yahoo.com/yui/2/">YUI 2 documentation</a></li>
7575
</ul>
7676

77-
7877

79-
<p class="title">WireIt-based projects</p>
78+
<p class="title">Examples</p>
79+
80+
81+
<p><b>Core components examples :</b></p>
82+
83+
<ul>
84+
<li><a href="examples/presentation.html">Interactive presentation</a></li>
85+
<li><a href="examples/creating_terminals.html">Creating terminals and wires</a></li>
86+
<li><a href="examples/changing_directions.html">Changing terminal direction</a></li>
87+
<li><a href="examples/wires_and_terminals.html">Wire and Terminals configuration</a></li>
88+
<li><a href="examples/dd_and_animation.html">DragDrop and Animation utilities</a></li>
89+
<li><a href="examples/planarGame/planarGame.html">Planar game</a></li>
90+
<li><a href="examples/wire_events.html">Wire mouse events</a></li>
91+
<li><a href="examples/wire_tooltips.html">Wire context menu</a></li>
92+
</ul>
93+
94+
<p>Plugin 'editor' examples</p>
95+
<ul>
96+
<li><a href="plugins/editor/examples/WiringEditor/">WiringEditor demo</a></li>
97+
<li><a href="plugins/editor/examples/logicGates/index.html">Logic Gates demo</a></li>
98+
<li><a href="plugins/editor/examples/ajaxAdapter/">Ajax Adapter</a></li>
99+
<li><a href="plugins/editor/examples/gearsAdapter/">Gears Adapter</a></li>
100+
<li><a href="plugins/editor/examples/WiringEditor/widget.html">WiringEditor non-fullscreen</a></li>
101+
</ul>
102+
103+
<p>Plugin 'composable' examples</p>
104+
<ul>
105+
<li><a href="plugins/composable/examples/jsBox/jsBox.html">jsBox</a></li>
106+
</ul>
107+
108+
<p>Plugin 'inputex' examples</p>
80109
<ul>
81-
<li><a href="http://webhookit.com">WebhookIt</a> - visual http programming</li>
82-
<li><a href="http://tarpipe.com">Tarpipe</a> - share content across social applications</li>
83-
<li><a href="http://github.com/LeifW/pipescape/tree/master">Pipescape</a> - a WireIt interface to <a href="http://www.w3.org/TR/xproc/">XProc</a></li>
84-
<li><a href="http://graphpipes.de/">Graphpipes</a> - easy way to aggregate semantic data</li>
85-
<li><a href="http://www.talk-map.com/">TalkMap</a> - Online debating</li>
110+
<li><a href="plugins/inputex/examples/index.html">FormContainers</a></li>
86111
</ul>
112+
87113

88114
</td>
89115

@@ -150,50 +176,36 @@
150176
</a>
151177
</div>
152178

153-
<p><b>Core components examples :</b></p>
154-
155-
<ul>
156-
<li><a href="examples/presentation.html">Interactive presentation</a></li>
157-
<li><a href="examples/creating_terminals.html">Creating terminals and wires</a></li>
158-
<li><a href="examples/changing_directions.html">Changing terminal direction</a></li>
159-
<li><a href="examples/wires_and_terminals.html">Wire and Terminals configuration</a></li>
160-
<li><a href="examples/dd_and_animation.html">DragDrop and Animation utilities</a></li>
161-
<li><a href="examples/planarGame/planarGame.html">Planar game</a></li>
162-
<li><a href="examples/wire_events.html">Wire mouse events</a></li>
163-
<li><a href="examples/wire_tooltips.html">Wire context menu</a></li>
164-
<li><a href="examples/labels.html">Wire labels</a></li>
165-
<li><a href="examples/label_containers.html">Label Containers</a></li>
166-
</ul>
167-
168-
<p>Plugin 'editor' examples</p>
169-
<ul>
170-
<li><a href="plugins/editor/examples/WiringEditor/">WiringEditor demo</a></li>
171-
<li><a href="plugins/editor/examples/logicGates/index.html">Logic Gates demo</a></li>
172-
<li><a href="plugins/editor/examples/ajaxAdapter/">Ajax Adapter</a></li>
173-
<li><a href="plugins/editor/examples/gearsAdapter/">Gears Adapter</a></li>
174-
<li><a href="plugins/editor/examples/WiringEditor/widget.html">WiringEditor non-fullscreen</a></li>
175-
</ul>
176-
177-
<p>Plugin 'composable' examples</p>
178-
<ul>
179-
<li><a href="plugins/composable/examples/jsBox/jsBox.html">jsBox</a></li>
180-
</ul>
181-
182-
<p>Plugin 'grouping' examples</p>
183-
<ul>
184-
<li><a href="examples/jsBox/jsBox.html">editor example</a></li>
185-
</ul>
186-
187-
<p>Plugin 'inputex' examples</p>
188-
<ul>
189-
<li><a href="plugins/inputex/examples/index.html">FormContainers</a></li>
190-
</ul>
191-
192-
<p>Plugin 'layout' examples</p>
193-
<ul>
194-
<li><a href="plugins/layout/examples/spring_layout.html">Spring Layout</a></li>
195-
<li><a href="plugins/layout/examples/dotparser/index.html">Dot parser</a></li>
196-
</ul>
179+
<p class="title">Beta/New components</p>
180+
181+
<p>Under-development components and plugins. <a href="guide.html#contribute">You can help !</a></p>
182+
183+
<p>Core components</p>
184+
<ul>
185+
<li><a href="examples/labels.html">Wire labels</a></li>
186+
<li><a href="examples/label_containers.html">Label Containers</a></li>
187+
</ul>
188+
189+
<p>Plugin 'layout' examples</p>
190+
<ul>
191+
<li><a href="plugins/layout/examples/spring_layout.html">Spring Layout</a></li>
192+
<li><a href="plugins/layout/examples/dotparser/index.html">Dot parser</a></li>
193+
</ul>
194+
195+
<p>Plugin 'grouping' examples</p>
196+
<ul>
197+
<li><a href="examples/jsBox/jsBox.html">editor example</a></li>
198+
</ul>
199+
200+
201+
<p class="title">WireIt-based projects</p>
202+
<ul class="star">
203+
<li><a href="http://webhookit.com">WebhookIt</a> - visual http programming</li>
204+
<li><a href="http://tarpipe.com">Tarpipe</a> - share content across social applications</li>
205+
<li><a href="http://github.com/LeifW/pipescape/tree/master">Pipescape</a> - a WireIt interface to <a href="http://www.w3.org/TR/xproc/">XProc</a></li>
206+
<li><a href="http://graphpipes.de/">Graphpipes</a> - easy way to aggregate semantic data</li>
207+
<li><a href="http://www.talk-map.com/">TalkMap</a> - Online debating</li>
208+
</ul>
197209

198210
</td>
199211
</tr>

‎js/Terminal.js‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -238,7 +238,8 @@ WireIt.Terminal.prototype = {
238238
},
239239

240240
/**
241-
* TODO
241+
* Set the position of the terminal with the given pos
242+
* @param {Object | Array} pos The position. It can be used in two ways: setPosition({left: 10, top: 10}) or setPosition([10, 10]) or setPosition({bottom: 10, right: 10})
242243
*/
243244
setPosition: function(pos) {
244245
if(pos) {
@@ -271,13 +272,10 @@ WireIt.Terminal.prototype = {
271272
*/
272273
addWire: function(wire) {
273274

274-
// Adds this wire to the list of connected wires :
275275
this.wires.push(wire);
276276

277-
// Set class indicating that the wire is connected
278277
Dom.addClass(this.el, this.connectedClassName);
279278

280-
// Fire the event
281279
this.eventAddWire.fire(wire);
282280
},
283281

0 commit comments

Comments
 (0)