alihasanimam/angular-dynamic-inputs

Build Inputs in AngularJS From Nothing But JSON

angular-dynamic-inputs

Build Inputs in AngularJS From Nothing But JSON

Uses the MIT License. See LICENSE file for details.

Installation

1. Clone the project from GitHub
2. Copy angular-dynamic-inputs.js or angular-dynamic-inputs.min.jsinto your project wherever your other assets reside.

Use

As with any other AngularJS module:

• include the script into your page anywhere after AngularJS itself, using whichever mechanism you use for including scripts in your project:

    <script src="your_assests_directory/angular-dynamic-inputs.js"></script>

    require('angular-dyninputs');

• INTERNET EXPLORER: This project (as with most of Angular itself) WILL NOT work properly with IE 6 or 7. Some of the functionality can be coerced into working, but much of it will simply be broken. radio fields, for example, will have every member selected. This may be fixed in a future version, but as it's 2014, IE 6 and 7 are very low priorities, especially with XP reaching end of life. IE 8 will work, with a bit of extra setup (you can try this for IE 6 and 7 as well, but again, they probably won't work):

    <!--[if lte IE 8]>
        <script src="https://cdnjs.cloudflare.com/ajax/libs/json3/3.3.1/json3.min.js"></script>
        <script src="https://cdnjs.cloudflare.com/ajax/libs/es5-shim/2.3.0/es5-shim.min.js"></script>
        <script>
            document.createElement('ng-include');
            document.createElement('ng-pluralize');
            document.createElement('ng-view');
            document.createElement('ng-form');
            document.createElement('dynamic-input');
            
            // Optionally these for CSS
            document.createElement('ng:include');
            document.createElement('ng:pluralize');
            document.createElement('ng:view');
            document.createElement('ng:form');
            
            // IE doesn't always run the bootstrap on its own...
            $(document).ready(function() {
              angular.bootstrap(document.documentElement);
            });
        </script>
    <![endif]-->

• inject dyninput as a dependency of your project.

    appModule = angular.module('app', ['dyninput']);

• create a dynamic-input element anywhere in your page.

    <dynamic-input template="inputTemplate"
        ng-model="inputData">
    </dynamic-input>

• populate your template with a JSON array describing the input you want to create.

    $scope.inputData = {};   // JavaScript needs an object to put our form's models into.
    
    $scope.inputTemplate = [
        {
            "type": "text",
            "label": "First Name",
            "model": "name.first"
        },
        {
            "type": "text",
            "label": "Last Name",
            "model": "name.last"
        },
        {
            "type": "email",
            "label": "Email Address",
            "model": "email"
        },
        {
            "type": "submit",
            "model": "submit"
        },
    ];

And that's about it! Check out the demo for a more robust example, or keep reading to learn about all of the things you can do with this module.

The TL;DR Version

The Directive

You invoke the dynamic-input directive using an element (<dynamic-input></dynamic-input>) - other options (such as class, attribute, and comment) are unsupported (for now). The directive requires two attributes: an [model][], and either a template or a template-url. The [model][] will be used to generate valid ng-model attributes for the various input controls in the template. You must initialize this model to an object, or your app will break.

If you specify a template-url, the dynamic-input directive will retrieve the form template via $http and build out your form based on the response. Currently, failure is silently ignored. This may change in a later release.

You may not want to rely on the directive to retrieve your input directly - perhaps you want to do some processing on the server response before passing it to the directive for building, or maybe you need to specify a more complex $http request with advanced authentication. Or perhaps you just want to proactively handle failure to retrieve the template. Enter the template attribute. When the directive sees template, it ignores any template-url and instead uses the array identified by the template attribute. (See below for more details on this value.) At some point in the future you will also be able to dynamically update this array, and the changes will automatically be reflected in the DOM. This is currently unsupported, however, and for technical reasons, will likely not be supported at all for templateUrl arrays.

Any other attributes you specify on the dynamic-input element are copied across to the input element.

