auto-views

Common, fully-tested, strictly-typed, Wix-styled, auto views library

Stats

stars 🌟issues ⚠️updated 🛠created 🐣size 🏋️‍♀️
auto-views
Minified + gzip package size for auto-views in KB

Readme

Auto-Views component family

Build Status Sauce Test Status

Sauce Test Status

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

image

the following editing view:


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

image

the following table view:


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

image

and the following list view:


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

image

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

image

  • 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"
    }
  }
}

image

  • 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"
    }
  }
}

image

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

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.