angular-formly
Advanced tools
AngularJS directive which takes JSON representing a form and renders to HTML
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
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 --save
Include the javascript file in your index.html, Formly comes in the following flavors:
Vanilla: no fancy styling, just plain html
<script src="bower_components/angular-formly/dist/formly.min.js"></script>
<script src="bower_components/angular-formly/dist/formly.bootstrap.min.js"></script>
DIY: You can create your own templates with formlyTemplateProvider! Use any of the builds above and override all the templates or just the ones you need.
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
description: 'Descriptive text'
},
{
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. Note, you can configure this on a form-by-form basis as shown in the example, or globally using the formlyOptionsProvider.
uniqueFormIdis used to identify the form.
hideSubmithides the submit button when set totrue. Defaults to false.
submitCopycustomizes the submit button copy. Defaults to 'Submit'.
submitButtonTemplatecustomizes the template used for the submit button. Compiled on the scope, so you have access to all other options (and any custom options) in your custom template.
When constructing fields use the options below to customize each field object. You must set at least a type, template, or templateUrl.
typeis the type of field to be rendered. Either type, template, or templateUrl must be set.
null
text,textarea,radioselectnumbercheckbox,password,hidden,
templatecan be set instead oftypeortemplateUrlto use a custom html template form field. Should be used with one-liners mostly (like a directive). Useful for adding functionality to fields.
undefined
templateUrlcan be set instead oftypeortemplateto 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
labelis used to add an html label to each field.
A default is set for each field based on its type. ie
Text,Checkbox,Password
requiredis used to add the required attribute to a form field.
undefined
requiredExpressionis used to conditionally require the input. Evaluates on theresultand uses therequiredproperty on the field.
undefined
hideExpressionis used to conditionally show the input. Evaluates on theresultand uses thehideproperty on the field.
undefined
hideis used to conditionally show the input. When true, the input is hidden (meant to be used with a watch).
undefined
disabledis used to add the disabled attribute to a form field.
undefined
placeholderis used to add placeholder text to some inputs.
undefined
descriptionis used to add descriptive text to all inputs.
undefined
watchhas two properties calledexpressionandlistener. Thewatch.expressionis added to the formly directive's scope. If it's a function, it will be wrapped and called with the field as the first argument, followed by the normal arguments for a watcher. Thelistenerwill also be wrapped and called with the field as the first argument, followed by hte normal arguments for a watch listener.
For example:
// normal watcher
$scope.$watch(function expression(theScope) {}, function listener(newValue, oldValue, theScope) {});
// field watcher
$scope.$watch(function expression(field, theScope) {}, function listener(field, newValue, oldValue, theScope) {});
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.
linessets 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
valueof one of theoptions.
optionsis 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.
optionsis an array of options for the select form field to display. Each option should be an object with aname(string). You may optionally add agroupto 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.
minsets minimum acceptable value for the input.
maxsets maximum acceptable value for the input.
minlengthsets 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 ifminlengthis set to 5, it would not be sent. Currently there is no error displayed to the user if they do not meet the requirement.
maxlengthsets 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 ifmaxlengthis 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'.
Unlike other formly fields, which use Angular's default setting to trim leading and trailing whitespace, the password field captures whitespace. You can override this by setting trimWhitespace to true.
Example password field
{
"key": "password",
"type": "password",
"label": "Password"
}
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
You can configure default options for all forms using the formlyOptionsProvider in your app's config function. The following options are used by angular-formly and are available for configuration:
ng-if for hiding fields (rather than ng-hide). Useful for removing watchers. Defaults to false (use ng-hide)To change these defaults globally, you have the following api:
Allows you to set an option
formlyOptionsProvider.setOption('useNgIfToHide', true);
formlyOptionsProvider.setOption('submitCopy', 'Save');
// the same can be accomplished with
formlyOptionsProvider.setOption({
submitCopy: 'Save',
useNgIfToHide: true
});
Returns a copy of the current options. This is used internally.
Please see the Wiki for tips and tricks from the community.
git checkout master
npm install && bower installgrunt dev which hosts the app at http://localhost:4000grunt dev: Creates a server for testing at http://0.0.0.0:4000grunt publish: Copies the src folder and bower_components to gh-pagesWhen submitting a Pull Request please submit it to the master branch.
Please do the following:
FAQs
AngularJS directive which takes JSON representing a form and renders to HTML
The npm package angular-formly receives a total of 3,093 weekly downloads. As such, angular-formly popularity was classified as popular.
We found that angular-formly demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.