JSON Voorhees Control Documentation (v83.05.13)

The Voorhees Control is just a small JavaScript which slaps an editor over a JSON block. This will allow you to edit a JSON block using a combination schema/interface definition which controls how and what controls are displayed.

Think of this as the XSLT/XSD/Parser equivalant to XML. It can be dropped into an online application much like the online html editors such as FCKEditor or TinyMCE.

1 Quick Start

The quick start guide will help you get started with the Voorhees Control and still be home for dinner.

First, copy prototype.js, voorhees.css and voorhees.js to a folder which is accessible by your web pages.

Copy and paste the following code between your <head> tags or near the top of your web page. Make sure you point the src attribute to the location of these to js files.

<script type="text/javascript" src="prototype.js"></script>
<script type="text/javascript" src="voorhees.js"></script>
<link rel="stylesheet" type="text/css" href="voorhees.css"></script>

By including voorhees.js, you’ve automatically created an object you can use named JVoorhees

<textarea id="MyData" name="MyData"></textarea>
<script type="text/javascript">

//Make schema
var schema = {"type":"object","name":"contact","control":"object","label":"Contact","children":[
{"type":"string","name":"name","label":"Name",},
{"type":"string","name":"url","label":"URL"},
{"type":"string","name":"email","label":"Email"}
]};     

//Assign control to use data from the MyData textarea
var j = JVoorhees.create(schema,'MyData');  

</script>

2 JSON Voorhees Schema

The Voorhees Control uses a schema called the JSON Voorhees Schema to decide how to load the data and display it to the user. The schema is actually just a composite collection of one type of object. In the future as needs arise, I’m sure more objects will form but for right now, it’s just this one.

Here’s the syntax of the schema object:

{
   "type"    : string, //Required, type of data, see data types for more info.
   "name"    : string, //Not required for objects or arrays, used as key for leaf objects.
   "model"   : string, //Used to bookmark object trees for use in a future node definition.   "label"   : string, //Used on the interface to label the control.   "def"     : string, //Default value of the object
   "value"   : string, //Set the value of the object, usually only used for option controls
   "control" : string, //Control to use for object, see control types for more info
   "nullable": boolean,//Not used yet
   "help"    : string, //Not used yet
   "children": array   //Container for additional/children schema objects.

   //Tree/Branch object specific properties//     

   "default"    : string //Child, array-type branch to make default child. (makes it look kewler)
   "icon"       : string //HTML or Text general icon for tree/branch.   "add_icon"   : string //HTML or Text icon for the "add a child" control.
   "remove_icon": string //HTML or Text icon for the "remove a child" control.
   "opened_icon": string //HTML or Text icon when the branch is expanded.   "closed_icon": string //HTML or Text icon when the branch is collapsed.
   "up_icon"    : string //HTML or Text icon for the "move child up" control.
   "down_icon"  : string //HTML or Text icon for the "move child down" control.
}

Example schema:

   var schema = {"type":"object","name":"contact","control":"object","label":"Contact","children":[
      {"type":"string","name":"name","label":"Name",},
      {"type":"string","name":"url","label":"URL"},
      {"type":"string","name":"email","label":"Email"}
   ]};

The above schema creates an interface which generates a JSON block consisting of an object with three properties, "name", "url" and "email".

Here’s an illustration how how the JSON Voorhees Control all fits together.

3 Reference

Data Types

Data types are the type of data you want in the end. It has nothing to do with how the controls are displayed. This determines how the toJSON() function mines the data and gets it into the state you need.

object

Typical javascript object. Creates and expects an object { "name" : "value", …}

array

Typical javascript array. Creates and expects an array object [ "text1" , "text2" ]

string

A javascript string. Creates and expects a string. Commonly text assigned to an object property. { "property" : "string" }

boolean

A javascript boolean, true or false.

model-type

This is a custom type used to back-reference a previously created objects. In case you wanted a recursive object definition. For example, you could create an object with the model property set to "node". Then in the object’s children property, reference the object by creating an object with the type set to "node".

{"type":"array","name":"node","model":"node","children":[
   {"type":"node"}
]}

Control Types

If a control is not specified, the control will look at the type and make a guess at which control would be best. The control determines the interface widget to use for that segment of the JSON Block.

object

This will create a DIV container with the id attribute set to its unique id.

For a good example check out example 1 and example 2.

array

This will create a DIV container with an insert control allowing the user to add new elements to the array. In addition, each element within the array, will be given a remove button.

When you use the array control with a ‘object’ data type, you’ll have the ability to name the objects. Validation of unique names are not yet implemented however..

text

This will create a text input box complete with a label.

Text Box:

select

This will create a dropdown box complete with a label. The options are created by using the option control (see below) as children elements.

Select Box:

option

This must be used in as a child object within a select control object. It creates dropdown options. The only two properties that must be set for this object are value and label.

tree

Possibly the must useful control. This control doesn’t require a data type. It sets up a framework for a series of branch controls.

branch

The branch control must have a tree control as a parent somewhere. This creates an explorer-like interface for that particular JSON block. The data type of a branch MUST BE either an array or object. Any children of a branch control which are not defined as a (sub)branch, will be considered a leaf and displayed on the right pane of the tree control.

For a good example of the tree/branch controls, check out example 3 and example 4.

branch labels get special treatment – If a branch control has the label property set, and the value starts with a ‘!’, then the system will look for a child named after what follows the ‘!’, and use the value of that object to label it. So if I have a branch named "contact" with a label of ‘!name’, this will make the branch look at it’s children for a control called name and use whatever value is contained to label it. Crude but effective.