Jeditor NPM | npm.io

Jeditor

Warning: Jeditor is experimental! It will undergo major changes in subsequent updates and is seriously, seriously untested. Check out the "Alernatives" section below if you need something more stable.

Jeditor is a simple admin interface that allows a user to build an object that conforms to a specified schema, all without a database. It's an HTML/JS/CSS Browserify-bundled component that can be inserted into any HTML page via client-side Javascript. You pass to a Javascript function a jQery selection and a configuration object that includes a schema, and it prints an admin interface to the selected element that will allow your user to create an object based on that schema.

Jeditor comes with a variety of controllers for different data types, including text, arrays, and files, and you can easily build your own.

Jeditor was built primarily to allow non-technical users to create complex, multi-level data objects without requiring a database or framework.

Some highlights:

Associations: Model definitions can include other models. For example, a "quiz" model can include an array that contains instances of another model, a "question."
Model properties and arrays can accept multiple types. For example, the "quiz" model's question array could accept "multiple choice question" instances or "hangman" instances.
Includes a simple drag-and-drop file upload controller. The controller is agnostic about what you do on the server-side; you simply tell the controller where to POST the file and how to determine the instance value from the response object of that request.

Class: Jeditor

Constructor

$container: A jQuery selection of the container that Jeditor will print to.
schema: An object representing the schema configuration. See "schema" below.

Methods

.export() returns a Javascript object representing the object instance.
.import(data) fills the currently edited object with data. This completely overwrites all existing data.

Usage

index.html:

<div id="your_container"></div>
<div class=".btn_export"></div>

main.bundle.js:

var Jeditor = require('jeditor');
var jeditor = new Jeditor($('#your_container'), YOUR_SCHEMA);

// Example export button
$('.btn_export').click(function(){
  window.prompt('Your object', JSON.stringify(jeditor.export()));
});

Schema

The schema is a simple Javascript object. The first level of the schema includes your models, which are keyed with an initial $ sign. One must be called $main, and it represents the primary or root model.

Each model definition comprises properties with keys that start with the @ symbol

A property object includes these parameters, which describe the property's type and the UI component with which the user defines its value, i.e. the controller.

type: Required. String or array. The type can either be the name of another model (using the $ symbol) or the name of a controller (see below). If array, the user can choose the type of object to set to this field.
desc: Optional. String. This string appears as small text inside the field's node in the DOM. Useful for annotating each field.
required: Optional. Boolean. Defaults to false. Determines whether the field is required. The project will not validate unless all required fields have values. (TK)
hide: Optional. Boolean. Defaults to false. If set to true, the field is hidden initially and can be added by clicking a link near the top of the object.

Each property contains additional parameters that affect its controller. See below.

Immutable properties

If you would like to predefine object properties that the user cannot change but will still appear in the export, you want to use immutable properties. Immutable properties can be set by leaving the @ symbol out. You may not include two keys that only differ with the @ symbol, e.g. @content and content cannot exist in the same model. That's because the @ symbol is dropped on export. Immutable properties do not appear in the UI.

Example Schema

{
  $quiz:{
    "@title": {
      type: 'string'
    }
    "@questions": {
      type: 'array',
      contains: ['$question']
    }
  },
  $question:{
    "@text": {
      type: 'richtext'
    },
    "@choices": {
      type: 'array',
      contains: '$choice'
    }
  },
  $choice: {
    "@text": {
      type: 'richtext'
    }
    "@validity": {
      type: 'boolean'
    }
  }

}

Example Export

{
  title: "My Quiz",
  questions: [
    {
      text: "What' the meaning of life?",
      choices: [
        {
          text: "42",
          validity: false
        },
        {
          text: "43",
          validity: true
        }
      ]
    }
  ]
}

Controllers

Controllers are the components by which the reader specifies the value of a field.

string

Straightforward enough! TK: char limit.

file

Uploads a file and shows a preview of it.

accepts: Array. Optional. An array of extensions that the controller allows. E.g. ['png','gif','jpg','jpeg'];
postTo: String. Required. The URL to which the controller will send a POST request that includes the data object as the body.
post_data: Object. Optional. Data to be sent along with the file in the POST request. Your server may use this data to, for example, resize an image.
setValue: Function. Required. A function returning the value that you would like this object to be set to after the file upload. The first argument is the response of the POST request.
getPreviewUrl: Function. Optional. A function returning the URL that you would like the controller to use to show the preview of the file (for images). The first argument is the value of the object. If this is not set, the controller will assume the value itself is the preview URL.

richtext

Similar to string, but allows the user to bold, italicize, underline, and link text. To use the RichText controller, you must embed medium-editor on your page.

integer

Similar to a string, but the data is stored as an integer.

array

In the code, array is referred to as intArray.

contains: String or array. If a string, the object (e.g. $description) or controller type (e.g. string) that this array contains. If an array, an array of strings identifying the types of objects that the array can contain, allowing the user to select which to add.

Creating your own controller

Constructor arguments:

$target is the jQuery selection of the DOM element representing the controller's field.
conf is the property definition of the controller. It includes all controller-specific properties.
template is the entire schema.

Required methods:

.setValue(val) must set the the value when Jeditor's import function is run. The controller must reflect this new value.
.getValue() must return the value that will be stored in the object when Jeditor's export function is run.