README
JSONEditor4Code
JSONEditor4Code
is a JSON Editor for UML Diagrams developed with Javascript Code Templates based on JSON Editor of Jeremy Dorn
The following table of contents is generated with node doctoc README.md
.
Table of Contents
- Start WebApp
JSONEditor4Code
- Installation
JSONEditor4Code
- Folder and Files in
docs/
- Files, Folders and Structure of Repository
- Quick Start for Users of JSONEditor4Code
- Templates for Handlebars4Code
- vDataJSON as Template Storage
- Templates and JSON into vDataJSON
- Script Tag for handlebars4code.js
- Additional Handlebars Helpers for Code generation
- Build Process of
npm run build
- Build and Compress with Browserify, Watchify, UglifyJS
- Acknowledgement
- Libraries required for
JSONEditor4Code
- Libraries for Building and Developement
- NPM Library Information
JSONEditor4Code
Start WebApp
JSONEditor4Code
Installation The library was designed to used in a browser (WebApp). So use the installation for your browser by using a bundle dist/jsoneditor4code.js
- see example Demo JSONEditor4Code
.
Installation for Browsers
If you want to use the library jsoneditor4code.js
in a browser, please copy the file dist/jsoneditor4code.js
into your library folder of WebApp that you want to test with a browser (e.g. js/jsoneditor4code.js
). If you want expand existing examples check the basic example in docs/index.html
first and play around with that HTML-file. If you want to import the library with script
-tag do it in the standard way with:
<script src="js/jsoneditor4code.js"></script>
Now it is possible to use the constructor of JSONEditor4Code
if (JSONEditor4Code) {
var vJSONEditor = new JSONEditor4Code();
vJSONEditor.initDoc(document);
}
Now we define a hash that contains the options for the init()
-call.
var pOptions = {
"editor_var": "vJSONEditor", // Variable in index.html that stores the JSONeditor
"editor_id": "editor_holder", // ID of DOM element, that stores the editor.
"validator_id":"valid_indicator", // ID of DOM, that contains the validator result "valid" or "not valid"
"filejson_id" : "fileJSON", // ID of DOM element that contains the JSON file upload
"filename_id" : "display_filename", // innerHTML for DOM element to display the loaded filename
"filename_key" : "data.classname", // key that stores the basename for the filename
"out_json": "tOutJSON", // ID of textarea to visualise the generated JSON
"out_code": "tOutput", // ID of textarea to visualise the generated code/markdown with the templates in docs/tpl
"out_errors": "tErrors" // ID of textarea that shows the errors in the loaded JSON
};
After the initDoc()
call the JSONEditor4Code
is aware about the document
in the browser.
Init the JSON Editor
The init method of the JSON Editor gets as parameter the follow JavaScript objects:
pJSON
is JSON data with which the JSON Editor is populated,pDefaultJSON
is the JSON data which is used, when the JSON Editor is resetted,pSchema
is JSON Schema which defines the input elements of JSON EditorJSONEditor4Code
vDataJSON.tpl
is a hash of string templates forHandlebars4Code
.vDataJSON.tpl
is hash with defined template strings. With the template ID theHandlebars4Code
template engine uses this template for code generation.pOption
are options for the JSON Editor.
vJSONEditor.init(vJSON,
vDefaultJSON,
vDataJSON["class_schema"],
vDataJSON.tpl,
vOptions);
vDataJSON
is a JSON container for all the loaded data. Templates are loaded with script
-tags (see docs/index.html
):
<script src="tpl/javascript_tpl.js"></script>
<!-- ### COMPILE HANDLEBARS TEMPLATES ############
Template ID: "docu4github"
Template: vDataJSON["tpl"]["docu4github"]
-->
<script src="tpl/docu4github_tpl.js"></script>
<!-- ### SCHEMA LOADER ############################
script tag stores the JSON schema in
vDataJSON.tpl.["class_schema"]
<script src="schema/class_uml_schema.js"></script>
-->
<script src="schema/class_uml_schema.js"></script>
docs/
Folder and Files in The folder docs/
contains all files for the web demo of this repository, that can be accessed to the https://___PKG_GITHUBUSER___.github.io/JSONEditor4Code
.
Files, Folders and Structure of Repository
The following enumeration explains the structure of the repository and folders.
dist/
folder contains the generated libraries by the commandnpm run build
.docs/
folder contains all the web content that you can access viagithub.io
defined in the settings of the GitHub repository as server root for the demo.docs/ace
folder contains files for the editor ACE, that is used in JSON-Editor to edit source code.docs/db
folder contains JSON database which initializes the JSON-Editor with the default JSON data. If the user saves the file, the current JSON data is stored in the LocalStorage of the browser.docs/css
folder contains all style sheet for the webbased demo indocs
.docs/fonts
folder contains the fonts for the FontAwesome.docs/jquery
folder contains the JQuery implementation so that a webbased demo runs offline.docs/js
folder contains all Javascript libraries used for the webbased demo.docs/schema
folder contains JSON schema for the webbased demo created JSON2schema, defining the input user interface for editing the JSON filedocs/tpl
folder contains the HandleBars template generating the source code from the UML definition.docs/index.html
files starts the webbased demo.
jscc/
folder contains the JavascriptClassCreator files that are used to create object-oriented Javascript class files.src/
folder contains the filemain.js
for NPM defined inpackage.json
and other source files in the future, to create a the library for webbased use in a browser can be found in the folderdist/
. The files indist/
are created withbrowsersify
and/orwatchify
.update_src_libs.sh
is a shell script that works on Linux and MacOSX to perform some library updates from the web and theupdate_src_libs.sh
can be used to initialize a new repository with the basic WebApp structure as an privacy friendly AppLSAC.
Quick Start for Users of JSONEditor4Code
Just download the ZIP-file of the JSONEditor4Code repository. For using the AppLSAC unzip the file
and navigate to the docs/
-folder and load the
docs/index.html
in your browser as privacy-friendly AppLSAC-2.
All files, that are equired for the AppLSAC to run are stored in the docs folder. Only if you are planing the change the source code of the AppLSAC JSONEditor4Code
you need the other folders.
If you just want to use JSONEditor4Code
in your browser it is recommended to
- copy just the
docs/
-folder, - rename the folder to
jsoneditor4code/
and - start
index.html
with your browser as AppLSAC-2.
Templates for Handlebars4Code
In the Handlebars4Code
demo the JSON data is stored in vDataJSON
, which is the main JSON data storage defined in index.html
. Data (docs/db/
) and templates (docs/tpl/
) are loaded into the JSON. All templates reside in vDataJSON.tpl
, which is provided as parameter to Handlebars4Code.create_compiler(vDataJSON.tpl)
. The method create_compiler(vDataJSON.tpl)
creates Handlebars compilers for all templates in vDataJSON.tpl
.
create_compiler(vTplHash)
expects a hash, for which the template ID is the key for accessing template (e.g.vDataJSON.tpl["docu4github"])
orvDataJSON.tpl["javascript"])
(see directorydocs/tpl/
).- The compilers need to be generated only once. Then the compiler for all templates are ready to process JSON data and generate output according to the template definition.
var my_compilers = Handlebars4Code.get_compiler()
stores the generated Handlebars compilers in an individual compiler hash.var my_output = my_compilers.javascript(vJSON)
provides JSON to the compiler function for the templatejavascript
.var my_output = my_compilers.docu4github(vJSON)
provides JSON to the compiler function for the templatedocu4github
.
vDataJSON as Template Storage
Create a template storage in your main HTML file.
<script language="javascript">
var vDataJSON = {};
vDataJSON.tpl = {};
vDataJSON.out = {};
</script>
vDataJSON.out
contain the compilers, that are generated by Handelbars4Code
. Each compiler in vDataJSON.out
have are corresponding template in vDataJSON.tpl
. vDataJSON.tpl
is hash of strings for each ID and vDataJSON.out
is hash of functions with the corresponding ID. The following code generates the compiler with HandleBars4Code
.
Handlebars4Code.create_compiler(vDataJSON.tpl);
vDataJSON.out = Handlebars4Code.get_compiler();
Assume you have a template with the ID mytpl
you will get a compiler function in vDataJSON.out.mytpl()
that you can populate with JSON data. The call of vDataJSON.out.mytpl(pMyData)
will replace the JSON data pMyData
in the template mytpl
.
Templates and JSON into vDataJSON
The javascript files in docs/tpl/
and docs/db/
are designed in way that allows the population of vDataJSON
just by including a script tag in the underlying HTML file (see example docs/index.html
).
Load JSON Data with Script Tag
The following script tag loads the JSON data into vDataJSON
.
<script src="db/umljs.js"></script>
The data is stored in the following way in the JavaScript file:
vDataJSON["umljs"]= {
"author": "Bert Niehaus",
"description": "My description for repository."
}
It is recommended to use the same ID in vDataJSON
as the basename of the corresponding JavaScript file db/umljs.js
without path db/
and extension .js
.
Load Templates with Script Tag
Every script tag loads a single template from the subdirectory docs/js/
:
<script src="tpl/javascript_tpl.js"></script>
<script src="tpl/docu4github_tpl.js"></script>
Script Tag for handlebars4code.js
Use the script tag to embed the Handlebars4Code library in your HTML file::
<script src="js/handlebars4code.js"></script>
Additional Handlebars Helpers for Code generation
The following Handlebars helpers are added to the basic Handlebars features, to support better code generation. Generated code can be in any programming language (of course including markup or markdown languages):
List of Helpers in Handlebars4Code
filename
create lower case filenames from camel-case class names (e.g.MyClass
intomyclass
).ifcond
creates id-conditions in the Handlebars template to create JSON context dependent compiler output.require_class_list
insertsrequire
commands according the used classes in the attributes and return values of the methods. It requires only modules that are not base classes that are provided by the programming language itself.requirelibs
The helper is designed to generate local and remote require commands in a class/module.foreach
is slighty different from the standardeach
helper in Handlebars. It allows to assign parentdata
hash toforeach
context of the template
filename
Helper: The helper function filename
generates from any input string a usable filename in lowercase that contains no blanks an no special characters.
filename
Template 1: Assume we have the following templates stored vDataJSON.tpl["mytpl1"]
with
// The filename of the class {{data.classname}} is {{filename data.classname}}.js
The template ID mytpl1
is
filename
JSON Data 1: The following JSON
var my_json = {
"data":{
"classname" : "MyClass"
}
}
filename
Compiler Output 1: The compiler call Handlebars4Code.compile.mytpl1(my_json)
for the JSON data my_json
and the template generates the following code
// The filename of the class MyClass is myclass.js
filename
JSON Data 2: The following JSON
var my_json = {
"data":{
"classname" : "MyClass",
"superclassname" : "MySuperClass"
}
}
filename
Template 2: Assume we have templates vDataJSON.tpl["mytpl2"]
with:
const {{data.superclassname}} = require('{{filename data.superclassname}}');
filename
Compiler Output 2: The compiler call Handlebars4Code.compile.mytpl2(my_json)
for the JSON data my_json
and the template generates the following code:
const MySuperClass = require('mysuperclass');
If the input string contains blanks then these blanks are replaced by an underscore.
ifcond
Helper: If
condition and application of JSON path to specific attribute to JSON. The following template generates a header as comment for the javascript output. Dependent on the value of data.superclassname
(string not empty) an additional name for the superclass is inserted in the header of generated output of code (see Blog in StackOverflow)
ifcond
Template: Assume we have the following templates is stored vDataJSON.tpl["mytpl"]
with
//#################################################################
//# Javascript Class: {{data.classname}}()
{{#ifcond data.superclassname "!=" ""}}
//# SuperClass: {{data.superclassname}}
{{/ifcond}}
//#
//# Author of Class: {{data.reposinfo.author}}
//# email: {{data.reposinfo.email}}
//#################################################################
The ifcond
is an if-condition, that inserts a line with name of the super class if the superclassname
is not empty.
ifcond
JSON Data: The following JSON is used the helper call:
var my_json = {
"data": {
"classname": "NewClass",
"superclassname": "MySuperClass",
"comment": "Description of the class",
"reposinfo": {
"repository": "https://www.github.com/author/NewClass",
"author": "My Name",
"email": "name@example.com",
},
}
};
The superclassname
is not empty and has the value "MySuperClass"
. The ifcond
used in the template will insert a line by the use of an if-condition.
ifcond
Compiler Output: The compiler call for the JSON data and the template generates the following code:
//#################################################################
//# Javascript Class: NewClass()
//# SuperClass: MySuperClass
//#
//# Author of Class: My Name
//# email: name@example.com
//#################################################################
The compiled result contains a comment about the super class, due to the fact that the attribute superclassname
is not empty and contains the value "MySuperClass"
.
require_class_list
Helper: The helper function creates a list of liberaries that must be required/imported (e.g. Javascript) so that the defined libary for the new class can used the required resources in other modules. Some classes/instances are already defined by the programming language (e.g. Math
, JSON
in Javascript). Those libraries do not need a require command. The code generator should know about
- base classes (
baseclasslist
) - no need to create require - local classes (
localclasslist
) - store in local directory, a path is necessary to these locally defined libraries (seedata.reposinfo.require_path
). - remote classes (
remoteclasslist
) - retrieved from a remote server via a package manager.
require_class_list
Template: Assume we have the following templates stored vDataJSON.tpl["mytpl"]
with
{{{require_class_list data settings}}}
The helper needs the data
and the settings
attribute of the JSON input as parameter:
data
contains all the defined elements of the class.settings
contain basic definitions for the classes that are available in the software development project.data.superclassname
because a superclass will be handled with a separaterequire
command.settings.baseclasses
because those classes are provided by the programming language by default and they do not need a require command.settings.localclasses
because those classes are created within the software developement of the repository and these modules need a special require command with a local pathname, where to to find the libraries, e.g.require('./libs/mylocallib')
.data.reposinfor.require_path
contain the local path to the libraries/modules oflocalclasses
./libs/
.settings.remoteclasses
remote classes are download with a package manager and these modules are required just by the module name, e.g.require('mylocallib')
.
require_class_list
JSON Data: The following JSON
var my_json = {
"data": {
"classname": "NewClass",
"superclassname": "MySuperClass"
},
"settings": {
"extension4code":".js",
"localclasslist": [
"App",
"AppAbstract"
],
"remoteclasslist": [
"LinkParam",
"JSONEditor"
],
"baseclasslist": [
"",
"Array",
"Boolean",
"Float",
"Function",
"Hash",
"Integer",
"Object",
"RegularExp",
"String"
]
}
};
require_class_list
Compiler Output: Assume that App
, LinkParam
and JSONEditor
are used in the class as attributes or returned instances of method. App
is a locally defined class while LinkParam
and JSONEditor
are remote classes downloaded from the package manager (e.g. NPM).
The compiler call for the JSON data and the template generates the following code.
require('./libs/app');
require('linkparam');
require('jsoneditor');
requirelibs
Helper: The helper is designed to generate local and remote require commands in a class/module.
requirelibs
Template: Assume we have the following templates is stored vDataJSON.tpl["requiretpl"]
with:
// NodeJS: Require additional Modules
{{#requirelibs data.reposinfo.requirelist}}
const {{variable}} = require('{{module}}');
{{/requirelibs}}
requirelibs
JSON Data: The following JSON is used the helper call:
var my_json = {
"data": {
"classname": "NewClass",
"reposinfo": {
"requirelist": [
{
"module":"handlebars",
"variable":"Handlebars"
},
{
"module":"filesaver",
"variable":"FileSaver"
},
{
"module":"jquery",
"variable":"