{"_id":"56d91c5607ae190b0000446c","project":"5515ba4981faf83900d2b10c","version":{"_id":"56d91c5507ae190b00004460","__v":1,"project":"5515ba4981faf83900d2b10c","createdAt":"2016-03-04T05:25:41.052Z","releaseDate":"2016-03-04T05:25:41.052Z","categories":["56d91c5507ae190b00004464","56d91c5507ae190b00004465","56d91c5507ae190b00004466","56d91c5507ae190b00004467","56d91c5507ae190b00004468"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"8.0.0","version":"8.0.0"},"user":"54e3723b8ef7552300409bf4","__v":1,"category":{"_id":"56d91c5507ae190b00004464","__v":1,"project":"5515ba4981faf83900d2b10c","pages":["56d91c5607ae190b00004469","56d91c5607ae190b0000446a","56d91c5607ae190b0000446b","56d91c5607ae190b0000446c","56d91c5607ae190b0000446d","56d91c5607ae190b0000446e","56d91c5607ae190b0000446f","56d91c5607ae190b00004470","56d91c5607ae190b00004471","56d91c5607ae190b00004472","56d91c5607ae190b00004473","56d91c5607ae190b00004474","56d91c5607ae190b00004475","56d91c5607ae190b00004476"],"version":"56d91c5507ae190b00004460","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-03-27T20:15:06.295Z","from_sync":false,"order":0,"slug":"guides","title":"Guides"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-03-27T20:21:13.402Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"You can create your own templates with `formlyConfig` in your `run` function (or `formlyConfigProvider` in a config function). This is the recommended approach if you want to customize your templates at all.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Prebuilt Templates\"\n}\n[/block]\nWhile it is recommended to create your own templates for ultimate customization and flexibility, there are prebuilt templates you can use:\n\n - [Vanilla HTML](https://github.com/formly-js/angular-formly-templates-vanilla)\n - [Bootstrap](https://github.com/formly-js/angular-formly-templates-bootstrap)\n - [LumX](https://github.com/formly-js/angular-formly-templates-lumx)\n - [Ionic](https://github.com/formly-js/angular-formly-templates-ionic)\n - [angular-material](https://github.com/formly-js/angular-formly-templates-material) (WIP)\n - [Foundation](https://github.com/formly-js/angular-formly-templates-foundation): (WIP, owner needed)\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Creating a Custom Template\"\n}\n[/block]\nCreating a custom template is quite easy, but also very flexible. It can be as simple as:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"formlyConfig.setType({\\n  name: 'input',\\n  template: '<input ng-model=\\\"model[options.key]\\\" />'\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nor as complex as\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"formlyConfig.setType({\\n  name: 'ipAddress',\\n  extends: 'input',\\n  wrapper: 'someWrapper',\\n  defaultOptions: {},\\n  link: function(scope, el, attrs) {},\\n  controller: function($scope, yourInjectableThing) {},\\n  apiCheck: {}\\n  // and more...\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nThen someone would use your type like so:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// in a controller\\nthis.fields = [\\n  {\\n    type: 'ipAddress',\\n    // other stuff\\n  }\\n];\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nYou have a lot of freedom when it comes to writing templates. You don't even need to use the `model` which means that you can have fields that are just part of the look and feel of your form. Because of angular-formly's [ngModelAttrsTemplateManipulator](#ngmodelattrstemplatemanipulator), you really only have to put the `ng-model` element where you want it (if you want it at all) and formly will take care of most of the rest. If you want to have any extra properties, you have pretty much full reign over the `options.templateOptions` object. Just be aware that angular-formly does make use of common parameters like `required` or `onClick` to automatically add attributes to `ng-model` elements. See [formlyConfig](doc:formlyconfig) for more information.\n\n# formlyConfig.setType options\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Option\",\n    \"h-1\": \"Data Type(s)\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"name\",\n    \"0-1\": \"string\",\n    \"0-2\": \"How you reference the type for a specific field.\",\n    \"1-0\": \"template\",\n    \"1-1\": \"string\",\n    \"1-2\": \"Inlined template for the type. Can only be specified if there is no templateUrl\",\n    \"2-0\": \"templateUrl\",\n    \"2-1\": \"string\",\n    \"2-2\": \"The URL for a template (uses the `$templateCache`). Can only be specified if there is no template.\",\n    \"3-0\": \"defaultOptions\",\n    \"3-1\": \"object (must be valid field config)\",\n    \"3-2\": \"This will be merged with the options the user of the type provides (so they can override these options).\",\n    \"4-0\": \"wrapper\",\n    \"4-1\": \"string || array of strings\",\n    \"4-2\": \"The name of a wrapper that has been registered with angular-formly\",\n    \"5-0\": \"controller\",\n    \"5-1\": \"controller name || controller function\",\n    \"5-2\": \"Provides you the ability to add custom behavior to the type without having to make an entire directive (you can make a directive instead if you wish).\",\n    \"6-0\": \"link\",\n    \"6-1\": \"function(scope, el, attrs)\",\n    \"6-2\": \"Provides the ability to manipulate the DOM of the field\",\n    \"7-0\": \"apiCheck\",\n    \"7-1\": \"object of functions\",\n    \"7-2\": \"angular-formly uses [apiCheck](https://github.com/kentcdodds/apiCheck.js) for validating options. You can enforce the API to your type this way.\",\n    \"8-0\": \"apiCheckInstance\",\n    \"8-1\": \"Instance of apiCheck\",\n    \"8-2\": \"Your own instance of apiCheck so you have the correct prefix/suffix/url/etc.\",\n    \"9-0\": \"apiCheckFunction\",\n    \"9-1\": \"`'throw'` or `'warn'`\",\n    \"9-2\": \"Defaults to `'warn'`. If you specify `'throw'` then an error will be thrown instead of `'warn'`\",\n    \"10-0\": \"apiCheckOptions\",\n    \"10-1\": \"object\",\n    \"10-2\": \"The options to use when the check fails. Defaults to something sensible.\",\n    \"11-0\": \"validateOptions\",\n    \"11-2\": \"Note: It is recommended that you use `apiCheck` with `apiCheckInstance` rather than `validateOptions`.\\n\\nThis function will be invoked with the options of the field after it has been merged with it's `optionsDefaults` and\\nany types that its type `extends`. Feel free to log warnings to the console or throw errors here to help users use your\\ntypes correctly. Recommended: Use [apiCheck.js](https://github.com/kentcdodds/apiCheck.js) as this is what formly uses\\nand will already be available to you.\",\n    \"11-1\": \"function(options)\"\n  },\n  \"cols\": 3,\n  \"rows\": 12\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Template's $scope\"\n}\n[/block]\nSee [this example](http://formly-js.github.io/angular-formly/#/example/custom-types/custom-templates) for an example what's accessible on the template's scope for your custom types.\n\nHere's what you have available on the `$scope` of your templates:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Variable Name\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"options\",\n    \"0-1\": \"The data provided to configure the field. As a template author, if you need custom properties, you use the `templateOptions` property on this object. Note, there are a few things that get added to your field configuration (and hence, these options). One of these is \\\"formControl\\\" which can be used to display errors to the user (for example).\",\n    \"1-0\": \"to\",\n    \"1-1\": \"Shortcut to `options.templateOptions`\",\n    \"2-0\": \"fc\",\n    \"2-1\": \"Shortcut to `options.formControl`\",\n    \"4-0\": \"id\",\n    \"4-1\": \"The id of the field. You shouldn't have to use this.\",\n    \"5-1\": \"The index of the field the form is on (in ng-repeat)\",\n    \"5-0\": \"index\",\n    \"6-0\": \"form\",\n    \"7-0\": \"model\",\n    \"6-1\": \"the form controller the field is in\",\n    \"7-1\": \"the model of the form (or the model specified by the field if it was specified).\",\n    \"8-0\": \"fields\",\n    \"8-1\": \"all the fields for the form\",\n    \"9-0\": \"formState\",\n    \"9-1\": \"The object passed as `options.formState` to the `formly-form` directive. Use this to share state between fields.\",\n    \"3-0\": \"showError\",\n    \"3-1\": \"Shortcut to `options.validation.errorExistsAndShouldBeVisible`\"\n  },\n  \"cols\": 2,\n  \"rows\": 10\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<hr />\\n<a href=\\\"https://app.codesponsor.io/link/PKGFLnhDiFvsUA5P4kAXfiPs/formly-js/angular-formly\\\" rel=\\\"nofollow\\\"><img src=\\\"https://app.codesponsor.io/embed/PKGFLnhDiFvsUA5P4kAXfiPs/formly-js/angular-formly.svg\\\" style=\\\"width: 888px; height: 68px;\\\" alt=\\\"Sponsor\\\" /></a>\\n\"\n}\n[/block]","excerpt":"angular-formly types for CSS frameworks","slug":"custom-templates","type":"basic","title":"Custom Templates"}

Custom Templates

angular-formly types for CSS frameworks

You can create your own templates with `formlyConfig` in your `run` function (or `formlyConfigProvider` in a config function). This is the recommended approach if you want to customize your templates at all. [block:api-header] { "type": "basic", "title": "Prebuilt Templates" } [/block] 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) - [Ionic](https://github.com/formly-js/angular-formly-templates-ionic) - [angular-material](https://github.com/formly-js/angular-formly-templates-material) (WIP) - [Foundation](https://github.com/formly-js/angular-formly-templates-foundation): (WIP, owner needed) [block:api-header] { "type": "basic", "title": "Creating a Custom Template" } [/block] Creating a custom template is quite easy, but also very flexible. It can be as simple as: [block:code] { "codes": [ { "code": "formlyConfig.setType({\n name: 'input',\n template: '<input ng-model=\"model[options.key]\" />'\n});", "language": "javascript" } ] } [/block] or as complex as [block:code] { "codes": [ { "code": "formlyConfig.setType({\n name: 'ipAddress',\n extends: 'input',\n wrapper: 'someWrapper',\n defaultOptions: {},\n link: function(scope, el, attrs) {},\n controller: function($scope, yourInjectableThing) {},\n apiCheck: {}\n // and more...\n});", "language": "javascript" } ] } [/block] Then someone would use your type like so: [block:code] { "codes": [ { "code": "// in a controller\nthis.fields = [\n {\n type: 'ipAddress',\n // other stuff\n }\n];", "language": "javascript" } ] } [/block] You have a lot of freedom when it comes to writing templates. You don't even need to use the `model` which means that you can have fields that are just part of the look and feel of your form. Because of angular-formly's [ngModelAttrsTemplateManipulator](#ngmodelattrstemplatemanipulator), you really only have to put the `ng-model` element where you want it (if you want it at all) and formly will take care of most of the rest. If you want to have any extra properties, you have pretty much full reign over the `options.templateOptions` object. Just be aware that angular-formly does make use of common parameters like `required` or `onClick` to automatically add attributes to `ng-model` elements. See [formlyConfig](doc:formlyconfig) for more information. # formlyConfig.setType options [block:parameters] { "data": { "h-0": "Option", "h-1": "Data Type(s)", "h-2": "Description", "0-0": "name", "0-1": "string", "0-2": "How you reference the type for a specific field.", "1-0": "template", "1-1": "string", "1-2": "Inlined template for the type. Can only be specified if there is no templateUrl", "2-0": "templateUrl", "2-1": "string", "2-2": "The URL for a template (uses the `$templateCache`). Can only be specified if there is no template.", "3-0": "defaultOptions", "3-1": "object (must be valid field config)", "3-2": "This will be merged with the options the user of the type provides (so they can override these options).", "4-0": "wrapper", "4-1": "string || array of strings", "4-2": "The name of a wrapper that has been registered with angular-formly", "5-0": "controller", "5-1": "controller name || controller function", "5-2": "Provides you the ability to add custom behavior to the type without having to make an entire directive (you can make a directive instead if you wish).", "6-0": "link", "6-1": "function(scope, el, attrs)", "6-2": "Provides the ability to manipulate the DOM of the field", "7-0": "apiCheck", "7-1": "object of functions", "7-2": "angular-formly uses [apiCheck](https://github.com/kentcdodds/apiCheck.js) for validating options. You can enforce the API to your type this way.", "8-0": "apiCheckInstance", "8-1": "Instance of apiCheck", "8-2": "Your own instance of apiCheck so you have the correct prefix/suffix/url/etc.", "9-0": "apiCheckFunction", "9-1": "`'throw'` or `'warn'`", "9-2": "Defaults to `'warn'`. If you specify `'throw'` then an error will be thrown instead of `'warn'`", "10-0": "apiCheckOptions", "10-1": "object", "10-2": "The options to use when the check fails. Defaults to something sensible.", "11-0": "validateOptions", "11-2": "Note: It is recommended that you use `apiCheck` with `apiCheckInstance` rather than `validateOptions`.\n\nThis function will be invoked with the options of the field after it has been merged with it's `optionsDefaults` and\nany types that its type `extends`. Feel free to log warnings to the console or throw errors here to help users use your\ntypes correctly. Recommended: Use [apiCheck.js](https://github.com/kentcdodds/apiCheck.js) as this is what formly uses\nand will already be available to you.", "11-1": "function(options)" }, "cols": 3, "rows": 12 } [/block] [block:api-header] { "type": "basic", "title": "Template's $scope" } [/block] See [this example](http://formly-js.github.io/angular-formly/#/example/custom-types/custom-templates) for an example what's accessible on the template's scope for your custom types. Here's what you have available on the `$scope` of your templates: [block:parameters] { "data": { "h-0": "Variable Name", "h-1": "Description", "0-0": "options", "0-1": "The data provided to configure the field. As a template author, if you need custom properties, you use the `templateOptions` property on this object. Note, there are a few things that get added to your field configuration (and hence, these options). One of these is \"formControl\" which can be used to display errors to the user (for example).", "1-0": "to", "1-1": "Shortcut to `options.templateOptions`", "2-0": "fc", "2-1": "Shortcut to `options.formControl`", "4-0": "id", "4-1": "The id of the field. You shouldn't have to use this.", "5-1": "The index of the field the form is on (in ng-repeat)", "5-0": "index", "6-0": "form", "7-0": "model", "6-1": "the form controller the field is in", "7-1": "the model of the form (or the model specified by the field if it was specified).", "8-0": "fields", "8-1": "all the fields for the form", "9-0": "formState", "9-1": "The object passed as `options.formState` to the `formly-form` directive. Use this to share state between fields.", "3-0": "showError", "3-1": "Shortcut to `options.validation.errorExistsAndShouldBeVisible`" }, "cols": 2, "rows": 10 } [/block] [block:html] { "html": "<hr />\n<a href=\"https://app.codesponsor.io/link/PKGFLnhDiFvsUA5P4kAXfiPs/formly-js/angular-formly\" rel=\"nofollow\"><img src=\"https://app.codesponsor.io/embed/PKGFLnhDiFvsUA5P4kAXfiPs/formly-js/angular-formly.svg\" style=\"width: 888px; height: 68px;\" alt=\"Sponsor\" /></a>\n" } [/block]