auto-views

Auto-Views component family

introduction

the auto-views component family includes components that genarate views from JSON schemas.

the json schemas are based on a subset of the json schema syntax JSONschema.org.

by using a common schema and different view-Generators we can create many different views from the same schema

example

the json schema

{
  "$id": "http://example.com/user",
  "type":"object",
  "title":"User",
  "properties":{
    "fName":{
      "type":"string",
      "title":"First name"
    },
    "lName":{
      "type":"string",
      "title":"Last name"
    },
    "age":{
      "type":"number",
      "title":"Age"
    }
  }
}

can be generated into:

the following view:

<AutoForm schemaId="http://example.com/user" view="view" value={{fName:'Derrick',lName:'Freeman',age:37}}/>

the following editing view:

<AutoForm schemaId="http://example.com/user" view="edit" value={{fName:'Derrick',lName:'Freeman',age:37}}/>

the following table view:

<AutoGrid schemaId="http://example.com/user" view="edit" value={[{fName:'Derrick',lName:'Freeman',age:37}...]}/>

and the following list view:

<AutoThumbnailForm schemaId="http://example.com/user" view="edit" value={[{fName:'Derrick',lName:'Freeman',age:37}...]}/>

exports

• schema-repo - repository of view schemas
• auto-form - React component for generating a form view from a schema
• auto-thumb - TBD
• auto-thumbnail-form- TBD
• auto-list-form- TBD
• auto-grid-view - TBD
• auto-table-edit - TBD

syntax

the schemas are defined in JSON format with the minimal schema {} representing "any" type.

meta-data

the following meta-data fields are supported:

• $id: unique id of the schema in URI format
• title: readable title
• description: short description

validation/typings

a schema can denote its acceptable type/types using the type keyword, available options: "string","number","boolean","null","array" or "object"

example

{
  "$id":"http://example.com/product",
  "title":"Product",
  "type":"object"
}

each type adds its own validation keywords:

number validation keywords

• multipleOf : number
• maximum : number
• exclusiveMaximum: boolean, defaults to false, does maximum N allow N?
• minimum : number
• exclusiveMinimum: boolean, defaults to false, does minimum N allow N?

string validation keywords

• maxLength : number
• minLength : number
• pattern: regExp to match against value
• format : "email" / "URI" / "date-time"
• enum: array of string options to allow

object validation keywords

• properties : propertyName to schema object
• additionalProperties : schema to match when property name does not match any defined property ( having only additionalProperties schema is describing a map)
• required: array of required props

{
  "$id":"http://example.com/person",
  "type":"object",
  "properties":{
    "lastName":{
      "type":"string"
    }
  }
}

// a named property called "lastName" with value of type string



{
  "$id":"http://example.com/stringToNumberMap",
  "type":"object",
  "additionalProperties":{
      "type":"number"
  }
}

//string to number map example

array validation keywords

• items : schema of the child items
• maxItems : number
• minItems : number
• uniqueItems: booelan /* no duplicates allowed */

ref - referncing schemas

a schema can reference another schema usinng the ref keyword

{
  "$id":"http://example.com/person",
  "type":"object",
  "properties":{
    "lastName":{
      "type":"string"
    }
  }
}


{
  "$id":"http://example.com/task",
  "type":"object",
  "properties":{
    "owner":{
      "$ref":"http://example.com/person"
    }
  }
}

//the task schema refernces the person schema

oneOf - union between complex types

a schema can be defined as a union between other schemas

{
  "$id":"http://example.com/image",
  "type":"object",
  "properties":{
    "src":{
      "type":"string"
    }
  }
}

{
  "$id":"http://example.com/video",
  "type":"object",
  "properties":{
    "src":{
      "type":"string"
    }
  }
}



{
  "$id":"http://example.com/post",
  "type":"object",
  "properties":{
    "media":{
      "$oneOf":[{"$ref":"http://example.com/image"},{"$ref":"http://example.com/video"}]
    }
  }
}

//the post schema refernces multiple schemas

GUI Hints

the following meta-data fields have been added for better GUI generation:

• views: a map between view-names to visual components for the schema, each view can specifiy:
  • controller: unique id of custom controller to show for this data.
  • props: object containing extra props for said component

