Skip to content

Commit dd3c197

Browse files
AnthropicAnthropic
committed
Update documentation on using builders
1 parent f43e2f8 commit dd3c197

File tree

2 files changed

+180
-71
lines changed

2 files changed

+180
-71
lines changed

‎docs/extending.md

Lines changed: 130 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,34 @@
1+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
2+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
3+
**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
4+
5+
- [Extending Schema Form](#extending-schema-form)
6+
- [How the form is built](#how-the-form-is-built)
7+
- [The actual building](#the-actual-building)
8+
- [Creating an add-on](#creating-an-add-on)
9+
- [The Template](#the-template)
10+
- [Compile template](#compile-template)
11+
- [Builder functions](#builder-functions)
12+
- [Application of builder functions](#application-of-builder-functions)
13+
- [Defining a decorator](#defining-a-decorator)
14+
- [Setting up schema defaults](#setting-up-schema-defaults)
15+
- [Sharing your add-on with the world](#sharing-your-add-on-with-the-world)
16+
- [The builders](#the-builders)
17+
- [builders.sfField](#builderssffield)
18+
- [builders.condition](#builderscondition)
19+
- [builder.ngModel](#builderngmodel)
20+
- [sf-field-model](#sf-field-model)
21+
- [sf-field-model="attribute name"](#sf-field-modelattribute-name)
22+
- [sf-field-model="replaceAll"](#sf-field-modelreplaceall)
23+
- [builders.ngModelOptions](#buildersngmodeloptions)
24+
- [builder.simpleTransclusion](#buildersimpletransclusion)
25+
- [Useful directives](#useful-directives)
26+
- [sf-field](#sf-field)
27+
- [What's on the scope?](#whats-on-the-scope)
28+
- [Deprecation warning](#deprecation-warning)
29+
30+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
31+
132
Extending Schema Form
233
=====================
334

@@ -102,14 +133,55 @@ Basic template example:
102133
</div>
103134
```
104135

105-
**BIG FAT CAVEAT**
106-
Ok, so currently there is something really ugly here. The bootstrap (and material) decorator uses
136+
#### Compile template
137+
Currently there is something of a nuisance here. The bootstrap (and material) decorator use
107138
a build step (gulp-angular-templatecache) to "compile" the template into a javascript file that
108-
basically chucks the template into `$templateCache`. Currently schema form does *not* support
109-
loading the templates any other way. They need to be in `$templateCache` when rendering.
139+
adds the template into `$templateCache`. Currently schema form does *not* support
140+
loading the templates any other way. **They need to be in `$templateCache` when rendering**.
141+
142+
We strongly recommend using the yeoman generator for creating add-ons https://github.com/json-schema-form/generator-angular-schema-form-add-on
143+
144+
#### Builder functions
145+
A more detailed description of the built in builders can be found below, however this section
146+
describes how you can add your own builder to process your template as it is inserted into the
147+
schema-form output.
148+
149+
A builder function takes an `args` object containing
150+
- fieldFrag - a document fragment for manipulating prior to its insertion into the form
151+
- form - The currently processing form definition
152+
- lookup - A reference list for items added already
153+
- state - Any behaviour or defaults being passed from parents
154+
- path - The path to the form definition
155+
- build - A build function used for building child elements from a form definition
156+
157+
The below builder looks up a `textarea` element and sets a md-maxlength attribute
158+
```javascript
159+
function textareaBuilder(args) {
160+
var textareaFrag = args.fieldFrag.querySelector('textarea');
161+
var maxLength = args.form.maxlength || false;
162+
if (textareaFrag && maxLength) {
163+
textareaFrag.setAttribute('md-maxlength', maxLength);
164+
};
165+
};
166+
```
110167

111-
This is really ugly and will be fixed. But you have been warned!
168+
#### Application of builder functions
169+
To make your add-on use the builder it must be in the array of builders in the decorator definition.
112170

171+
To update the previous example to add my builder, since `sfBuilderProvider.stdBuilders` is an
172+
array I can simply add `.concat(textarea)` as below:
173+
```js
174+
angular.module('myAddOnModule', ['schemaForm']).config(function(schemaFormDecoratorsProvider, sfBuilderProvider) {
175+
176+
schemaFormDecoratorsProvider.defineAddOn(
177+
'bootstrapDecorator', // Name of the decorator you want to add to.
178+
'awesome', // Form type that should render this add-on
179+
'templates/my/addon.html', // Template name in $templateCache
180+
sfBuilderProvider.stdBuilders.concat(textarea) // List of builder functions to apply.
181+
);
182+
183+
});
184+
```
113185

114186
Defining a decorator
115187
--------------------
@@ -190,25 +262,25 @@ So [make a bower package](http://bower.io/docs/creating-packages/), add the keyw
190262

191263
The builders
192264
------------
193-
A collection of useful builders that cover most cases are in the `sfBuilder` service and is accessable
194-
both from the provider and the service on the property `builders`. There is also a list of "standard"
195-
builders, when in doubt use those.
265+
A collection of useful builders that cover most cases are in the `sfBuilder` service and is accessable
266+
both from the provider and the service on the property `builders`. There is also a list of "standard"
267+
builders, when in doubt use those.
196268

197269
```js
198270
angular.module('myMod').config(function(sfBuildersProvider) {
199271

200272
// Standard builders
201273
sfBuildersProvider.stdBuilders;
202-
203-
// All builders
274+
275+
// All builders
204276
sfBuildersProvider.builders.sfField;
205277
sfBuildersProvider.builders.condition;
206-
sfBuildersProvider.builders.ngModel;
278+
sfBuildersProvider.builders.ngModel;
207279
sfBuildersProvider.builders.ngModelOptions;
208280
sfBuildersProvider.builders.simpleTransclusion;
209281
sfBuildersProvider.builders.transclusion;
210282
sfBuildersProvider.builders.array;
211-
283+
212284
});
213285
```
214286

@@ -224,32 +296,31 @@ var stdBuilders = [
224296

225297

226298
### builders.sfField
227-
The `sfField` builder adds the `sf-field="..."` directive to *the first child element* in the template,
299+
The `sfField` builder adds the `sf-field="..."` directive to *the first child element* in the template,
228300
giving it a correct value. The value is an id number that identifies that specific form object.
229301

230-
The `sf-field` directive exports the form definition object as `form` on scope and as a lot of useful functions.
302+
The `sf-field` directive exports the form definition object as `form` on scope and as a lot of useful functions.
231303

232-
As a rule of thumb you always want this builder.
304+
As a rule of thumb you always want this builder.
233305

234306
### builders.condition
235-
The `condition` builder checks the form definition for the option `condition`. If it's present it adds a
307+
The `condition` builder checks the form definition for the option `condition`. If it's present it adds a
236308
`ng-if` to all top level elements in the template.
237309

238310
You usually want this as well.
239311

240-
### builder.ngModel
312+
### builder.ngModel
241313
The `ngModel` builder is maybe the most important builder. It makes sure you get a proper binding to
242-
your model value.
314+
your model value.
243315

244-
The `ngModel` builder queries the DOM of the template for all elements that have the attribute `sf-field-model`. Your template may have several of them. `sf-field-model` is *not* a directive,
316+
The `ngModel` builder queries the DOM of the template for all elements that have the attribute `sf-field-model`. Your template may have several of them. `sf-field-model` is *not* a directive,
245317
but depending on it's value the `ngModel` builder will take three different actions.
246318

247-
248-
#### sf-field-model
249-
Just `sf-field-model` or `sf-field-model=""` tells the builder to add a `ng-model` directive to this element.
319+
#### sf-field-model
320+
Just `sf-field-model` or `sf-field-model=""` tells the builder to add a `ng-model` directive to this element.
250321
This is a common use case.
251322

252-
Ex:
323+
Ex:
253324
DOM before `ngModel` builder:
254325
```html
255326
<div>
@@ -263,11 +334,11 @@ DOM after `ngModel` builder:
263334
</div>
264335
```
265336

266-
#### sf-field-model="<attribute name>"
267-
Given a value the `ngModel` builder will treat that value as a *attribute name* and instead of slapping
337+
#### sf-field-model="attribute name"
338+
Given a value the `ngModel` builder will treat that value as a *attribute name* and instead of slapping
268339
on a `ng-model` set the specified attributes value. It sets it to the same value as the `ng-model` would have gotten.
269340

270-
Ex:
341+
Ex:
271342
DOM before `ngModel` builder:
272343
```html
273344
<div sf-field-model="my-directive">
@@ -283,13 +354,13 @@ DOM after `ngModel` builder:
283354

284355
#### sf-field-model="replaceAll"
285356
With the special value *replaceAll* the `ngModel` builder will instead loop over every attribute on the
286-
element and do a string replacement of `"$$value$$"` with the proper model value.
357+
element and do a string replacement of `"$$value$$"` with the proper model value.
287358

288-
Ex:
359+
Ex:
289360
DOM before `ngModel` builder:
290361
```html
291362
<div>
292-
<input sf-field-model="replaceAll"
363+
<input sf-field-model="replaceAll"
293364
ng-model="$$value$$"
294365
ng-class="{'large': $$value$$.length > 10}"
295366
type="text">
@@ -298,7 +369,7 @@ DOM before `ngModel` builder:
298369
DOM after `ngModel` builder:
299370
```html
300371
<div>
301-
<input sf-field-model="replaceAll"
372+
<input sf-field-model="replaceAll"
302373
ng-model="model['name']"
303374
ng-class="{'large': model[name].length > 10}"
304375
type="text">
@@ -307,7 +378,7 @@ DOM after `ngModel` builder:
307378

308379
### builders.ngModelOptions
309380
If the form definition has a `ngModelOptions` option specified this builder will slap on a `ng-model-options`
310-
attribute to *the first child element* in the template.
381+
attribute to *the first child element* in the template.
311382

312383

313384
### builder.simpleTransclusion
@@ -317,4 +388,31 @@ is simple because it only appends children to the first child element and only c
317388

318389
Useful directives
319390
-----------------
320-
TODO: more in depth about schema-validate, sf-messages and sf-field
391+
392+
### sf-field
393+
sfField is the directive that adds scope to the template
394+
395+
#### What's on the scope?
396+
You have several helper functions and values on the scope, most important of this `form`. The
397+
`form` variable contains the merged form definition for that field, i.e. your supplied form object +
398+
the defaults from the schema (it also has its part of the schema under *form.schema*).
399+
This is how you define and use new form field options, whatever is set on the form object is
400+
available here for you to act on.
401+
402+
| Name | What it does |
403+
|----------|----------------|
404+
| form | Form definition object |
405+
| showTitle() | Shorthand for `form && form.notitle !== true && form.title` |
406+
| ngModel | The ngModel controller, this will be on scope if you use either the directive `schema-validate` or `sf-array` |
407+
| evalInScope(expr, locals) | Eval supplied expression, ie scope.$eval |
408+
| evalExpr(expr, locals) | Eval an expression in the parent scope of the main `sf-schema` directive. |
409+
| interp(expr, locals) | Interpolate an expression which may or may not contain expression `{{ }}` sequences |
410+
| buttonClick($event, form) | Use this with ng-click to execute form.onClick |
411+
| hasSuccess() | Shorthand for is valid and either not pristine or the model value is not empty |
412+
| hasError() | Shorthand for is invalid and not pristine |
413+
414+
#### Deprecation warning
415+
There is still a `errorMessage` function on scope but it's been deprecated. Please use the
416+
`sf-message` directive instead.
417+
418+
TODO: more in depth about schema-validate and sf-messages

‎docs/index.md

Lines changed: 50 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -11,45 +11,56 @@ specific. The docs is undergoing updating.
1111

1212
Documentation
1313
=============
14-
15-
1. [Basic Usage](#basic-usage)
16-
1. [Handling Submit](#handling-submit)
17-
1. [Updating Form](#updating-form)
18-
1. [Global Options](#global-options)
19-
1. [Validation Messages](#validation-messages)
20-
1. [Custom Validation](#custom-validation)
21-
1. [Inject errors into form, aka backend validation](#inject-errors-into-form-aka-backend-validation)
22-
1. [Using ngModelController](#using-ngmodelcontroller)
23-
1. [$validators](#$validators)
24-
1. [$asyncVaidators](#$asyncValidators)
25-
1. [Form defaults in schema](#form-defaults-in-schema)
26-
1. [Form types](#form-types)
27-
1. [Default form types](#default-form-types)
28-
1. [Form definitions](#form-definitions)
29-
1. [Overriding field types and order](#overriding-field-types-and-order)
30-
1. [Standard Options](#standard-options)
31-
1. [onChange](#onchange)
32-
1. [Validation Messages](#validation-messages)
33-
1. [Inline feedback icons](#inline-feedback-icons)
34-
1. [ngModelOptions](#ngmodeloptions)
35-
1. [copyValueTo](#copyvalueto)
36-
1. [Specific options and types](#specific-options-and-types)
37-
1. [input group addons](#input-group-addons)
38-
1. [fieldset and section](#fieldset-and-section)
39-
1. [select and checkboxes](#select-and-checkboxes)
40-
1. [actions](#actions)
41-
1. [button](#button)
42-
1. [radios and radiobuttons](#radios-and-radiobuttons)
43-
1. [help](#help)
44-
1. [template](#template)
45-
1. [tabs](#tabs)
46-
1. [array](#array)
47-
1. [tabarray](#tabarray)
48-
1. [Post process function](#post-process-function)
49-
1. [Events](#events)
50-
1. [Manual field insertion](#manual-field-insertion)
51-
1. [Deprecated fields](#deprecated-fields)
52-
1. [Extending Schema Form](extending.md)
14+
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
15+
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
16+
17+
18+
- [Basic Usage](#basic-usage)
19+
- [Handling Submit](#handling-submit)
20+
- [Updating Form](#updating-form)
21+
- [Global Options](#global-options)
22+
- [Validation Messages](#validation-messages)
23+
- [Message Interpolation](#message-interpolation)
24+
- [Taking over: functions as validationMessages](#taking-over-functions-as-validationmessages)
25+
- [Custom Validation](#custom-validation)
26+
- [Inject errors into form aka backend validation](#inject-errors-into-form-aka-backend-validation)
27+
- [Using ngModelController](#using-ngmodelcontroller)
28+
- [$validators](#validators)
29+
- [$asyncValidators](#asyncvalidators)
30+
- [Form defaults in schema](#form-defaults-in-schema)
31+
- [Form types](#form-types)
32+
- [Default form types](#default-form-types)
33+
- [Form definitions](#form-definitions)
34+
- [Overriding field types and order](#overriding-field-types-and-order)
35+
- [Standard Options](#standard-options)
36+
- [onChange](#onchange)
37+
- [Validation Messages](#validation-messages-1)
38+
- [Inline feedback icons](#inline-feedback-icons)
39+
- [ngModelOptions](#ngmodeloptions)
40+
- [copyValueTo](#copyvalueto)
41+
- [condition](#condition)
42+
- [destroyStrategy](#destroystrategy)
43+
- [Specific options and types](#specific-options-and-types)
44+
- [input group addons](#input-group-addons)
45+
- [fieldset and section](#fieldset-and-section)
46+
- [select and checkboxes](#select-and-checkboxes)
47+
- [actions](#actions)
48+
- [button and submit](#button-and-submit)
49+
- [radios and radiobuttons](#radios-and-radiobuttons)
50+
- [help](#help)
51+
- [template](#template)
52+
- [tabs](#tabs)
53+
- [array](#array)
54+
- [tabarray](#tabarray)
55+
- [Deprecation Warning](#deprecation-warning)
56+
- [Post process function](#post-process-function)
57+
- [Events](#events)
58+
- [Manual field insertion](#manual-field-insertion)
59+
- [Deprecated fields](#deprecated-fields)
60+
- [conditional](#conditional)
61+
62+
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
63+
- [Extending Schema Form](extending.md)
5364

5465
Basic Usage
5566
-----------

0 commit comments

Comments
 (0)