Skip to content

Commit 219078b

Browse files
committed
Updated documentation
1 parent 8d33e14 commit 219078b

File tree

1 file changed

+162
-8
lines changed

1 file changed

+162
-8
lines changed

README.md

Lines changed: 162 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,17 +4,17 @@ Angular Schema Form
44
Generate forms from a JSON schema, with AngularJS!
55

66
Schema Form is a set of AngularJS directives (and a service..) that can create a form directly from a json schema
7-
definition and also validate against that schema. The defaults may be fine for a lot cases, but you can also
7+
definition and also validate against that schema. The defaults may be fine for a lot cases, but you can also
88
customize it, changing order and type of fields.
99

1010

1111
Schema Form is inspired by the nice [JSON Form](https://github.com/joshfire/jsonform) library and aims to be roughly
1212
compatible with it, especially it's form defintion. What sets Schema Form apart from JSON Form is that Schema Form
1313
aims to be deeply integrated with AngularJS, i.e. to use the standard AngularJS way of handling forms. It also uses
1414
[tv4](https://github.com/geraintluff/tv4) for validation which means its compatible with version 4 of the json schema
15-
standard. Schema Form, as a default, generates bootstrap 3 friendly HTML.
15+
standard. Schema Form, as a default, generates bootstrap 3 friendly HTML.
1616

17-
Another thing that sets Schema Form apart is that it, at the moment, doesn't implement half of what JSON Form
17+
Another thing that sets Schema Form apart is that it, at the moment, doesn't implement half of what JSON Form
1818
does, nor have any documentation! Which of course we hope to remedy soon.
1919

2020

@@ -35,25 +35,179 @@ function FormController($scope) {
3535
type: "object",
3636
properties: {
3737
name: { type: "string", minLength: 2, title: "Name", description: "Name or alias" },
38-
title: {
38+
title: {
3939
type: "string",
4040
enum: ['dr','jr','sir','mrs','mr','NaN','dj']
4141
}
4242
};
43-
44-
43+
4544
$scope.form = [
4645
"*",
47-
{
46+
{
4847
type: "submit",
4948
title: "Save",
5049
}
5150
];
52-
51+
5352
$scope.data = {};
5453
}
5554
```
5655
56+
Form types
57+
----------
58+
Schema Form currently supports the following form field types:
59+
| Type | Becomes |
60+
|:--------------|:-----------------------:|
61+
| fieldset | a fieldset with legend |
62+
| section | just a div |
63+
| actions | horizontal button list, can only submit buttons as items |
64+
| text | input with type text |
65+
| textarea | a textarea |
66+
| number | input type number |
67+
| checkbox | a checkbox |
68+
| checkboxes | list of checkboxes |
69+
| select | a select (single value)|
70+
| submit | a submit button |
71+
72+
73+
74+
Default form types
75+
------------------
76+
| Schema | Form type |
77+
|:-------------------|:------------:|
78+
| "type": "string" | text |
79+
| "type": "number" | number |
80+
| "type": "integer" | number |
81+
| "type": "boolean" | checkbox |
82+
| "type": "object" | fieldset |
83+
| "type": "string" and a "enum" | select |
84+
| "type": "array" and a "enum" in array type | checkboxes |
85+
86+
87+
88+
Form definition and "*"
89+
----------------------
90+
If you don't supply a form definition, it will default to rendering the after the defaults taken
91+
from the schema.
92+
93+
A form definition is a list where the items can be
94+
* A star, ```"*"```
95+
* A string with the dot notated name/path to a property, ```"name"```
96+
* An object with that defines the options for a form field., ```{ key: "name" }```
97+
98+
The star, ```"*"``` means "use the default for the entire schema" and is useful when you want the
99+
defaults plus an additional button.
100+
101+
ex.
102+
```javascript
103+
[
104+
"*",
105+
{ type: 'submit', title: 'Save' }
106+
]
107+
```
108+
109+
The string notation, ```"name"```, is just a shortcut for the object notation ```{ key: "name" }```
110+
where key denotes what part of the schema we're creating a form field for.
111+
112+
113+
Overriding field types and order
114+
--------------------------------
115+
The order of the fields is technically undefined since the order of attributes on an javascript
116+
object (which the schema ends up being) is undefined. In practice it kind of works though.
117+
If you need to override the order of the forms, or just want to be sure, specify a form definition.
118+
119+
ex.
120+
```javascript
121+
var schema = {
122+
"type": "object",
123+
"properties": {
124+
"surname": { "type": "string" },
125+
"firstname": { "type": "string" },
126+
}
127+
}
128+
129+
[
130+
"firstname",
131+
"surname"
132+
]
133+
```
134+
135+
You can also override fields to force the type and supply other options:
136+
ex.
137+
138+
```javascript
139+
var schema = {
140+
"type": "object",
141+
"properties": {
142+
"surname": { "type": "string" },
143+
"firstname": { "type": "string" },
144+
}
145+
}
146+
147+
[
148+
"firstname",
149+
{
150+
key: "surname",
151+
type: "select",
152+
itemNames: {
153+
"Andersson": "Andersson",
154+
"Johansson": "Johansson",
155+
"other": "Something else..."
156+
}
157+
}
158+
]
159+
```
160+
161+
Options
162+
-------
163+
164+
General options most field types can handle:
165+
```javascript
166+
{
167+
key: "address.street", //The dot notatin to the attribute on the model
168+
type: "text", //Type of field
169+
title: "Street", //Title of field, taken from schema if available
170+
notitle: false, //Set to true to hide title
171+
description: "Street name", //A description, taken from schema if available
172+
}
173+
```
174+
57175
176+
Specific options per type
177+
-------------------------
58178
179+
*fieldset* and *section* doesn't need a key. You can create generic groups with them.
180+
They do need a list of ```items``` to have as children.
181+
```javascript
182+
{
183+
type: "fieldset",
184+
items: [
185+
"name",
186+
{ key: "surname", notitle: true }
187+
]
188+
}
189+
```
190+
191+
192+
*select* and *checkboxes* can take an object, ```itemNames```, where key is the value to be saved on the model
193+
and the value is the title of the option.
194+
```javascript
195+
{
196+
type: "select",
197+
itemNames: {
198+
"yes": "Yes I do",
199+
"no": "Hell no"
200+
}
201+
}
202+
```
203+
204+
*actions* behaves the same as fieldset, but can only handle buttons as chidren.
205+
```javascript
206+
{
207+
type: "actions",
208+
items: [
209+
{ type: 'submit', title: 'Ok' }
210+
]
211+
}
212+
```
59213

0 commit comments

Comments
 (0)