|
1 | 1 | Extending Schema Form |
2 | 2 | ===================== |
3 | | -Schema Form is designed to be easily extended and there are two basic ways to do it: |
4 | 3 |
|
5 | | -1. Add a new type of field |
6 | | -2. Add a new decorator |
| 4 | +Extending schema form with new form field via add-ons or changing to another CSS framework (a new |
| 5 | +decorator) is easy. But how you do it has changed recently due to "the new builder". |
7 | 6 |
|
8 | | -Adding a Field |
9 | | --------------- |
10 | | -To add a new field to Schema Form you need to create a new form type and match that form type with |
11 | | -a template snippet. To do this you use the `schemaFormDecoratorsProvider.addMapping()` function. |
12 | | - |
13 | | -Ex. from the [datepicker add-on](https://github.com/Textalk/angular-schema-form-datepicker/blob/master/src/bootstrap-datepicker.js#L18) |
14 | | -```javascript |
15 | | - schemaFormDecoratorsProvider.addMapping( |
16 | | - 'bootstrapDecorator', |
17 | | - 'datepicker', |
18 | | - 'directives/decorators/bootstrap/datepicker/datepicker.html' |
19 | | -); |
20 | | -``` |
21 | | - |
22 | | -The second argument is the name of your new form type, in this case `datepicker`, and the third is |
23 | | -the template we bind to it (the first is the decorator, use `bootstrapDecorator` unless you know |
24 | | -what you are doing). |
25 | | - |
26 | | -What this means is that a form definition like this: |
27 | | -```javascript |
28 | | -$scope.form = [ |
29 | | - { |
30 | | - key: "birthday", |
31 | | - type: "datepicker" |
32 | | - } |
33 | | -]; |
34 | | -``` |
35 | | -...will result in the `datepicker.html` template to be used to render that field in the form. |
36 | | - |
37 | | -But wait, where is all the code? Basically it's then up to the template to use directives to |
38 | | -implement whatever it likes to do. It does have some help though, lets look at template example and |
39 | | -go through the basics. |
40 | | - |
41 | | -This is sort of the template for the datepicker: |
42 | | -```html |
43 | | -<div class="form-group" ng-class="{'has-error': hasError()}"> |
44 | | - <label class="control-label" ng-show="showTitle()">{{form.title}}</label> |
45 | | - |
46 | | - <input ng-show="form.key" |
47 | | - style="background-color: white" |
48 | | - type="text" |
49 | | - class="form-control" |
50 | | - schema-validate="form" |
51 | | - ng-model="$$value$$" |
52 | | - pick-a-date |
53 | | - min-date="form.minDate" |
54 | | - max-date="form.maxDate" |
55 | | - format="form.format" /> |
56 | | - |
57 | | - <span class="help-block" sf-message="form.description"></span> |
58 | | -</div> |
59 | | -``` |
60 | | - |
61 | | -### What's on the scope? |
62 | | -Each form field will be rendered inside a decorator directive, created by the |
63 | | -`schemaFormDecorators` factory service, *do* |
64 | | -[check the source](https://github.com/Textalk/angular-schema-form/blob/master/src/services/decorators.js#L33). |
65 | | - |
66 | | -This means you have several helper functions and values on scope, most important of this `form`. The |
67 | | -`form` variable contains the merged form definition for that field, i.e. your supplied form object + |
68 | | -the defaults from the schema (it also has its part of the schema under *form.schema*). |
69 | | -This is how you define and use new form field options, whatever is set on the form object is |
70 | | -available here for you to act on. |
71 | | - |
72 | | -| Name | What it does | |
73 | | -|----------|----------------| |
74 | | -| form | Form definition object | |
75 | | -| showTitle() | Shorthand for `form && form.notitle !== true && form.title` | |
76 | | -| ngModel | The ngModel controller, this will be on scope if you use either the directive `schema-validate` or `sf-array` | |
77 | | -| evalInScope(expr, locals) | Eval supplied expression, ie scope.$eval | |
78 | | -| evalExpr(expr, locals) | Eval an expression in the parent scope of the main `sf-schema` directive. | |
79 | | -| interp(expr, locals) | Interpolate an expression which may or may not contain expression `{{ }}` sequences | |
80 | | -| buttonClick($event, form) | Use this with ng-click to execute form.onClick | |
81 | | -| hasSuccess() | Shorthand for `ngModel.$valid && (!ngModel.$pristine || !ngModel.$isEmpty(ngModel.$modelValue))` | |
82 | | -| hasError() | Shorthand for `ngModel.$invalid && !ngModel.$pristine` | |
83 | | - |
84 | | -#### Deprecation warning |
85 | | -There is still a `errorMessage` function on scope but it's been deprecated. Please use the |
86 | | -`sf-message` directive instead. |
87 | | - |
88 | | - |
89 | | -### The magic $$value$$ |
90 | | -Schema Form wants to play nice with the built in Angular directives for form. Especially `ng-model` |
91 | | -which we want to handle the two way binding against our model value. Also by using `ng-model` we |
92 | | -get all the nice validation states from the `ngModelController` and `FormController` that we all |
93 | | -know and love. |
94 | | - |
95 | | -To get that working properly we had to resort to a bit of trickery, right before we let Angular |
96 | | -compile the field template we do a simple string replacement of `$$value$$` and replace that |
97 | | -with the path to the current form field on the model, i.e. `form.key`. |
98 | | - |
99 | | -So `ng-model="$$value$$"` becomes something like `ng-model="model['person']['address']['street']"`, |
100 | | -you can see this if you inspect the final form in the browser. |
101 | | - |
102 | | -So basically always have a `ng-model="$$value$$"` (Pro tip: ng-model is fine on any element, put |
103 | | - it on the same div as your custom directive and require the ngModelController for full control). |
104 | | - |
105 | | -### schema-validate directive |
106 | | -`schema-validate` is a directive that you should put on the same element as your `ng-model`. It is |
107 | | -responsible for validating the value against the schema using [tv4js](https://github.com/geraintluff/tv4) |
108 | | -It takes the form definition as an argument. |
109 | | - |
110 | | - |
111 | | -### sf-message directive |
112 | | -Error messages are nice, and the best way to get them is via the `sf-message` directive. It usually |
113 | | -takes `form.description` as an argument so it can show that until an error occurs. |
114 | | - |
115 | | - |
116 | | -### Setting up schema defaults |
117 | | -So you got this shiny new add-on that adds a fancy field type, but feel a bit bummed out that you |
118 | | -need to specify it in the form definition all the time? Fear not because you can also add a "rule" |
119 | | -to map certain types and conditions in the schema to default to your type. |
120 | | - |
121 | | -You do this by adding to the `schemaFormProvider.defaults` object. The `schemaFormProvider.defaults` |
122 | | -is an object with a key for each type *in JSON Schema* with a array of functions as its value. |
123 | | - |
124 | | -```javscript |
125 | | -var defaults = { |
126 | | - string: [], |
127 | | - object: [], |
128 | | - number: [], |
129 | | - integer: [], |
130 | | - boolean: [], |
131 | | - array: [] |
132 | | -}; |
133 | | -``` |
134 | | - |
135 | | -When schema form traverses the JSON Schema to create default form definitions it first checks the |
136 | | -*JSON Schema type* and then calls on each function in the corresponding list *in order* until a |
137 | | -function actually returns something. That is then used as a defualt. |
138 | | - |
139 | | -This is the function that makes it a datepicker if its a string and has format "date" or "date-time": |
140 | | - |
141 | | -```javascript |
142 | | -var datepicker = function(name, schema, options) { |
143 | | - if (schema.type === 'string' && (schema.format === 'date' || schema.format === 'date-time')) { |
144 | | - var f = schemaFormProvider.stdFormObj(name, schema, options); |
145 | | - f.key = options.path; |
146 | | - f.type = 'datepicker'; |
147 | | - options.lookup[sfPathProvider.stringify(options.path)] = f; |
148 | | - return f; |
149 | | - } |
150 | | -}; |
151 | | - |
152 | | -// Put it first in the list of functions |
153 | | -schemaFormProvider.defaults.string.unshift(datepicker); |
154 | | -``` |
155 | | - |
156 | | -### Sharing your add-on with the world |
157 | | -So you made an add-on, why not share it with us? On the front page, |
158 | | -[http://textalk.github.io/angular-schema-form/](http://textalk.github.io/angular-schema-form/#third-party-addons), we |
159 | | -maintain a list of add ons based on a query of the bower register, and we love to see your add-on |
160 | | -there. |
161 | | - |
162 | | -Any [bower](http://bower.io) package with a name starting with `angular-schema-form-` or that has |
163 | | -the `keyword` `angular-schema-form-add-on` in its `bower.json` will be picked up. It's cached so |
164 | | -there can be a delay of a day or so. |
165 | | - |
166 | | -So [make a bower package](http://bower.io/docs/creating-packages/), add the keyword |
167 | | -`angular-schema-form-add-on` and [register it](http://bower.io/docs/creating-packages/#register)! |
168 | | - |
169 | | -Decorators |
170 | | ----------- |
171 | | -Decorators are a second way to extend Schema Form, the thought being that you should easily be able |
172 | | -to change *every* field. Maybe you like it old school and want to use bootstrap 2. Or maybe you like |
173 | | -to generate a table with the data instead? Right now there are no other decorators than bootstrap 3. |
174 | | - |
175 | | -Basically a *decorator* sets up all the mappings between form types and their respective templates |
176 | | -using the `schemaFormDecoratorsProvider.createDecorator()` function. |
177 | | - |
178 | | -```javascript |
179 | | -var base = 'directives/decorators/bootstrap/'; |
180 | | - |
181 | | -schemaFormDecoratorsProvider.createDecorator('bootstrapDecorator', { |
182 | | - textarea: base + 'textarea.html', |
183 | | - fieldset: base + 'fieldset.html', |
184 | | - array: base + 'array.html', |
185 | | - tabarray: base + 'tabarray.html', |
186 | | - tabs: base + 'tabs.html', |
187 | | - section: base + 'section.html', |
188 | | - conditional: base + 'section.html', |
189 | | - actions: base + 'actions.html', |
190 | | - select: base + 'select.html', |
191 | | - checkbox: base + 'checkbox.html', |
192 | | - checkboxes: base + 'checkboxes.html', |
193 | | - number: base + 'default.html', |
194 | | - password: base + 'default.html', |
195 | | - submit: base + 'submit.html', |
196 | | - button: base + 'submit.html', |
197 | | - radios: base + 'radios.html', |
198 | | - 'radios-inline': base + 'radios-inline.html', |
199 | | - radiobuttons: base + 'radio-buttons.html', |
200 | | - help: base + 'help.html', |
201 | | - 'default': base + 'default.html' |
202 | | -}, [ |
203 | | - function(form) { |
204 | | - if (form.readonly && form.key && form.type !== 'fieldset') { |
205 | | - return base + 'readonly.html'; |
206 | | - } |
207 | | - } |
208 | | -]); |
209 | | -``` |
210 | | -`schemaFormDecoratorsProvider.createDecorator(name, mapping, rules)` takes a name argument, a mapping object |
211 | | -(type -> template) and an optional list of rule functions. |
212 | | - |
213 | | -When the decorator is trying to match a form type against a tempate it first executes all the rules |
214 | | -in order. If one returns that is used as template, otherwise it checks the mappings. |
| 7 | +New documentation is in the works and will come soon. |
0 commit comments