Skip to content

Commit

Permalink
Some documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@ericabouaf
ericabouaf committed Sep 22, 2010
1 parent c9b903a commit 389f458
Show file tree
Hide file tree
Showing 6 changed files with 178 additions and 89 deletions.
2 changes: 1 addition & 1 deletion VERSION.txt
View file
Expand Up @@ -17,7 +17,7 @@ Changeset:

* Wires enhancements
* Adding labels for Wires
* drawingMethod has been removed from the Wire options. Use the xtype instead.
* the "drawingMethod" has been removed from the Wire options. Use the xtype instead.

* Containers enhancements
* Bug fix: DDResize on containers redraw wires
Expand Down
102 changes: 89 additions & 13 deletions guide.html
View file
Expand Up @@ -93,6 +93,8 @@ <h2>Chapters</h2>
<a href="#visualLanguage"><span>Create your visual language</span></a>

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

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

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

<p>The visual language is defined in a JSON format :</p>
<a name="xtypeConvention"><h2>3.1 <i>xtype</i> convention</h2></a>

<p>WireIt uses a convention to simplify extending widgets:<br />
<b style="font-size: 120%;">wires, terminals and containers are instantiated from the class specified by the <i>xtype</i> property</b>.</p>

<p>It lets you create specialized widgets by creating a subclass and using it simply from your language definition.</p>

<p class="advanced">This choice was made to transport the definition using JSON.</p>

<a name="customizingWiresAndTerminals"><h2>3.2 Customizing Wires and Terminals</h2></a>

<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>

