Formly for Angular is an AngularJS module which has directives to help customize and render JSON based forms. The directive originated from a need to allow our users to create surveys and distribute them easily. Currently we've can render the form data from JSON and assign a model to form so we can receive the submitted data.
<formly-form result="formData" fields="formFields" options="formOptions" ng-submit="onSubmit()">
</formly-form>
-
Required to use Formly:
-
Angular
-
Twitter Bootstrap (Default templates use TBS, you can create use your own templates with
formlyTemplateProvider
) -
Dev dependencies to build Formly
-
npm
See bower.json
and index.html
in the master
branch for a full list / more details
-
Install with Bower
$ bower install angular-formly
-
Include the files in your index.html
<script src="bower_components/angular-formly/dist/formly.min.js"></script>
-
Add 'formly' as a required module to your angular app, usually in
app.js
:
var app = angular.module('app', ['ng', 'ui.router', 'formly']);
You can add a formly-form in your HTML templates as shown below.
<formly-form result="formData" fields="formFields" options="formOptions" ng-submit="onSubmit()">
</formly-form>
Example data as it would be set in the controller
$scope.formData = {};
$scope.formFields = [
{
//the key to be used in the result values {... "username": "johndoe" ... }
key: 'username',
//default value
default: 'uberuser'
type: 'text',
label: 'Username',
placeholder: 'johndoe',
required: true,
disabled: false, //default: false
},
{
key: 'password'
type: 'password',
label: 'Password',
required: true,
disabled: false, //default: false
hideExpression: '!username' // hide when username is blank
}
];
$scope.formOptions = {
//Set the id of the form
uniqueFormId: 'myFormId',
//Hide the submit button that is added automaticaly
//default: false
hideSubmit: false,
//Set the text on the default submit button
//default: Submit
submitCopy: 'Login'
};
$scope.onSubmit = function() {
console.log('form submitted:', $scope.formData);
};
Forms can be customized with the options below.
uniqueFormId
is used to identify the form.
hideSubmit
hides the submit button when set totrue
. Defaults to false.
submitCopy
customizes the submit button copy. Defaults to 'Submit'.
When constructing fields use the options below to customize each field object. You must set at least a type
, template
, or templateUrl
.
type
is the type of field to be rendered. Either type, template, or templateUrl must be set.
null
text
,textarea
,radio
select
number
checkbox
,password
,hidden
,
template
can be set instead oftype
ortemplateUrl
to use a custom html template form field. Should be used with one-liners mostly (like a directive). Useful for adding functionality to fields.
undefined
templateUrl
can be set instead oftype
ortemplate
to use a custom html template form field. Set a path relative to the root of the application. iedirectives/custom-field.html
undefined
By default form results are keyed by location in the form array, you can override this by specifying a
key
.
undefined
label
is used to add an html label to each field.
A default is set for each field based on its type. ie
Text
,Checkbox
,Password
required
is used to add the required attribute to a form field.
undefined
hideExpression
is used to conditionally show the input. Evaluates on theresult
and uses thehide
property on the field.
undefined
hide
is used to conditionally show the input. When true, the input is hidden (meant to be used with a watch).
undefined
disabled
is used to add the disabled attribute to a form field.
undefined
placeholder
is used to add placeholder text to some inputs.
undefined
Below is a detailed description of each form fields and its custom properties.
The text field allows single line input with a input element set to
type='text'
. It doesn't have any custom properties.
Example text field
{
"type": "text",
"key": "firstName",
"placeholder": "jane doe",
"label": "First name"
}
The textarea field creates multiline input with a textarea element.
lines
sets the rows attribute for the textarea element. If unset, the default is 2 lines.
Example textarea field
{
"type": "textarea",
"key": "about",
"placeholder": "I like puppies",
"label": "Tell me about yourself",
"lines": 4
}
The checkbox field allows checkbox input with a input element set to
type='checkbox'
. It doesn't have any custom properties.
Example checkbox field
{
"type": "checkbox",
"key": "checkThis",
"label": "Check this box",
"default": true
}
The radio field allows multiple choice input with a series of linked inputs, with
type='radio'
.
The default can be set to the
value
of one of theoptions
.
options
is an array of options for the radio form field to display. Each option should be an object with aname
(string) andvalue
(string or number).
Example radio field
{
"key": "triedEmber",
"type": "radio",
"label": "Have you tried EmberJs yet?",
"default": "no",
"options": [
{
"name": "Yes, and I love it!",
"value": "yesyes"
},
{
"name": "Yes, but I'm not a fan...",
"value": "yesno"
},
{
"name": "Nope",
"value": "no"
}
]
}
The select field allows selection via dropdown using the select element.
The default can be set to the index of one of the
options
.
options
is an array of options for the select form field to display. Each option should be an object with aname
(string). You may optionally add agroup
to some or all of your options.
Example select field
{
"key": "transportation",
"type": "select",
"label": "How do you get around in the city",
"options": [
{
"name": "Car"
},
{
"name": "Helicopter"
},
{
"name": "Sport Utility Vehicle"
},
{
"name": "Bicycle",
"group": "low emissions"
},
{
"name": "Skateboard",
"group": "low emissions"
},
{
"name": "Walk",
"group": "low emissions"
},
{
"name": "Bus",
"group": "low emissions"
},
{
"name": "Scooter",
"group": "low emissions"
},
{
"name": "Train",
"group": "low emissions"
},
{
"name": "Hot Air Baloon",
"group": "low emissions"
}
]
}
The number field allows input that is restricted to numbers. Browsers also provide minimal ui to increase and decrease the current value.
min
sets minimum acceptable value for the input.
max
sets maximum acceptable value for the input.
minlength
sets minimum number of characters for the input. If a number less than this value it will not be submitted with the form. eg 1000 is 4 characters long and ifminlength
is set to 5, it would not be sent. Currently there is no error displayed to the user if they do not meet the requirement.
maxlength
sets maximum number of characters for the input. If a number is greater than this value it will not be submitted with the form. eg 1000 is 4 characters long and ifmaxlength
is set to 2, it would not be sent. Currently there is no error displayed to the user if they do not meet the requirement.
Example number field
{
"key": "love",
"type": "number",
"label": "How much love?",
"default": 2,
"min": 0,
"max": 100,
"required": true
}
The password field allows password input, it uses an input with
type='password'
.
Example password field
{
"key": "password",
"type": "password",
"label": "Password"
}
Hidden form field
The hidden field allows hidden input, it uses an input with
type='hidden'
.
Example password field
{
"key": "hiddenCode",
"type": "hidden",
"default": "hidden_code"
}
The email field allows email input, it uses an input with
type='email'
. Browsers will provide basic email address validation by default.
Example password field
{
"key": "email",
"type": "email",
"placeholder": "janedoe@gmail.com"
}
You can configure formly to use custom templates for specified types (your own "text" template) by injecting the formlyTemplateProvider
in your app's config
function. The formlyTemplateProvider
has the following functions:
Allows you to set a template
formlyTemplateProvider.setTemplateUrl('radio', 'views/custom-formly-radio.html');
formlyTemplateProvider.setTemplateUrl('checkbox', 'views/custom-formly-checkbox.html');
// the same can be accomplished with
formlyTemplateProvider.setTemplate({
radio: 'views/custom-formly-radio.html',
checkbox: 'views/custom-formly-checkbox.html'
});
Allows you to get the template
formlyTemplateProvider.setTemplateUrl('radio', 'views/custom-formly-radio.html');
formlyTemplateProvider.getTemplateUrl('radio') === 'views/custom-formly-radio.html'; // true
git checkout master
- run
npm install && bower install
- test your code using
grunt dev
which hosts the app athttp://localhost:4000
- commit your changes
- run
- update README, CHANGELOG, bower.json, and do any other final polishing to prepare for publishing
- git commit changes
grunt dev
: Creates a server for testing athttp://0.0.0.0:4000
grunt publish
: Copies the src folder and bower_components to gh-pages