The dynamic-input directive makes every attempt to set up the input it generates to be valid HTML inputs, complete with the ability to have their data submitted to the server by the browser's native form submission mechanism and still have the data in the same structure that it takes on in your AngularJS models. This makes it easy to implement a fallback mode in case there is a problem with using the standard Angular methods to handle your form inputs. You will, of course, need to provide your own action and method attributes for this to work completely.

The Template

Regardless of whether it arrives via template or template-url, the form template is a fairly-straightforward JavaScript array/object. Each index/key of the template value (referred to elsewhere in this README as an ID) serves as the name and ng-model (where applicable) of the control described in the corresponding value. Each of the values, then, is an object describing a form input control. A type key identifies what kind of control to build, which in turn determines what other keys are expected. Any type that isn't supported builds a <span> containing the value of the label key, if one exists, as its content, and any other keys as attributes.

Supported Control Types

Following is a list of all currently-supported types, and then a more detailed specification of each. Links to Angular documentation in the specifications below indicate that values will be added to the Angular-defined attributes mentioned, and that Angular provides the actual functionality described there. Note that not all of these types are properly supported in all browsers, yet; there are a number of references around the web for which browsers support what.

Common Options

• attributes: key-value pairs for arbitrary attributes not otherwise supported here; it is strongly recommended that you use this option only if the attribute you need isn't already supported, as any attributes specified here bypass any enhancements this module provides.

• class: see ng-class

• callback: see ng-change (or ng-click for button-like types)

• disabled: see ng-disabled

• label: wraps the control in a <label> tag with the value as text content (but see specific types for exceptions to how this is handled)

• The following options are only supported for types that have values:

  • model: overrides the control's ID as the value of [model][] and name attributes; allows multiple controls to be tied to a single model - you can nest your models further by using dot notation in the value
  • readonly: see ng-readonly
  • required: see ng-required
  • val: an initial value for the model

• button

• checkbox

• checklist

• color

• date

• datetime

• datetime-local

• email

• fieldset

• file

• hidden

• image

• legend

• month

• number

• password

• radio

• range

• reset

• search

• select

• submit

• tel

• text

• textarea

• time

• url

• week

button

• Renders: <button></button>
• Additional Options:
  • None
• Other Notes:
  • The value of label is used as the content of the <button> itself; no additional elements are created

checkbox

• Renders: <input type="checkbox">
• Additional Options:
  • isOn: see ng-true-value
  • isOff: see ng-false-value
  • slaveTo: see ng-checked
• Other Notes:
  • See also the checklist type, below

checklist

• Renders: multiple <input type="checkbox"> controls
• Additional Options:
  • options: an object containing a collection of child objects, each describing a checkbox
    • The key of each child object specifies the key to associate with the checkbox it describes
    • class: applies a specific ng-class to the current checkbox, independently of the rest
    • label: operates identically to the standard label option, but applies to a specific checkbox in the list
    • See the checkbox type for other fields supported here
• Other Notes:
  • This is a convenience type, used to tie a group of checkbox controls together under a single model; the model holds an object, and each control sets a separate key within it
  • You can set a val on the entire checklist (it must, of course, be an object) in addition to any per-option vals; the per-option versions are set after the full checklist version, so they will override anything set to their key by the checklist itself

color

• Renders: <input type="color">
• Additional Options:
  • None
• Other Notes:
  • May not be supported in all browsers

date

• Renders: <input type="date">
• Additional Options:
  • See text below
• Other Notes:
  • May not be supported in all browsers

datetime

• Renders: <input type="datetime">
• Additional Options:
  • See text below
• Other Notes:
  • May not be supported in all browsers

datetime-local

• Renders: <input type="datetime-local">
• Additional Options:
  • See text below
• Other Notes:
  • May not be supported in all browsers

email

• Renders: <input type="email">
• Additional Options:
  • See text below
• Other Notes:
  • On devices that have on-screen keyboards, the browser may modify the keyboard layout to make entering email addresses in these controls easier.

fieldset

• Renders: <fieldset></fieldset>
• Additional Options:
  • fields: the template for the fields which should appear in the fieldset
