Getting started

Installing

You can install the RDForms framework from npm via:

npm install @entryscape/rdforms

Alternatively you can check out the code via git and run yarn to get the dependencies:

$ git clone https://bitbucket.org/metasolutions/rdforms.git
$ yarn

Or download a zip from the RDForms Bitbucket download page and RDFJSON Bitbucket download page.

Material UI renderers below

With RDForms you can choose different UI frameworks by selecting a set of renderers. However, in the code below we only show the dependency to React Material UI renderers as the code will be largely the same with other renderers.

Importing from libraries

Below we indicate how to load the RDForms framework into different settings. Note that RDForms has a dependency to the RDFJSON library that provides a way to work with RDF graphs in javascript. RDFJSON is not built into the RDForms bundle, hence you need to load it explicitly from node_modules/@entryscape/rdfjson/dist/ or some other location .

Browser environment

<script src="/path/to/libs/rdforms.react.js"></script>
<script src="/path/to/libs/rdfjson.js"></script>
<script>
  const { Editor, ItemStore } = window.rdforms;
  const { Graph } = window.rdfjson;
  // init a template, rdf graph and editor
</script>

ES Module environment

import { ItemStore } from '@entryscape/rdforms';
import { Editor } from '@entryscape/rdforms/renderers/react';
import { Graph } from '@entryscape/rdjson';
// init a template, rdf graph and editor

CommonJS environment

const { Editor, ItemStore } = require('@entryscape/rdforms/renderers/react');
const { Graph } = require('@entryscape/rdfjson');
// init a template, rdf graph and editor

Note

The above code works in a bundler scenario (e.g. utilizing webpack) where you aim to build a webb application. But it will fail in Node.js unless you provide a fake DOM environment, e.g. for testing purposes. However, RDForms can be used in Node.js without a fake DOM, typically for validation purposes. In this scenario you need to load RDForms without a renderer which is best done from the RDForms base:

const { ItemStore, Engine, validate } = require('@entryscape/rdforms');
const { Graph } = require('@entryscape/rdfjson');
// init a template, rdf graph and validate

Providing a template

To be able to use RDForms you will always need a template that describes which part of an RDF graph you want to edit/present/validate. In most situations the templates will be loaded from a JSON file, below they are given inline for simplicity. The templates are registered into the itemstore and includes two field-level templates that are grouped together into a larger form-level template named myTemplate.

const foafTemplateSource = {
  "templates": [
    {
      "id": "foaf::name",
      "type": "text",
      "property": "foaf:name",
      "nodetype": "ONLY_LITERAL",
      "label": {"en": "Name"},
      "cardinality": {"min": 1}
    },
    {
      "id": "foaf::gender",
      "type": "choice",
      "property": "foaf:gender",
      "nodetype": "ONLY_LITERAL",
      "label": {"en": "Gender"},
      "choices": [
         {"value": "male", "label": {"en": "Male"}},
         {"value": "female", "label": {"en": "Female"}},
         {"value": "other", "label": {"en": "Other"}},
      ],
      "cardinality": {"max": 1},
      "styles": ["horizontalradiobuttons"]
    },
    {
      "id" : "myTemplate",
      "type": "group",
      "items": [
        "foaf::name",
        "foaf::gender"
      ]
    }
  ]
};
const itemstore = new ItemStore();
itemstore.registerBundle({source: foafTemplateSource});
const template = itemstore.getTemplate('myTemplate');

Providing an RDF graph

RDForms always works with RDF graphs. The common scenario is to load the graph from an API or disk, but for simplicity we provide a graph inline in the RDF/JSON format which is what is understood by default in the rdfjson library.

const graph = new Graph({
  "http://example.com": {
     "http://xmlns.com/foaf/0.1/name": [{ "value": "John Doe", "type": "literal" }]
  }
});

Creating an editor

To create an editor we also need to specify which URI to start editing from as well provide a dom-node to attach the editor to.

const resource = 'http://example.com';
const editor = new Editor({ resource, graph, template,
     compact: false, includeLevel: 'optional' }, 'id_to_dom_node');

The resulting UI can be seen below:

See the Nobel example for a more complete view of how an editor can look like in different renderers.