PrototypeJungle users can (1) build compound items such as diagrams with code, but can also (2) code their own visual elements and kits, and place them in their catalog directories where they become available in PrototypeJungle's UI, and can be shared with other users. In addition, the core technology is available under the MIT Licence for use in any application (3). This document provides the information needed for all three activities.

Sections 4 - 10 describe how to work with prototype trees, the material from which all elements (referred to as "items") are made. These are the sections that are relevant to use of this core technology outside of the PrototypeJungle context. Also, the first three modules of the API section document core technology.

Before wading into the details, you might like to look at some code. Samples 2,3,4 illustrate how new visual elements are built.

1. A simple diagram.
2. An element: rectangle
3. An element with a handle: roundedRectangle. See the section below about custom controllers.
4. Building an item from data
5. A kit: ring

Select the item of interest in the catalog, and then click the "Open Code" button.

2.1 The Code Editor

The editor enables you to edit code in one window, re-run it at will, and see the results in the graphics panel immediately. If you click on the name of the source file, or on one of the dependencies, an ordinary text editor is popped on the file in question.

If you have signed in, the save as button will be active. Each signed in user is allocated a directory where files are named according to the scheme:

(<username>)/<path>

This is where the code editor saves files. You can open the code editor on a file as illustrated by this example:

 https://prototypejungle.org/code.html?source=(exampleUser)/shape/triangle.js

The main drawing program (also called the "structure editor") can be invoked in a similar way:

 https://prototypejungle.org/draw.html?source=(exampleUser)/shape/triangle.js

In addition, there is a base directory of files with names of the form:

/<path>

For example:

https://prototypejungle.org/draw.html?source=/arrow/arcArrow.js

The base directory is at the PrototypeJungle github repo (MIT license)

The underlying implementation of all of this is in the cloud at Google's FireBase.