• Other Notes:
  • The value of label is used to create a <legend> tag as the first child of the fieldset

file

• Renders: <input type="file">
• Additional Options:
  • multiple: whether or not the user can select more than one file at a time with this single control
• Other Notes:
  • A directive is included with this module that allows file controls to properly bind to AngularJS models - the control's FileList object is stored in the model, and updating the model's value with a valid FileList object will update the control accordingly
  • Also included is an AngularJS service that wraps the browser's FileReader in a promise, so you can get the contents of the selected file for further manipulation, or even send it along in an AJAX request, and all without leaving AngularJS
  • Both of these additions are modified versions of code by K. Scott Allen and made available on the OdeToCode website; the original versions are linked above

hidden

• Renders: <input type="hidden">
• Additional Options:
  • None
• Other Notes:
  • Because the underlying HTML control has so little functionality, this control only supports model and val keys

image

• Renders: <input type="image">
• Additional Options:
  • source: the URL of the image to display in this control
• Other Notes:
  • The value of label is used to set the alt attribute of this control

legend

• Renders: <legend></legend>
• Additional Options:
  • None
• Other Notes:
  • As a display-only control, only class, label, callback (via ng-click) and disabled are supported on this control
  • The value of label is used to set the contents of this control

month

• Renders: <input type="month">
• Additional Options:
  • See text below
• Other Notes:
  • May not be supported in all browsers

number

• Renders: <input type="number">
• Additional Options:
  • maxValue: the largest allowed value for this control
  • minValue: the smallest allowed value for this control
  • step: the amount by which the control can increase or decrease in value
  • Also see text below
• Other Notes:
  • May not be supported in all browsers

password

• Renders: <input type="password">
• Additional Options:
  • See text below
• Other Notes:
  • The only real difference between this control and a text control is in the rendering, so they support exactly the same options (with the exception of splitBy, since it makes no sense to split obscured-input strings)

radio

• Renders: multiple <input type="radio"> controls
• Additional Options:
  • values: an object which acts as a simple list of radio options to include
    • The key of each property of this option specifies the value the model should be set to when the associated radio input is selected
    • The value of each property of this option specifies the label to use for the associated radio input
• Other Notes:
  • Because a single radio input by itself isn't particularly useful in most cases, this control type assumes users will want to define a list of value:label pairs tied to a single model; if this is incorrect, you can still create radio controls with just one value:label each, and then tie them together using the model key
  • The directive doesn't prevent you from applying a label to the entire collection of input controls created by this control type - the entire div containing them will be wrapped in a <label> tag; keep this in mind when building style sheets

range

• Renders: <input type="range">
• Additional Options:
  • step: the amount by which the control can increase or decrease in value
  • Also see number above
• Other Notes:
  • By default, this control seems to provide its values to AngularJS as strings. This might be due to Angular (as well as the browser) handling them as regular text controls internally. Among its other minor tweaks, this module contains a very simple directive to override the default $parsers mechanism for range controls and convert these values back to numbers (floats, in case your step is not an integer).
  • May not be supported in all browsers

reset

• Renders: <button type="reset"></button>
• Additional Options:
  • None
• Other Notes:
  • As with button, the value of label provides the control's contents
  • AngularJS doesn't seem to monitor the reset event, so your models wouldn't normally be updated when the form is cleared in this way; while this control is strongly dis-recommended in most cases, this directive supports it, so code is included that monitors and properly handles these events (NOTE - this feature has not been widely tested; please report any issues on GitHub or Bitbucket)

search

• Renders: <input type="search">
• Additional Options:
  • See text below
• Other Notes:
  • All browsers support this because it works exactly like a text control. The idea is that search boxes will be styled differently, and on some devices might even support additional input methods, such as voice recognition. You'll probably want to tie these controls to some kind of search mechanism in your app, since users whose browsers do render them differently will expect them to act accordingly.

select

