Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/simeonackermann/RDForm

Create and edit RDF data in a HTML form
https://github.com/simeonackermann/RDForm

forms rdf semantic-web

Last synced: 5 days ago
JSON representation

Create and edit RDF data in a HTML form

Awesome Lists containing this project

README 

        
# RDForm



RDForm is a jQuery plugin for creating and editing RDF data in a clean and modern HTML form.



With templates based on the [RDFa](https://en.wikipedia.org/wiki/RDFa) notation (see template documentation) its easy to create classes, properties with datatypes, resources and class-relations.



The inserting of existing data and the output is done as a JavaScript object with the [JSON-LD](https://github.com/digitalbazaar/jsonld.js) notation.



For a **running example** see https://simeonackermann.github.io/RDForm/.



> This software is currently in a very early state. Please be careful when use it in a productive environment.



## Screenshot ##



![](screenshot.png)



## Installation ##



### Via npm



`npm i @donsi/rdform`



### Manually



* download the source code

* open [index.html](index.html) in your browser for a sample form.

* to create an own form, edit [templates/form.html](templates/form.html) to your requirements or create a new file



The load of templates and hooks requires a running http server. You can use docker for example:



	docker run --name rdform -v $(pwd):/usr/share/nginx/html -p 8080:80 nginx



and access at http://localhost:8080



### Integrate



If you want to integrate RDForm into an existing project you have to include [jQuery](http://jquery.com/) (> 1.8) (and for a good style [Bootstrap](getbootstrap.com/)). Have a look at [index.html](index.html) for the right structure.



The basic initialization of the plugin with callback function on submit is:



```js

$(document).ready(function(){

	$(".rdform").RDForm({

		template: "templates/form.html",

		submit: function() {

			console.log( JSON.stringify(this, null, '\t') );

		}

	});

});

```



# Documentation #



### Content ###



- Parameter

- Template Documentation

	- Classes

	- Literal-Properties

	- Class-Resources

	- External resources

	- Hidden-Properties

	- Wildcards

	- Translation

- Insert Data

- Hooking



## Paramter ##



The following parameters can given to the plugin (see Installation above):



Parameter (Type) | Default | Description

--- | --- | ---

`template` (String) | templates/form.html | Path to the template file

`data` (Object) | null | Array or Object of existing data to insert

`hooks` (String) | null | Path to the hooks file

`prefixes` (Object)	| {  foaf: ..., rdf: ..., rdfs: ..., ...} (see rdform.js) | Object with prefiex and URIs

`base` (String)	| null | Base URI

`lang` (String) | null | Path to the language file

`cache` (Boolean) | false | true or false, loads template from cache

`verbose` (Boolean)  | false | true or false, output all messages and the result

`debug` (Boolean) false | log error, warnings and infos into the console

`submit` (Function)	| null | Submit callback function, will be called after submit the form

`abort` (Function)	| null | Abort callback function, will be called on aborting the form



## Template Documentation ##



To visualize a class, its properties and the resources in a form the plugin needs a template. The templates are based on the [RDFa](https://en.wikipedia.org/wiki/RDFa) notation which adds RDF attributes to HTML elements. With that kind of templates its possible to describe RDF-ontologies on the HTML-way and to define the layout like labels, legends, placeholder and so on.



Some default templates can by found in the subfolder [templates](templates/). The path of the current template must be given as `model` argument to the plugin (see installation).



The base structure of an example template is:



```html



	A person

	


		The label

		

	



```



The JavaScript output for this template will be:



```js

{

	"@id": "http://example.com/Person-Max_Mustermann",

	"@type": [

		"http://xmlns.com/foaf/0.1/Person"

	],

	"http://www.w3.org/2000/01/rdf-schema#label": [

		{

			"@type": "xsd:string",

			"@value": "Max Mustermann"

		}

	]

}

```



### The Form ###



The root element should be a `...` tag and contains all further classes and properties.



Attribute | Description

------------- | -------------

`prefix`		| Optional, Prefixes fo all resources. The form is "PREFIX URI PREFIX URI ..."

`base`	| Optional, Base URI



### Classes ###



Classes are described by a `
...
` tag.



Attribute | Description

------------- | -------------

`typeof`		| Type of the class

`resource`	| Class uri

`id`		| Optional class ID to reference classes with same typeof

`typeof-select` | Optional, show select form lets users choose the type of the class. The value must be a [JSON](https://en.wikipedia.org/wiki/JSON) object with label and value pairs.



Example (with legend and help message):



```html

Birth



	
I'm a help message...



	...



```



### Literal Properties ###



Literals are described by a ``.



Attribute | Description

------------- | -------------

`type="literal"`	| Defines an input as an literal property

`name`			| Name of the property



Optional Attribute | Description

------------- | -------------

`datatype`	| Datatype, e.g. xsd:string, xsd:date,

`value`		| Prefilled value

`placeholder`	| Placeholder

`multiple`	| The property can be multipled by clicking an add-button

`required`	| Required property, cannot be empty

`additional`	| Additional, by default hidden property. Can be added it by clicking an add-button

`readonly`	| Cannot be edited

`hidden`		| Hide this literal in the form

`boolean`		| Boolean property, shown as `

`textarea`		| Multiple line text, shown as ``

`select`		| Select a property from multiple options, shown as ``

`select-options`		| Required for attribute select. JSON object with label/value pairs. >`

`help`		| Short help text for the property



Example:



```html



```



Special literals are booleans, textareas and select-lists.



#### Booleans



Are described as checkboxes in the form and can be 1|0 or true|false. They are initialized by adding the attribute `boolean` to a literal property.



#### Textareas



Are multiple line texts and initialized by adding the attribute `textarea` to a literal property.



### Dates



Properties of type `xsd:date` will rendered with a date-type select option. To define the date format you can use `xsd:gYearMonth` or `xsd:gYear` as datatype.



#### Select-Lists



To get a select list add the attributes `select` and `select-options='...'`. the value of `select-options` must be a [JSON](https://en.wikipedia.org/wiki/JSON) object with a label and value pair.



Example:



```html



```



### Class Resources ###



Classes can contain resource properties, which containing a reference to another class.



Example:



```html



	



	






	



```



If you need to reference classes with same typeof add the id attribute. Example:



```html



	

	






	






	



```



### External Resources ###



Example:



```html



```



#### Select-Lists



To get a select list add the attributes `select` and `select-options='...'`. the value of `select-options` must be a [JSON](https://en.wikipedia.org/wiki/JSON) object with a label and value pair.



Example:



```html



```



Multiple external select resources are not yet supported.



## Hidden Properties ##



Example:



```html



```



### Wildcards ###



With wildcards the class identifier or a property value can point to another property value of the same class. Just write the name of the property into brackets.



Example:



```html



	

	



```



#### Wildcard Functions



To the returned value of a wildcard a function can applied. Basically you can use the string functions `toUpperCase` and `toLowerCase`, while writing the function name into braces just before the wildcard-identifier:



```html



```



Custom functions can written into the return statement of the `__wildcardFcts` method in your hooks file (see `hooks.js` for examples). E.g:



```js

__wildcardFcts : function() {

	return {

		foo: function(str) {

			return str + "bar";

		},

	};

}

```



And called just before the wilcard-identifier as above.



### Translation ###



Strings in legends, labels and placeholder can translated with `l(My Label)`. The translation files are stored in [lang/](lang/) (currently only english and german) and must be given as `lang` argument to the plugin.



Example:



```js

$(".rdform").RDForm({

	template: "templates/form.html",

	lang: "de"

});

```



## Insert Data ##



Existing data can inserted as [json-ld](http://json-ld.org/) javascript object. The form of the data should fit to the loaded template. RDForm will insert the data into the form fields.



Example:



```js

var data = {

	"@id": "http://json-ld.org/playground/Person-Karl",

	"@type": [

		"http://xmlns.com/foaf/0.1/Person"

	],

	"http://xmlns.com/foaf/0.1/name": [

		{

			"@type": "xsd:string",

			"@value": "Karl"

		}

	]

};



$(".rdform").RDForm({

	template: "templates/form.html",

	data: data

});

```



## Hooking ##



With hooks own JavaScript methods can affect the application execution on certain points. Have a look at [js/hooks/hooks.js](js/hooks/hooks.js) for more information.



## License ##



RDForm is licensed under the [GNU General Public License Version 2, June 1991](http://www.gnu.org/licenses/gpl-2.0.txt).