Browser debuggers (eg Chrome's DevTools) work well with PrototypeJungle. However, the usual variants at https://prototypejungle.org/code.html and https://prototypejungle.org/draw.html catch errors, which is not what is wanted in the context of debugging. The variants https://prototypejungle.org/coded.html and https://prototypejungle.org/drawd.html (accepting exactly the same GET arguments) are provided in which errors are not caught.

The catalog panel is the area on the right side of the screen from which you drag items for insertion/swap. Initially the contents of this panel are taken entirely from a shared source, the global catalog.

However, you can build your own catalog, simply by saving any code-built item in the folder /catalog/, or in a subfolder /catalog/<whatever>. Then, the next time you start up PrototypeJungle, you will see the item under the tab (.c) or (.c)/<whatever> (resp.), where it can be used in insertions and swaps.

If you'd like to share your work, place it in the exports directory. You yourself will have access to its contents under tabs (.x) or (.x)/<whatever>. But so will other people, if they know your user name, controlled by their config file /config.json (accessible at top level from the file pulldown). Initial contents of config.json:

{
"catalogs":
  "sys/*,.exports/*,.catalog/*"
}

This can be edited to, for example

{
"catalogs":
  "sys/*,.exports/*,.catalog/*,someUserName/*
}

After this edit, the tab (someUserName) will appear in the catalog panel. When this tab is selected, the contents of that user's exports directory will appear, ready to be dragged in. If the exports directory in question contains subdirectories, tabs of the form (someUserName)/someDirectory will appear. If only the subdirectory is wanted, and not the rest of someUser's exports, then config file should look like this:

{
"catalogs":
  "sys/*,.exports/*,.catalog/*,someUserName/someDirectory"
}

More than one exports subdirectory, and more than one user, can be indicated in this manner. Of course, you can edit your own config file to access other people's exports. Generally, only the content indicated in the config file will appear in your catalog panel.

If you select an item in the catalog without dragging it into the main panel, it will be outlined with a red box indicating which catalog item has been selected. Then, if you click on "View Source" in the top bar, the code editor will open on the code which implements that catalog item. Within the code editor you can in turn navigate to the dependencies of this code. Try it with the circle.

Components are accessed and defined via core.require. Here is an example:

 core.require('/shape/circle.js','/arrow/arcArrow.js',
  function (circlePP,arrowPP) {
    let item = svg.Element.mk('<g/>');
    ...
    return item;
  }
)

This binds the variables circlePP and arrowPP to the components defined in '/shape/circle.js', and '/shape/arcArrow.js', respectively, and then calls the function (ie the last argument to core.require). The value returned by the function is the newly built component.

Now to the nitty-gritty: the structure of PrototypeJungle's data, and the operations which provide access to it.

All prototype trees (aka "items") are trees: each non-atomic child has a unique parent. (Formally, if parent.prop === child, and prop is an own property of parent, there is no parent2 with parent2 !== parent, and with parent2.prop2 === child for own property prop2 of parent2). The internal nodes in items inherit from prototypes core.ArrayNode for sequential, zero-based arrays, and core.ObjectNode for objects which are not arrays.

  
core.ObjectNode.mk();

creates a new Object, and

core.ArrayNode.mk();

a new Array.

object.set('name',child);

assigns child as a child of object with name name. If child is an Object or Array, this results in setting special properties: child.__parent === object, and child.__name === 'name'.

object.add(child);
 

also assigns child as a child of object, but automatically assigns its name.

For an Array,

array.push(child);

pushes child onto the end of array, and assigns array as the parent of child. That is, array[array.length-1] === child, and if child is an Object or Array, and child.__parent === array. Also, child.__name === array.length-1. Arrays are always sequential and zero-based.

core.lift(obj);

takes an "ordinary" JavaScript tree such as one expressable in JSON, and turns it into the PrototypeJungle kind of tree. For example:

core.lift({a:2,b:["a",4]});

will produce a Object/Array tree with matching structure.

Click here for an example of tree construction and manipulation.

var root = core.ObjectNode.mk();
var aa = core.ObjectNode.mk();
var bb = core.ObjectNode.mk();

root.set("a",aa); // adds aa as a child named "a" of root
root.set("b",bb);

// __name and __parent "glue the tree together".
bb.__name;
==>b
bb.__parent === root;
==>true

// let's add some atomic data 
aa.x = 5;  // set is not needed for atomic data or functions
aa.f = function (x) {return x*x;}

// now for an Array
var cc = core.ArrayNode.mk();
bb.set("c",cc);

cc.push(core.ObjectNode.mk().set("z",45));
cc.push(5);

          --root--
        /          \
       a            b
      / \            \
     x   f            c
    /     \            \
   5    function      [ *, 5]
                       /
                      z
                     /
                    45
   

 
var root = core.lift({a:{x:5},b:{c:[{z:45},5]}})
root.a.f = function (x) {return x*x};

a.xx = b; 

 
inode = node.instantiate();

builds an instance of node; a tree which has the same structure as node, but inherits primitive data and functions from node via prototypical inheritance. (Details here)

Serialization is performed by:

 
s = core.stringify(node);

as described here.

Nodes are constructed with core.ObjectNode.mk() and core.ArrayNode.mk(), rather than via the use of a "new". The definition of the mk method for Object is:

core.ObjectNode.mk = function () {
  return Object.create(core.ObjectNode);
}

Recall that Object.create(X) creates a new object with X as prototype.

Object is introduced simply with:

core.ObjectNode = {};

and Array with:

core.ArrayNode = [];

core.ObjectNode itself serves as the prototype for instances. In the more conventional pattern, core.ObjectNode would be a function, and the prototype property of that function, not Object itself, would be the prototype for the instances generated via the new operator (note that if F = function (){}, new F() is equivalent to Object.create(F.prototype))

The function, function.prototype, new   pattern has been available in JavaScript all along, whereas the more direct Object.create was introduced more recent years (in version 1.8.5 to be exact). PrototypeJungle employs the newer pattern, not so much for its intrinsic simplicity (though that's nice), but because this way of doing things has a major simplifying effect on the entire PrototypeJungle code base.

You will never see a "new" anywhere in the code. The convention is that for prototype X, X.mk is the creator/initializer (which may take arguments).

  svg.Element.mk(<markup>);

creates an object that inherits from the prototype svg.Element, which in turn inherits from core.ObjectNode. Its content as an SVG element is as specified by the markup. At this stage, only some of the tags are supported: clipPath, circle, g, line, linearGradient, path, polygon, polyline, rect, radialGradient, stop, text, and tspan.

Here is an example:

var circle = svg.Element.mk(
'<circle fill="rgb(39, 49, 151)" stroke="black" stroke-width="1" r="5" />'
);

Each svg.Element may have an associated coordinate system/transform. The methods getTransform, and setTransform access this, and operations such as moveto affect it. See the API section for details. As in SVG, the transforms represent coordinate systems relative to parents.

At any given time, the root of the tree being displayed by PrototypeJungle is held in core.root.

An svg.Element is displayed by construction of an associated element in the SVG DOM. The method Element.setDomAttribute(attr,vl) sets the given attribute of the DOM element asscociated with this to the given value. See the SVG documentation for the available attributes. Use of the setDomAttribute method is only occasionally necessary, because each svg.Element has a standard list of properties (eg stroke and fill) that are automatically transferred from the item to the DOM, by setting attributes in the DOM from the values of the item's properties of the same name.

Consider this snippet of code, which can be found at /example/two_circles.js

  
core.require('/shape/circle.js',
function (circlePP) {
  let item = svg.Element.mk('<g/>');
  let circleP = core.installPrototype(circlePP); 
  // set the parameters of the circle prototype
  circleP.r = 12;
  circleP.fill = 'blue';
  let circle1 = item.add(circleP.instantiate()).show();
  let circle2 = item.add(circleP.instantiate()).show();
  circle1.moveto(Point.mk(-50,0));
  circle2.moveto(Point.mk(50,0));
  return item;
  });

Consider the state of PrototypeJungle (that is, of core.root) invoked as follows

/draw.html?source=/example/two_circles.js

Here is what it looks like:

circlePP is an external component. core.installPrototype instantiates that external component, and adds its instantiation in a standard place thereby giving us an internal version circleP of the external component circlePP. That "standard place" is core.root.prototypes. installPrototype(circlePP) is nearly equivalent to

  let circleP = core.root.prototypes.add(circlePP.instantiate().hide());

but leaves out the step of automatically adding the object core.root.prototypes if it is missing. The useful consequence is that any edits to the properties of circleP, being internal to the state, will be retained when the item is saved.

In the introductory example, interactivity is implemented "under the hood" via the PrototypeJungle's graph machinery. Here is a variant which has the same behavior, ut it is implemented more directly with no dependencies on graph connections.

 
  
  item.update = function () {
    let p1=this.p1,p2 = this.p2;
    this.circle1.moveto(p1);
    this.circle2.moveto(p2);
    this.arrow1.setEnds(p1,p2);
    this.arrow2.setEnds(p2,p1);
    this.arrow1.update();
    this.arrow2.update();
  }

This method moves circle1 and circle2 to this.p1 and this.p2, respectively, and then causes the arrows to point at the circles. Updates are triggered automatically at load time, and in any circumstance of change. By "a circumstance of change" is meant one in which the implementation detects a potentially relevant event (eg editing properties in the right panel). Update methods, can, of course, be invoked explicitly. Each update method is responsible for triggering updates of its descendants (the automatic updater traverses the tree looking for update methods, but when such a method is found, it does not descend the tree further).

The code for the variant includes support for dragging in the method dragStep, which will be expla.ined in a moment.

The method

 item.initialize = function () {
   ...
 }

may be defined as well. If defined, this method is called once when the item in question is added, whether via code (core.requires), or the user interface.

In order to support resizing, an item that is intended to play the role of a visual element appearing in a catalog should follow this rule: It should define the parameters width and height, and its update method should adjust the item's SVG content to reflect these dimensions. The figure should be centered on the local origin. Examples are

/shape/rectangle.js

and

/shape/lozenge.js

In cases where the width and height are always identical, the parameter dimension should be used instead of width and height, as in

/shape/circle.js

The following lines should be included if the item you are defining is to be draggable and resizable:

 item.resizable = true;
 item.draggable = true;

To make use of a new visual element, its implementation should be stored in your catalog directory. How this is done is explained in an earlier section.

The visual elements rectangle, lozenge, and circle mentioned above handle display only. However these shapes are mostly useful as components (the border) of a container element which supports placement of text and images within the container. It is the container that you see in the global catalog, not the underlying shape. It is also desirable to support graph operations on containers. For example, we wish to be able to connect any two containers with an arrow that follows the containers around when dragged. Luckily, a few simple incantations are all that is needed to build a graph-respecting container from its border element. To see how, have a look at

/container/rectangle.js

As you'll see, the code is short and simple. The work is done in these lines:

core.require('/shape/rectangle.js','/container/container.js',
function (borderPP,containerP) {
let item = containerP.instantiate();
...
// properties to be transferred to the border
item.set('borderProperties',core.lift(['fill','stroke','stroke-width']));
item.installBorder(borderPP);
// This makes the item suitable for use as a graph vertex.
graph.installRectanglePeripheryOps(item);

The code for every container in the global library is similar. The only variation is in which "PeripheryOps" are installed (these operations define where connectors should terminate). There are at present three alternatives: graph.installCirclePeripheryOps, graph.installRectanglePeripheryOps, and graph.installLozengePeripheryOps.

Line-like shapes (such as line itself) can serve as components of connectors in an analogous fashion. As is the case for /shape/rectangle.js, /line/line.js and, for example, /line/wavyLine.js, only support drawing. A connector is something that can attach to containers, and follow them around. Connectors may also have an associated label. The code for the wavy line container is at /connector/wavyLine.js Again, it is short and simple; the work is done by:

core.require('/line/wavyLine.js','/connector/connector.js',
function (shaft,connectorP) {
let item = connectorP.instantiate();
...
//the properties to be transferred to the shaft
item.set('shaftProperties',
   core.lift(['cornerFraction','waveAmplitude','waveLength','stroke','stroke-width']));
item.installShaft(shaft);

Again, the code for every connector in the global library is similar.

In the standard catalog, there are several items that are defined from data, such as graphs, trees, and rings. Any user can edit or re-source the data, and rebuild the item to reflect the edit. Working with data is explained in the tutorial.

You can define your own items built from data. How this is done is illustrated by

 /code.html?source=/example/fromData.js

Here is an extract of the code:

core.require('/container/circle.js',function (circlePP) {

let item = svg.Element.mk('<g/>');
let dataString = '["a","b","c"]';
item.separation = 50;

item.buildFromData = function (data) {
  ... some code  ...
}

item.initialize = function () {
  this.circleP = core.installPrototype(circlePP);
  let data = item.initializeData(dataString);
  this.buildFromData(data);
}

return item;
});

An item becomes buildable from data whenever you define a method on it called "buildFromData". In this simple example, the data is an array of strings, and buildFromData constructs one circle for each string in the array, and labels the circle with that string. Please have a look at the full code.

Data-built items must also supply initial data, given as a JSON string. The method initializeData (predefined) installs that initial data.

Just as with visual elements, data-built items should be stored in your /catalog directory. That's it!

A kit is an item which incorporates specialized methods for 1) dragging and 2) deletion. A kit may also implement 3) menu buttons for manipulating the kit. Consider the tree kit, for example. It defines specialized dragging (where subtrees travel with their roots), deletion (in which subtrees are deleted along with their roots), and several menu buttons including adding a node as child or sibling, and repositioning a subtree).

1) Dragging.

The relevant code for trees is :

kit.isKit = true;

kit.dragStep = function (vertex,pos) {
 let localPos = this.vertices.toLocalCoords(pos,true);
 vertex.moveto(localPos);
 /* move all the descendants of vertex to the relative
    positions they had prior to the move of vertex
 */
 this.positionvertices(vertex);
 graph.graphUpdate();
}

kit.dragStart = function () {
  this.computeRelativePositions();
}

This code appears in /kit/arrowTree.js

In the construction of a tree from data (buildFromData) we have the line:

  vertexP.draggableInKit = true;

vertexP is the prototype for nodes in the tree.

Whenever a node defined as draggableInKit is dragged, the dragStep method of the diagram is invoked for each increment of dragging the node. Since the prototype vertexP of the vertices is defined as draggable, this property is inherited by the instances. If present, the dragStart method is called with the initial position at the start of the drag.

2) Deletion. kit.__delete(x) works in a similar fashion to allow deletion to be handled in a special way suitable to the kit. If the __delete method is defined for the kit, then when any item x within the kit is deleted, this method is called with x as argument. In the tree case, the subtree depending from x is deleted (as you will see from the code).