• Renders: <select></select>
• Additional Options:
  • autoOptions: see ng-options
  • empty: if not false or undefined, specifies the display value (contents) of an empty option, and tells the directive to include it in its output
  • multiple: if not false or undefined, allows the user to select more than one option at one time
  • options: an object containing a collection of child objects, each describing an option to include in the select list
    • The key of each child object gives the value of the associated option
    • disabled: see ng-disabled
    • group: adds the option to an optgroup whose label is the value of the group key
    • label: the display value (contents) of the option
    • slaveTo: see ng-selected
• Other Notes:
  • An unreleased prototype version of this module (which used a combination of ng-repeat and ng-switch instead of a directive) specified four different control types for the functionality provided by this one - one for normal lists, one for grouped lists, one for multi-select lists, and one that combined multi-select with group support; this version is much cleaner about its approach - multi-select is the 'flag' option multiple, and groups are enabled by simply defining them with their associated values
  • Note that only one of options and autoOptions will be honored by this module - if you specify autoOptions, options is completely ignored; keep this in mind when building your forms because the actual values will have to be specified in a separate object

submit

• Renders: <button type="submit"></button>
• Additional Options:
  • None
• Other Notes:
  • As with button, the value of label provides the control's contents

tel

• Renders: <input type="tel">
• Additional Options:
  • See text below
• Other Notes:
  • There is currently no validation support for this control in nearly any browser, and AngularJS doesn't provide any by default. This is mostly because telephone numbers are tricky beasts, especially with the differences between how these numbers are allocated from one part of the world to another. And that's before we start getting messy with things like VoIP "numbers".

text

• Renders: <input type="text">
• Additional Options:
  • maxLength: see ng-maxlength
  • minLength: see ng-minlength
  • placeholder: a value to display in a text-like control when it is empty
  • splitBy: see ng-list (this option is only supported by text and textarea controls)
  • validate: see ng-pattern
• Other Notes:
  • This control serves as the base template for nearly all the other form input controls defined by HTML - as such, most of the controls supported by this directive support these options as well, leading their entries to refer here

textarea

• Renders: <textarea></textarea>
• Additional Options:
  • See text above
• Other Notes:
  • While the syntax used to define them in raw HTML differs to some extent, the only practical difference between text and textarea controls is the multi-line support offered by textarea - therefore, the options available to each are identical

time

• Renders: <input type="time">
• Additional Options:
  • See text above
• Other Notes:
  • May not be supported in all browsers

url

• Renders: <input type="url">
• Additional Options:
  • See text above
• Other Notes:
  • Similar to the email type, some browsers will alter on-screen keyboards when this control type is selected in such a way that URL entry is simplified; AngularJS, meanwhile, enforces the requirement that the value be a valid URL, even if the browser does not

week

• Renders: <input type="week">
• Additional Options:
  • See text above
• Other Notes:
  • May not be supported in all browsers

Acknowledgements

This is a fork of danhunsaker's Angular Dynamic Forms project. All credits goes to him for his excellent works.

Alternatives

If this project isn't for you (it's not very mature, yet, so there are plenty of reasons it may not be a good fit for your projects, yet), there are some other ways to go about the same basic thing. They each have their own benefits and drawbacks, but I'll let their own developers speak to those, especially as I haven't tested any, yet. Here are a few; let me know if you're aware of others:

• Angular Dynamic Forms - My library is based on this project. All the codes of this library was forked from it to render only input fields, instead of generating fully functional dynamic form.
• JSON Form - A jQuery-based library for converting JSON Schemas into HTML forms; a mature option with many advanced features, though centered around Twitter Bootstrap.
• Angular Schema Form - An Angular implementation of (not wrapper for) JSON Form.
• Alpaca - Another jQuery-based library, it boasts many of the same features as JSON Form.
• MetaWidget - Apparently automated, based on existing infrastructure, rather than controlled by code. Boasts compatibility with many languages and frameworks, including AngularJS, Java Swing, native Android, and others.
• inputEx - A YUI3 library offering.
• "The Other" ADF - Wallace Breza's project with the same name this one started with.

Issues And Assistance