<pre class="brush:js">
var myLanguage = {
Terminal.prototype.wireConfig = {"xtype":"WeirdWire", "weirdness": 7};
</pre>

<p>The code above overrides the default Wire configuration for <b>all</b> terminals on the page.</p>

<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>

<p>For a concrete example, let's see how the TerminalOutput works :</p>

<pre class="brush:js">
// use YUI2 class inheritance
WireIt.util.TerminalOutput = function(parentEl, options, container) {
WireIt.util.TerminalOutput.superclass.constructor.call(this,parentEl, options, container);
};
YAHOO.lang.extend(WireIt.util.TerminalOutput, WireIt.Terminal, {
xtype: "WireIt.TerminalOutput",

// Set a unique name for the language
// override some options
direction: [0,1],
fakeDirection: [0,-1],
ddConfig: { type: "output", allowedTypes: ["input"] },
alwaysSrc: true
});</pre>

<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>


<p><b>How do we handle the wire creation ? What are the options ?</b></p>

<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>

<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>

<p>You can change the default wiring config using the <i>editingWireConfig</i> property :</p>

<pre class="brush:js">
WeirdTerminal = function(parentEl, options, container) {
WeirdTerminal.superclass.constructor.call(this,parentEl, options, container);
};
YAHOO.lang.extend(WeirdTerminal, WireIt.Terminal, {
xtype: "WeirdTerminal",

wireConfig: {"xtype":"WeirdWire", "weirdness": 7},
editingWireConfig: {"xtype":"WeirdWire", "weirdness": 13},
direction: [1,1],
fakeDirection: [-1,-1]

});
</pre>

<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>


<a name="visualLanguageDefinition"><h2>3.3 Visual Language Definition</h2></a>

<p>Your visual language is defined by a JSON object :</p>

<pre class="brush:js">
var myLanguageDef = {

// Set a unique name for your language
languageName: "myLanguage",


// modules: list of module type definitions
modules: [
// List of module type definitions ...
{
name: "module1",
container: {"xtype":"WireIt.InOutContainer", ...}
},
...
]
};
</pre>
Expand All @@ -453,15 +529,15 @@ <h3>1.4.3 Other plugins</h3>
<pre class="brush:js">
YAHOO.util.Event.onDOMReady( function() {
try {
logicGates = new WireIt.WiringEditor(myLanguage);
logicGates = new WireIt.WiringEditor(myLanguageDef);
}catch(ex) {
alert(ex);
}
});
</pre>


<a name="moduleDefinition"><h2>3.2 Module Definition</h2></a>
<a name="moduleDefinition"><h2>3.4 Module Definition</h2></a>

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

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


<a name="BaseContainer"><h2>3.3 Using the basic Container</h2></a>
<a name="BaseContainer"><h2>3.5 Using the basic Container</h2></a>


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


<a name="InOutContainer"><h2>3.4 Using InOutContainer</h2></a>
<a name="InOutContainer"><h2>3.6 Using InOutContainer</h2></a>

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

Expand All @@ -542,7 +618,7 @@ <h3>1.4.3 Other plugins</h3>
</pre>


<a name="FormContainer"><h2>3.5 Using FormContainer</h2></a>
<a name="FormContainer"><h2>3.7 Using FormContainer</h2></a>

<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>

Expand Down Expand Up @@ -571,7 +647,7 @@ <h3>1.4.3 Other plugins</h3>
</pre>


<a name="ImageContainer"><h2>3.6 Using ImageContainer</h2></a>
<a name="ImageContainer"><h2>3.8 Using ImageContainer</h2></a>

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

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



<a name="propertiesForm"><h2>3.7 Edit the "Properties" form</h2></a>
<a name="propertiesForm"><h2>3.9 Edit the "Properties" form</h2></a>

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



<a name="stylingContainers"><h2>3.8 Styling containers</h2></a>
<a name="stylingContainers"><h2>3.10 Styling containers</h2></a>

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

Expand Down
118 changes: 65 additions & 53 deletions index.html
View file
Expand Up @@ -59,9 +59,9 @@

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

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

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



<p class="title">WireIt-based projects</p>
<p class="title">Examples</p>


<p><b>Core components examples :</b></p>

<ul>
<li><a href="examples/presentation.html">Interactive presentation</a></li>
<li><a href="examples/creating_terminals.html">Creating terminals and wires</a></li>
<li><a href="examples/changing_directions.html">Changing terminal direction</a></li>
<li><a href="examples/wires_and_terminals.html">Wire and Terminals configuration</a></li>
<li><a href="examples/dd_and_animation.html">DragDrop and Animation utilities</a></li>
<li><a href="examples/planarGame/planarGame.html">Planar game</a></li>
<li><a href="examples/wire_events.html">Wire mouse events</a></li>
<li><a href="examples/wire_tooltips.html">Wire context menu</a></li>
</ul>

<p>Plugin 'editor' examples</p>
<ul>
<li><a href="plugins/editor/examples/WiringEditor/">WiringEditor demo</a></li>
<li><a href="plugins/editor/examples/logicGates/index.html">Logic Gates demo</a></li>
<li><a href="plugins/editor/examples/ajaxAdapter/">Ajax Adapter</a></li>
<li><a href="plugins/editor/examples/gearsAdapter/">Gears Adapter</a></li>
<li><a href="plugins/editor/examples/WiringEditor/widget.html">WiringEditor non-fullscreen</a></li>
</ul>

<p>Plugin 'composable' examples</p>
<ul>
<li><a href="plugins/composable/examples/jsBox/jsBox.html">jsBox</a></li>
</ul>

<p>Plugin 'inputex' examples</p>
<ul>
<li><a href="http://webhookit.com">WebhookIt</a> - visual http programming</li>
<li><a href="http://tarpipe.com">Tarpipe</a> - share content across social applications</li>
<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>
<li><a href="http://graphpipes.de/">Graphpipes</a> - easy way to aggregate semantic data</li>
<li><a href="http://www.talk-map.com/">TalkMap</a> - Online debating</li>
<li><a href="plugins/inputex/examples/index.html">FormContainers</a></li>
</ul>


</td>

Expand Down Expand Up @@ -150,50 +176,36 @@
</a>
</div>

<p><b>Core components examples :</b></p>

<ul>
<li><a href="examples/presentation.html">Interactive presentation</a></li>
<li><a href="examples/creating_terminals.html">Creating terminals and wires</a></li>
<li><a href="examples/changing_directions.html">Changing terminal direction</a></li>
<li><a href="examples/wires_and_terminals.html">Wire and Terminals configuration</a></li>
<li><a href="examples/dd_and_animation.html">DragDrop and Animation utilities</a></li>
<li><a href="examples/planarGame/planarGame.html">Planar game</a></li>
<li><a href="examples/wire_events.html">Wire mouse events</a></li>
<li><a href="examples/wire_tooltips.html">Wire context menu</a></li>
<li><a href="examples/labels.html">Wire labels</a></li>
<li><a href="examples/label_containers.html">Label Containers</a></li>
</ul>

<p>Plugin 'editor' examples</p>
<ul>
<li><a href="plugins/editor/examples/WiringEditor/">WiringEditor demo</a></li>
<li><a href="plugins/editor/examples/logicGates/index.html">Logic Gates demo</a></li>
<li><a href="plugins/editor/examples/ajaxAdapter/">Ajax Adapter</a></li>
<li><a href="plugins/editor/examples/gearsAdapter/">Gears Adapter</a></li>
<li><a href="plugins/editor/examples/WiringEditor/widget.html">WiringEditor non-fullscreen</a></li>
</ul>

<p>Plugin 'composable' examples</p>
<ul>
<li><a href="plugins/composable/examples/jsBox/jsBox.html">jsBox</a></li>
</ul>

<p>Plugin 'grouping' examples</p>
<ul>
<li><a href="examples/jsBox/jsBox.html">editor example</a></li>
</ul>

<p>Plugin 'inputex' examples</p>
<ul>
<li><a href="plugins/inputex/examples/index.html">FormContainers</a></li>
</ul>

<p>Plugin 'layout' examples</p>
<ul>
<li><a href="plugins/layout/examples/spring_layout.html">Spring Layout</a></li>
<li><a href="plugins/layout/examples/dotparser/index.html">Dot parser</a></li>
</ul>
<p class="title">Beta/New components</p>

<p>Under-development components and plugins. <a href="guide.html#contribute">You can help !</a></p>

<p>Core components</p>
<ul>
<li><a href="examples/labels.html">Wire labels</a></li>
<li><a href="examples/label_containers.html">Label Containers</a></li>
</ul>

<p>Plugin 'layout' examples</p>
<ul>
<li><a href="plugins/layout/examples/spring_layout.html">Spring Layout</a></li>
<li><a href="plugins/layout/examples/dotparser/index.html">Dot parser</a></li>
</ul>

<p>Plugin 'grouping' examples</p>
<ul>
<li><a href="examples/jsBox/jsBox.html">editor example</a></li>
</ul>


<p class="title">WireIt-based projects</p>
<ul class="star">
<li><a href="http://webhookit.com">WebhookIt</a> - visual http programming</li>
<li><a href="http://tarpipe.com">Tarpipe</a> - share content across social applications</li>
<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>
<li><a href="http://graphpipes.de/">Graphpipes</a> - easy way to aggregate semantic data</li>
<li><a href="http://www.talk-map.com/">TalkMap</a> - Online debating</li>
</ul>

</td>
</tr>
Expand Down
6 changes: 2 additions & 4 deletions js/Terminal.js
View file
Expand Up @@ -238,7 +238,8 @@ WireIt.Terminal.prototype = {
},

/**
* TODO
* Set the position of the terminal with the given pos
* @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})
*/
setPosition: function(pos) {
if(pos) {
Expand Down Expand Up @@ -271,13 +272,10 @@ WireIt.Terminal.prototype = {
*/
addWire: function(wire) {

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

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

// Fire the event
this.eventAddWire.fire(wire);
},

Expand Down

0 comments on commit 389f458

Please sign in to comment.