Skip to content

Commit 9b31c09

Browse files
GregwarGregwar
committed
README & LICENSE
1 parent 3e2bce5 commit 9b31c09

File tree

3 files changed

+186
-1
lines changed

3 files changed

+186
-1
lines changed

‎LICENSE

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Copyright (c) <2013> Grégoire Passault
1+
Copyright (c) <2013-2014> Grégoire Passault
22

33
Permission is hereby granted, free of charge, to any person obtaining a copy
44
of this software and associated documentation files (the "Software"), to deal

‎README.md

+135
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,16 @@ Note that this is just a flexible front-end editor, there is no back-end here.
99

1010
You can [try a live demo](http://gregwar.com/blocks.js/).
1111

12+
## Overview
13+
14+
blocks.js is feeded using [blocks specifications](#blocks), using meta informations
15+
explaining its fields, name and behaviour.
16+
17+
It allow the user to edit the blocks scene.
18+
19+
Then, thanks for instance to the `exportData()`, method, you can get back
20+
the edited [scene](#scene). When you load the blocks, you can also load back a scene.
21+
1222
## Using blocks.js
1323

1424
### Downloading
@@ -51,3 +61,128 @@ Then, you'll have to load `blocks.js` and `blocks.css`:
5161
<link rel="stylesheet" type="text/css" href="build/blocks.css" />
5262
```
5363

64+
### Running it
65+
66+
Here is a simple example:
67+
68+
```js
69+
// Instanciate Blocks
70+
var blocks = new Blocks();
71+
72+
// Registering a simple block, with an input
73+
// and an output
74+
blocks.register({
75+
name: "Test",
76+
fields: [
77+
{
78+
name: "Input",
79+
attrs: "input"
80+
},
81+
{
82+
name: "Output",
83+
attrs: "output"
84+
}
85+
]
86+
});
87+
88+
// Running blocks on the div with the name "blocks"
89+
blocks.run("#blocks");
90+
```
91+
92+
Have a look at `simple.html`.
93+
94+
## Blocks
95+
96+
The blocks is an object containing:
97+
98+
* `name`: the name of the block
99+
* `family`: the block family, this will be used to put it in the right
100+
blocks menu sub-section
101+
* `module`: the block module, act like a namespace and avoid name collisions
102+
* `description`: a description of what the block does, to help the user
103+
* `size`: the size of the block, can be ̀`small`, `normal` or a certain
104+
number of pixels
105+
* `fields`: listing of the block [fields](#fields), see below
106+
* `class`: additionals CSS classes that will be added to the block
107+
108+
### Fields
109+
110+
A field can be an input, output and/or an editable parameter of the block.
111+
It is an object containing:
112+
113+
* `name`: the name of the field, should not contain special chars
114+
* `prettyName`: the pretty name of the field, which will be printed in
115+
the blocks title, can contain special characters
116+
* `attrs`: a string containg field attributes, can contain `input`, `output`
117+
and/or `editable`. For instance: `"editable input"`
118+
* ̀`type`: the field type. See [typing](#typing).
119+
* `defaultValue`: the default value of the field, that will be used if it's
120+
editable
121+
* `hide`: do not display the editable field in the block information
122+
* `hideLabel`: do not display the editable field label in the block information
123+
* `card`: the cardinality of the input/output. This can be a string like `"0-3"`
124+
or and array like `[0,3]`, it represents the minimum and the maximum edges that
125+
can be connected to the I/O.
126+
* `dimension`: the number of connection on the same field can depend on another
127+
field value, size, or be fixed to a static number. See [variadic I/Os](#variadoc-ios)
128+
129+
Do not hesitate to have a look at the repository demo, in the `demo/̀ directory.
130+
131+
## Scene
132+
133+
The scene is an easy-to-parse object containing:
134+
135+
* `blocks`: the scene blocks
136+
* `edges`: the scene edges
137+
138+
## Scene blocks
139+
140+
All scene block is represented with:
141+
142+
* `id`: its numeric ID
143+
* `x` and `y`, the position of the block in the scene
144+
* `type`: the block type name
145+
* `module`: the block type module name
146+
* `values`: an array containing the values of all its editable fields
147+
148+
## Scene edges
149+
150+
A scene edge is represented with:
151+
152+
* `id`: its numeric ID
153+
* `block1`: the ID of the block where the edge starts
154+
* `connector1`: the connector of the block where the edge starts
155+
* `block2`: the ID of the block where the edge ends
156+
* `connector2`: the connector of the block where the edge ends
157+
158+
## Scene connectors
159+
160+
A connector is an array containing 2 or 3 elements:
161+
162+
* A string, `input` or `output`, explaining if the connector is outgoing of
163+
the block or entering in it
164+
* The name of the block field, in lower case
165+
* Optionally, the index for [variadic fields](#variadic-ios)
166+
167+
## Typing
168+
169+
Doc soon
170+
171+
## Variadic I/Os
172+
173+
Doc soon
174+
175+
## Contributing & hacking
176+
177+
The development takes places in the `src/` directory. There is a `Makefile`
178+
using `uglifyjs` command line to create the build.
179+
180+
You can use `index-dev.html` to test blocks.js using its sources, and `index.html`
181+
to try it in build mode.
182+
183+
The `build/` directory of this repository will not be updated on every commit, but
184+
must contain a recent snapshot of the repository.
185+
186+
## License
187+
188+
blocks.js is under MIT license. Have a look at the LICENSE file for more information.

‎simple.html

+50
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
<!DOCTYPE html>
2+
<html>
3+
<head>
4+
<meta charset="utf-8" />
5+
<!-- Third party libraries -->
6+
<script type="text/javascript" src="build/jquery.js"></script>
7+
<script type="text/javascript" src="build/jquery.json.min.js"></script>
8+
<script type="text/javascript" src="build/jquery.mousewheel.min.js"></script>
9+
<script type="text/javascript" src="build/jquery.svg.min.js"></script>
10+
<script type="text/javascript" src="build/jquery.formserialize.min.js"></script>
11+
<script type="text/javascript" src="build/jquery.fancybox.min.js"></script>
12+
<link rel="stylesheet" type="text/css" href="build/fancybox/jquery.fancybox.css" />
13+
14+
<!-- blocks.js -->
15+
<script type="text/javascript" src="build/blocks.js"></script>
16+
<link rel="stylesheet" type="text/css" href="build/blocks.css" />
17+
18+
<!-- Demo script -->
19+
<link rel="stylesheet" type="text/css" href="css/style.css" />
20+
<script type="text/javascript">
21+
var blocks = new Blocks();
22+
23+
blocks.register({
24+
name: "Test",
25+
fields: [
26+
{
27+
name: "Input",
28+
attrs: "input"
29+
},
30+
{
31+
name: "Output",
32+
attrs: "output"
33+
}
34+
]
35+
});
36+
37+
blocks.run("#blocks");
38+
</script>
39+
</head>
40+
<body>
41+
<h1>blocks.js</h1>
42+
<div id="blocks"></div>
43+
<button class="setLabel">Set the edges label</button>
44+
<button class="setInfos">Set the block infos</button>
45+
<button class="setDescriptions">Set the block descriptions</button>
46+
<button class="resize">Resize the div</button>
47+
<button class="hideIcons">Hide icons</button>
48+
<button class="stressTest">Stress Test!</button>
49+
</body>
50+
</html>

0 commit comments

Comments
 (0)