<commit_before>[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/formly-js/angular-formly?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[![Build Status](https://travis-ci.org/formly-js/angular-formly.svg)](https://travis-ci.org/formly-js/angular-formly)

# angular-formly

Formly for Angular is an AngularJS module which has directives to help customize and render JavaScript configured forms.
The directive originated from a need to allow our users to create surveys and distribute them easily. Buckle up, because
angular-formly is very powerful.

```html
<formly-form model="formData" fields="formFields"></formly-form>
```

## NOTICE: UPGRADING FROM 2.0 to 3.0?

There were some [significant changes](https://github.com/formly-js/angular-formly/blob/master/CHANGELOG.md) that you'll
want to be aware of. In order to upgrade and get all the cool features, you're going to need to change your field
configurations. [Here is a tool](http://jsbin.com/ruwoke) that should help make that process easier. Also, if you are
not able to update the configuration very easily, see
[this issue](https://github.com/formly-js/angular-formly/issues/162) for ideas on how to ease things a little.

## Demo

http://formly-js.github.io/angular-formly/

## Dependencies

 - Angular

## Install in your project
1. Install with bower or npm (or just download the script)

 `$ bower install angular-formly --save`

 or

 `$ npm install angular-formly --save`

2. Include the javascript file in your index.html, Formly without any form templates. You can create your own or use
some of our prebuilt templates which cover basic form types, then extend with your own as needed.

 `<script src="bower_components/angular-formly/dist/formly.min.js"></script>`

 and

 `angular.module('yourModule', ['formly']);`

 or

 `angular.module('yourModule', [require('angular-formly')]);`


### Prebuilt Templates

While it is recommended to create your own templates for ultimate customization and flexibility, there are prebuilt
templates you can use:

 - [Vanilla HTML](https://github.com/formly-js/angular-formly-templates-vanilla)
 - [Bootstrap](https://github.com/formly-js/angular-formly-templates-bootstrap)
 - [LumX](https://github.com/formly-js/angular-formly-templates-lumx)
 - [angular-material](https://github.com/formly-js/angular-formly-templates-material) (WIP)
 - [Ionic](https://github.com/formly-js/angular-formly-templates-ionic): (WIP, owner needed)
 - [Foundation](https://github.com/formly-js/angular-formly-templates-foundation): (WIP, owner needed)

### DIY Templates

Regardless of which flavor you use (or if you use no flavor at all), you can create your own templates with
`formlyConfigProvider`. This is the recommended approach if you want to customize your templates at all.

## Documentation

*Note:* This `README.md` is for the latest version of `formly`. Be sure to check that you're reading the right docs!

`https://github.com/formly-js/angular-formly/tree/{{YOUR_VERSION}} <-- insert your version`

### Example

Here's an example using the vanilla template properties

You can add a formly-form in your HTML templates as shown below.
```html
<formly-form model="formData" fields="formFields">
	<button ng-click="onSubmit()">Hello World</button>
</formly-form>
```

Example data as it would be set in the controller
```javascript
$scope.formData = {};
$scope.formFields = [
	{
		//the key to be used in the model values {... "username": "johndoe" ... }
		key: 'username',

		type: 'text',
		label: 'Username',
		placeholder: 'johndoe',
		required: true,
		disabled: false, //default: false
		description: 'Descriptive text'
	},
	{
		key: 'password',
		type: 'password',
		label: 'Password',
		required: true,
		disabled: false, //default: false
		expressionProperties: {
			hide: '!model.username' // hide when username is blank
		}
	}

];

$scope.onSubmit = function() {
	console.log('form submitted:', $scope.formData);
};
```

### Creating Form Fields
When constructing fields use the options below to customize each field object. You must set at least a `type`,
`template`, or `templateUrl`.

### Valid field options

You can only specify these properties. Additional properties will result in an error. If you need custom properties, use
`templateOptions` or `data`.

##### type (string)
>`type` is the type of field to be rendered. Either type, template, or templateUrl must be set.
<commit_msg>Updating readme basic example to actually work.<commit_after>[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/formly-js/angular-formly?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[![Build Status](https://travis-ci.org/formly-js/angular-formly.svg)](https://travis-ci.org/formly-js/angular-formly)

# angular-formly

Formly for Angular is an AngularJS module which has directives to help customize and render JavaScript configured forms.
The directive originated from a need to allow our users to create surveys and distribute them easily. Buckle up, because
angular-formly is very powerful.

```html
<formly-form model="formData" fields="formFields"></formly-form>
```

## NOTICE: UPGRADING FROM 2.0 to 3.0?

There were some [significant changes](https://github.com/formly-js/angular-formly/blob/master/CHANGELOG.md) that you'll
want to be aware of. In order to upgrade and get all the cool features, you're going to need to change your field
configurations. [Here is a tool](http://jsbin.com/ruwoke) that should help make that process easier. Also, if you are
not able to update the configuration very easily, see
[this issue](https://github.com/formly-js/angular-formly/issues/162) for ideas on how to ease things a little.

## Demo

http://formly-js.github.io/angular-formly/

## Dependencies

 - Angular

## Install in your project
1. Install with bower or npm (or just download the script)

 `$ bower install angular-formly --save`

 or

 `$ npm install angular-formly --save`

2. Include the javascript file in your index.html, Formly without any form templates. You can create your own or use
some of our prebuilt templates which cover basic form types, then extend with your own as needed.

 `<script src="bower_components/angular-formly/dist/formly.min.js"></script>`

 and

 `angular.module('yourModule', ['formly']);`

 or

 `angular.module('yourModule', [require('angular-formly')]);`


### Prebuilt Templates

While it is recommended to create your own templates for ultimate customization and flexibility, there are prebuilt
templates you can use:

 - [Vanilla HTML](https://github.com/formly-js/angular-formly-templates-vanilla)
 - [Bootstrap](https://github.com/formly-js/angular-formly-templates-bootstrap)
 - [LumX](https://github.com/formly-js/angular-formly-templates-lumx)
 - [angular-material](https://github.com/formly-js/angular-formly-templates-material) (WIP)
 - [Ionic](https://github.com/formly-js/angular-formly-templates-ionic): (WIP, owner needed)
 - [Foundation](https://github.com/formly-js/angular-formly-templates-foundation): (WIP, owner needed)

### DIY Templates

Regardless of which flavor you use (or if you use no flavor at all), you can create your own templates with
`formlyConfigProvider`. This is the recommended approach if you want to customize your templates at all.

## Documentation

*Note:* This `README.md` is for the latest version of `formly`. Be sure to check that you're reading the right docs!

`https://github.com/formly-js/angular-formly/tree/{{YOUR_VERSION}} <-- insert your version`

### Example

Here's an example using the vanilla template properties

You can add a formly-form in your HTML templates as shown below.
```html
<formly-form model="formData" fields="formFields">
	<button ng-click="onSubmit()">Hello World</button>
</formly-form>
```

Example data as it would be set in the controller
```javascript
$scope.formData = {};
$scope.formFields = [
	{
		//the key to be used in the model values {... "username": "johndoe" ... }
		key: 'username',
		type: 'input',
		templateOptions: {
			label: 'Username',
			placeholder: 'johndoe',
			required: true,
			description: 'Descriptive text'
		}
	},
	{
		key: 'password',
		type: 'input',
		templateOptions: {
		  type: 'password',
  		label: 'Password',
  		required: true
		},
		expressionProperties: {
			'templateOptions.disabled': '!model.username' // disabled when username is blank
		}
	}
];

$scope.onSubmit = function() {
	console.log('form submitted:', $scope.formData);
};
```

### Creating Form Fields
When constructing fields use the options below to customize each field object. You must set at least a `type`,
`template`, or `templateUrl`.

### Valid field options

You can only specify these properties. Additional properties will result in an error. If you need custom properties, use
`templateOptions` or `data`.

##### type (string)
>`type` is the type of field to be rendered. Either type, template, or templateUrl must be set.

{'fraction_non_alphanumeric': 0.12527864467231387, 'fraction_numerical': 0.002452073116362015, 'mean_word_length': 4.515058389674247, 'pattern_counts': {'":': 2, '<': 21, '<?xml version=': 0, '>': 21, 'https://': 26, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1710198', 'n_tokens_mistral': 2823, 'n_tokens_neox': 2664, 'n_words': 920}