{
  "$id": "http://example.com/customForm",
  "title":"Custom person Form",
  "properties":{
    "name":{
      "type":"string",
      "enum":['a','b']
    },
    "avatar":{
      "type":"object",
      "$ref":"http:/example.com/MpImage"
    },
    "age":{
      "type":"number",
    },
    "income":{
      "type":"number",
      "controller":{
        edit:"slider"
      }
    },
    "height":{
      "type":"number",
      "controller":{
        edit:"vertical-slider"
      }
    }
  }
}

this should be accompanied with registering the component to the schemaRepo

myRepo.registerController('number', 'edit', NumberInput, controllerProps);
myRepo.registerController('number', 'edit',Slider, controllerProps, (schema)=>schema.controller.edit==='slider');
myRepo.registerController('number', 'edit',VerticalSlider, controllerProps, (schema)=>schema.controller.edit==='vertical-slider');

//with sugar
myRepo.registerController('number', 'edit',VerticalSlider,controllerProps,'vertical-slider');


//register to enum string
myRepo.registerController('string', 'edit',DropDown,controllerProps ,(schema)=>!!schema.enum);
//register to array of strings
myRepo.registerController('array', 'edit',TagsInput,controllerProps ,(schema)=>schema.items.type==='string');

//register to string map
myRepo.registerController('object', 'edit',MapEditor,controllerProps ,(schema)=>!!schema.additionalProperties);

//register to Mpimage
myRepo.registerController('http:/example.com/MpImage', 'edit',ImageSelector,controllerProps);

• uiGroup string, properties with the same uiGroup will be grouped together, some view generators support presentations for specific uiGroup ( and default to uiGroup content when not specified)

{
  "$id":"http://example.com/user",
  "title":"User",
  "type":"object",
  "properties":{
    "fName":{
      "type":"string",
      "uiGroup":"name"
    },
    "lName":{
      "type":"string",
      "uiGroup":"name"
    },
    "age":{
      "type":"number"
    }
  }
}

• icon string, unique id of an icon from the repo

{
  "$id":"http://example.com/user",
  "title":"User",
  "type":"object",
  "properties":{
    "fName":{
        "type":"string"
      }
    },
    "location":{
      "type":"string",
      "icon":"locationPin"
    }
  }
}

TBD: Extra views for type

because the schemas are used to create GUI, it is sometimes usefull to define extra schemas for the same dataType (views), this should be used only for differnt views and not apply any different validation.

in these cases it is usefull to have the view schemas explicitly reference the base schema that defines the validation using the $viewOf keyword

example

base schema:

{
  "$id":"http://example.com/user",
  "title":"User",
  "type":"object",
  "properties":{
    "fName":{
      "type":"string"
    },
    "lName":{
      "type":"string"
    },
    "age":{
      "type":"number"
    }
  }
}

extra view:

{
  "$id":"http://example.com/user/partialView",
  "$viewOf":"http://example.com/user",
  "title":"User",
  "type":"object",
  "properties":{
    "fName":{},
    "lName":{}
  }
}

auto-generation from typescript

auto generating schemas is possible through third party projects - add link here

using this method the following typescipt code sitting in src/components/bobs.ts:

/**
 * @id bob
 */
interface bob{
    age:number;
}
//unique id set by user

interface bobsUncle{
    cousin:bob;
}

//unique id is auto generated from project structure

will result in the 2 following generated schemas

{
    "$id":"http://npmJs/{project-name}/bob",
    "properties":{
        "age":{
          "type":"number"
        }
    }
}

{
     "$id":"http://npmJs/{project-name}/dist/src/components/bobs.ts/bobsUncle",
    "properties":{
        "cousin":{
          "$ref":"http://npmJs/{project-name}/bob"
        }
    }
}

Library structure

auto-views
|
|--src - source code.
|
|--test - test code. browser tests end with: spec.ts/x
|                    node tests end with: .node-spec.ts/x
|
|--demo - demo of all components.
|
|--lib - target code generated by build script.

Development

The following scripts are available:

npm start - Runs webpack-dev-server (watching, hot-reloading), with access to demos and browser tests available via http://localhost:8080/webpack-dev-server

npm run build - Transpiles src into lib. Run automatically on prepublish.

npm test - Runs test:browser and test:node scripts. See below.

npm run test:browser - Runs karma for an automated single run of browser tests. For watch mode, see start script above.

npm run test:node - Runs mocha for an automated single run of node tests. For watch mode, you can pass in the watch flag: npm run test:node -- -w