3) Menu buttons. The additional menu buttons for the left panel are defined as follows for the tree:

  
kit.actions = function (node) {
  let rs = [];
  if (!node) return;
  if (node.role === 'vertex') {
     rs.push({title:'Add Child',action:'addChild'});
    if (node.parentVertex) {
      rs.push({title:'Add Sibling',action:'addSibling'});
    }
    rs.push({title:'Reposition Subtree',action:'reposition'});
  }
  if (node === this) {
    rs.push({title:'Reposition Tree',action:'repositionTree'});
  }
  return rs;
}

As you can see, actions returns a list of objects each with title and method name. When an item in the kit is selected, titles appear in the left panel. Each associated method name should be defined as indicated by the example:

 
kit.addChild = function (vertex) {
  this.addDescendant(vertex,0);
  vertex.__select('svg');
}

Notice that when you select an arrow, little yellow boxes appear by which you can drag its head and tail around, and resize the head. These little yellow boxes are called "custom controls", or "handles".

To define a custom control, the two methods needed are controlPoints(), and updateControlPoint(index,pos). The controlPoints method should return a core.ArrayNode of geom.Point (s). When the item is selected, yellow handles will appear at the positions returned by controlPoints (the points should be given relative to the item's own origin). Then, when the handles are dragged, updateControlPoint(index,pos) is called at each moment of dragging, with index set to the index of the point which generated the handle being dragged, and pos to its new position. It is the responsibility of updateControlPoint to update and redisplay the item as appropriate given the new handle position. The rounded rectangle provides an example - click on the yellow square to adjust the rounding

If all three methods are defined and adjustable is set, as is the case for the rounded rectangle, the item will be displayed with both a resize box, and the custom handles.

In many items, the visible elements play varying roles. For example in graphs and trees, some shapes play the role of nodes/vertices, and some of edges. A role is assigned in code via:

item.role = <roleName>

When replacing an element in a diagram via "swap" or "swap prototype" in the top bar, only shapes whose role matches the role of the replaced element are presented as possibilities (via a highlight of the candidate shape as the mouse rolls over it).

For any item dest, the method dest.transferState(src, own), if present, transfers state from the replaced shape (src) to its replacement (dest). The own argument indicates whether only own properties should be transfered, or whether the operation should be applied to the relevant inherited properties as well. A common defintion of transferred state for basic shapes such as circles and rectangles is:

 

//own = consider only the own properties of src
item.transferState = function (src,own) { 
  core.setProperties(this,src,ui.stdTransferredProperties,own);
}
 

 const stdTransferredProperties = ['stroke','stroke-width','fill','unselectable',
   'adjustable','draggable','draggableInKit','role','text','includeEndControls'];
 

A kit might define kit.transferElementState(dest,src,own). When a shape S is replaced by R within a kit, this kit.transferElementState(R,S,own) is called as well as R.transferState(S,own). As an example, transferElementState transfers information about the descendant relation in the case of tree kits. The own flag is set or not according to whether a prototype, or an instance is being swapped.

When an item is selected in the structure editor, its properties and those of its prototype are displayed in the right-hand panel. If a property name begins with a double underbar (eg "__name"), it is not shown, and you can use this convention to hide properties from the user's view. But you can also employ ui.hide as exemplified by the following line from the implementation of the arrow

ui.hide(item,['head','shaft','end0','end1','direction','labelText']);

The subsequent line:

item.setFieldType('solidHead','boolean');

causes the solidHead property to be displayed with a true/false selection box. Similarly, in the implementation of the shadedCircle , the line

item.setFieldType('outerFill','svg.Rgb');

causes the outerFill property to be displayed with the Spectrum color picker. By default,this chooser is deployed for all fields named fill or stroke.

By default, the values of properties are editable in the property panel. But with

ui.freeze(item,[property1,property2,...propertyn]);

the given properties are presented in non-editable form.

The content that you create on PrototypeJungle is public in the partial sense that anyone who knows the URL of the content has read access to it. This allows you to share content with others by giving them URLs. There is no directory service which would allow discovery by other means. However you should not regard the content as private, either, since guesses (possibly mechanized) are always possible. PrototypeJungle content is somewhat like the content in public repositories on GitHub, but without any directory service. As at GitHub, you are encouraged to express your desires about sharing your content via a license.txt file at top level.

Private content will be supported in the future.

(Partial listing - more to come)

The core, geom, and svg modules are core technology from the prototypetrees repository.

Calls are given in the form f(arg1:type1,arg2:type2...) where types are: boolean, number,string, Node (core.ArrayNode or core.ObjectNode) or any When a call is described in more detail elsewhere in this document, a link is supplied.

Defaults for property values are given in parentheses just after the name of the property.

These calls control how property values are displayed in the structure editor.